xtc_proc.h

/*-
 * Copyright (c) 2026, The XTC Project
 * @stability stable
 * Use of this source code is governed by the ISC License.
 *
 * src/inc/xtc_proc.h
 *      Lightweight processes with mailboxes, selective receive,
 *      links, monitors, and explicit exit.  M8 ships the core; the
 *      `xtc_orc` supervisor (M10) sits on top of these primitives.
 *
 *      A process is a coroutine with identity (xtc_pid_t) plus a
 *      mailbox.  Send is fire-and-forget; the message is copied into
 *      an envelope owned by the mailbox.  Receive is selective: the
 *      caller supplies a match function, and envelopes that don't
 *      match are kept in arrival order in a save queue and re-tested
 *      on the next receive.
 */
 
#ifndef XTC_PROC_H
#define XTC_PROC_H
 
#include "xtc_export.h"
 
#include <stddef.h>
#include <stdint.h>
 
#include "xtc.h"
#include "xtc_loop.h"
#include "xtc_async.h"
#include "xtc_exec.h"   /* xtc_exec_class_t for xtc_proc_opts_t.sched_class */
 
/*
 * Process identifier (16 bytes; 2.0).  Encodes the loop ID, a per-loop
 * slot index, and the slot's generation, so a stale pid (after a
 * process exits and its slot is reused) is recognisably stale on
 * lookup.  The slot index is 32 bits (a loop holds as many live procs as
 * memory and the xtc_res caps allow), and the generation is 64 bits per
 * slot, so it never wraps: a pid held across any number of reuses of
 * its slot never names the new occupant.  Compare with xtc_pid_eq, not
 * memcmp (padding-free today, but that is not part of the contract).
 */
typedef struct xtc_pid {
        uint32_t loop_id;   /* 0 standalone loop, else xtc_exec slot + 1 */
        uint32_t local_id;  /* slot in the loop's proc table */
        uint64_t gen;       /* slot generation, 1.. (0 only in XTC_PID_NONE) */
} xtc_pid_t;
 
#define XTC_PID_NONE ((xtc_pid_t){0, 0, 0})
 
static inline int
xtc_pid_eq(xtc_pid_t a, xtc_pid_t b)
{
        return a.loop_id == b.loop_id &&
               a.local_id == b.local_id &&
               a.gen == b.gen;
}
 
static inline int
xtc_pid_is_none(xtc_pid_t p)
{
        return p.loop_id == 0 && p.local_id == 0 && p.gen == 0;
}
 
/*
 * A pid published from one thread and read on others.  A 16-byte pid
 * does not fit one lock-free atomic word (C11 _Atomic of 16 bytes is a
 * libatomic call, and MSVC C has none), so this is a seqlock: a reader
 * never sees a torn pid.  Initialize with XTC_ATOMIC_PID_INIT (or zero
 * memory: it then holds XTC_PID_NONE).  Stores from several threads are
 * safe (they serialize on the sequence word); a load spins only while a
 * store is in progress.  The fields are private.
 */
typedef struct xtc_atomic_pid {
        uint64_t seq_;
        uint64_t w_[2];
} xtc_atomic_pid_t;
#define XTC_ATOMIC_PID_INIT { 0, { 0, 0 } }
 
/*
 * Match callback for selective receive.  Inspects an envelope's
 * data + size and returns:
 *   1  -> consume this envelope (the receive call returns it)
 *   0  -> skip; envelope stays in the save queue for the next receive
 */
typedef int (*xtc_match_fn)(const void *data, size_t size, void *user_data);
 
/*
 * Process entry function.  The proc runs as a coroutine and the
 * function returns nothing; exit happens by returning from the entry,
 * by calling xtc_exit, or by being killed via a link.
 */
typedef void (*xtc_proc_fn)(void *arg);
 
typedef struct xtc_proc_opts {
        size_t      size;          /* sizeof(xtc_proc_opts_t): XTC_PROC_OPTS_INIT */
        const char *name;          /* optional, for debug */
        size_t      mailbox_cap;   /* 0 = default */
        /* Mailbox watermark: when an accepted message brings the depth to
         * this percent of mailbox_cap (1..100; 0 = disabled), the callback
         * fires once on the rising edge, so the app can shed load before
         * the hard cap rejects with XTC_E_AGAIN.  The callback runs on the
         * sender's thread, outside the mailbox lock; keep it cheap and do
         * not block. */
        int         mailbox_watermark_pct;
        /*
         * Work-stealing: 0 (default) pins the proc's coroutine to its
         * spawn loop.  1 makes the coroutine work-stealable: an idle loop
         * may steal it (only while parked/scheduled, never mid-instruction)
         * to rebalance runnable work across a multi-loop executor.  The
         * proc's identity (pid), supervision (links/monitors/DOWN), recovery
         * frame, and mailbox are unaffected -- only the carrier loop can
         * change, and only at a yield point.  See xtc_proc(3) MIGRATION.
         */
        int         migratable;
        void      (*mailbox_watermark_fn)(xtc_pid_t self, size_t depth,
                                          size_t cap, void *user);
        void       *mailbox_watermark_user;
        /*
         * L1 proportional-share scheduler: place this proc's task in a
         * scheduling CLASS created with xtc_exec_class_create.  NULL (the
         * default) is the implicit plain-FIFO class -- zero overhead.  A
         * non-NULL handle weights the proc's CPU share against the other
         * classes on its loop.  INSPIRED BY Glommio.
         */
        xtc_exec_class_t sched_class;
} xtc_proc_opts_t;
 
/* All defaults.  Add fields with a designated initializer that sets .size
 * too: { .size = sizeof(xtc_proc_opts_t), .name = "w" }.  A NULL opts
 * pointer also means all defaults. */
#define XTC_PROC_OPTS_INIT { .size = sizeof(xtc_proc_opts_t) }
 
/* Mailbox statistics snapshot (see xtc_proc_mailbox_stats). */
typedef struct xtc_mailbox_stats {
        size_t   size;         /* sizeof(xtc_mailbox_stats_t): XTC_MAILBOX_STATS_INIT */
        size_t   depth;        /* messages currently in the mailbox */
        size_t   saved;        /* messages held in the selective-receive
                                * save queue (inspected, not yet matched) */
        size_t   peak;         /* high-water mailbox depth ever reached */
        size_t   cap;          /* capacity bound on depth + saved (0 = none) */
        uint64_t recv_total;   /* messages accepted over the proc's life */
        uint64_t drop_total;   /* messages rejected (full / dead) */
} xtc_mailbox_stats_t;
 
#define XTC_MAILBOX_STATS_INIT { .size = sizeof(xtc_mailbox_stats_t) }
 
/*
 * PUBLIC: int       xtc_proc_spawn __P((xtc_loop_t *, xtc_proc_fn, void *, const xtc_proc_opts_t *, xtc_pid_t *));
 * PUBLIC: int       xtc_proc_spawn_link __P((xtc_loop_t *, xtc_proc_fn, void *, const xtc_proc_opts_t *, xtc_pid_t *));
 * PUBLIC: int       xtc_proc_spawn_monitor __P((xtc_loop_t *, xtc_proc_fn, void *, const xtc_proc_opts_t *, xtc_pid_t *, uint64_t *));
 * PUBLIC: xtc_pid_t xtc_self __P((void));
 * PUBLIC: xtc_pid_t xtc_atomic_pid_load __P((const xtc_atomic_pid_t *));
 * PUBLIC: void      xtc_atomic_pid_store __P((xtc_atomic_pid_t *, xtc_pid_t));
 * PUBLIC: int   xtc_proc_set_userdata __P((void *));
 * PUBLIC: void *xtc_proc_userdata __P((void));
 * PUBLIC: int   xtc_proc_set_class __P((xtc_exec_class_t));
 * PUBLIC: int       xtc_send __P((xtc_pid_t, const void *, size_t));
 * PUBLIC: int       xtc_send_owned __P((xtc_pid_t, void *, size_t));
 * PUBLIC: int       xtc_recv __P((void **, size_t *, int64_t));
 * PUBLIC: int       xtc_recv_match __P((xtc_match_fn, void *, void **, size_t *, int64_t));
 * PUBLIC: int       xtc_recv_correlate __P((const void *, size_t, int, xtc_msg_t *, int *, int64_t));
 * PUBLIC: int       xtc_proc_wait_fd __P((int, uint32_t, int64_t, uint32_t *));
 * PUBLIC: int       xtc_proc_sleep __P((int64_t));
 * PUBLIC: int       xtc_exit_self __P((int));
 * PUBLIC: int       xtc_exit_pid __P((xtc_pid_t, int));
 * PUBLIC: int       xtc_exit_pid_deadline __P((xtc_pid_t, int, int64_t, int *));
 * PUBLIC: int       xtc_proc_wake __P((xtc_pid_t));
 * PUBLIC: int       xtc_link __P((xtc_pid_t));
 * PUBLIC: int       xtc_unlink __P((xtc_pid_t));
 * PUBLIC: int       xtc_proc_trap_exit __P((int));
 * PUBLIC: int       xtc_monitor __P((xtc_pid_t, uint64_t *));
 */
 
XTC_API int       xtc_proc_spawn(xtc_loop_t *loop, xtc_proc_fn fn, void *arg,
                                  const xtc_proc_opts_t *opts, xtc_pid_t *out_pid);
 
/*
 * Atomic spawn + link / spawn + monitor (Erlang spawn_link /
 * spawn_monitor).  Identical to xtc_proc_spawn, but the parent<->child
 * relationship is established BEFORE the child is made runnable, so
 * there is no window in which the child exists but is not yet
 * linked/monitored -- even if the child runs and exits immediately,
 * its EXIT/DOWN is delivered (no XTC_DOWN_NOPROC race that a
 * spawn-then-link/monitor idiom can hit).  The CALLER MUST be a
 * process (xtc_self() != NONE); returns XTC_E_INVAL otherwise.
 *
 * _link:    bidirectional fate, exactly like calling xtc_link(child)
 *           the instant the child is born -- an abnormal exit on either
 *           side kills the other, or delivers it an EXIT message if it
 *           traps exits (see xtc_link / xtc_proc_trap_exit).
 * _monitor: unidirectional; the caller receives a DOWN (with *out_ref
 *           as the monitor reference) when the child exits, exactly
 *           like xtc_monitor(child).
 */
XTC_API int       xtc_proc_spawn_link(xtc_loop_t *loop, xtc_proc_fn fn, void *arg,
                                  const xtc_proc_opts_t *opts, xtc_pid_t *out_pid);
XTC_API int       xtc_proc_spawn_monitor(xtc_loop_t *loop, xtc_proc_fn fn,
                                  void *arg, const xtc_proc_opts_t *opts,
                                  xtc_pid_t *out_pid, uint64_t *out_ref);
 
/* From inside a process, return its pid; from outside, returns NONE. */
/*
 * Asynchronous cross-process exit signal.  Sets a kill flag on the
 * target proc; the target raises the exit at its next yield/recv
 * point with the supplied reason.  Idempotent (first call wins).
 * Returns XTC_E_INVAL if the target is unknown or already dead.
 */
XTC_API int xtc_exit_pid(xtc_pid_t target, int reason);
 
/*
 * Kill-delivery outcome, reported by xtc_exit_pid_deadline.
 *
 * xtc_exit_pid is FIRE-AND-FORGET: it returns XTC_OK once the flag is
 * set, which says nothing about whether the target ever acted on it.
 * That is fine for a cooperative sibling, but it leaves a supervisor
 * unable to distinguish the two cases it most needs to tell apart --
 * "the fiber is unwinding" from "the fiber is wedged inside an
 * xtc_uncancelable() region, where the kill is deferred with no bound
 * and will never fire."  Guessing after a fixed timeout is the only
 * option today; these statuses replace the guess with an answer.
 */
enum xtc_kill_status {
        /* The target is no longer ALIVE: it observed the kill and left its
         * body, or it was already dead (a pid that was never issued is
         * XTC_E_INVAL, not DELIVERED).  NOT proof that at-exit
         * hooks finished, that the stack was reclaimed, or even that THIS
         * request's reason was the one delivered -- see the long note on
         * xtc_exit_pid_deadline below before using this to release a
         * shared resource or start a replacement. */
        XTC_KILL_DELIVERED = 0,
        /* Still masked when the deadline expired: the kill is LATCHED and
         * will fire if the mask ever drops -- but the fiber is inside a
         * critical section and is not obliged to leave it.  A supervisor
         * should treat this as "wedged, escalate", NOT "try again": a
         * second xtc_exit_pid is a no-op (first call wins).  Escalation
         * means taking down a larger unit -- see the "Killing a fiber that
         * mutates shared state" section of xtc_proc(3). */
        XTC_KILL_DEFERRED  = 1,
        /* Reported as soon as a nonzero mask depth with a latched kill is
         * OBSERVED, which can be well before the supplied deadline -- so
         * DEFERRED is not evidence that the full timeout elapsed, and a
         * brief mask (any xtc_uncancelable / xtc_mask_enter region) is not
         * by itself evidence of a wedge.  Sample mask_depth /
         * mask_deferred over time (xtc_proc_info) to tell a transient mask
         * from a stuck one. */
        /* Not masked, but still alive at the deadline: it simply has not
         * reached a yield/recv point yet (a CPU-bound loop with no yield,
         * or a park that outlives the deadline).  Usually means "wait
         * longer"; a fiber that never yields will never be killable.
         * NOT proof the target is unmasked for the whole interval: a fiber
         * that is masked but has not yet OBSERVED the kill can land here
         * too.  And when the caller is itself a fiber on a starved loop,
         * this deadline is an observation budget, not a wall-clock bound --
         * call from a plain thread if you need the latter. */
        XTC_KILL_TIMEOUT   = 2
};
 
/*
 * xtc_exit_pid with a bounded wait and a REPORT of what happened.
 *
 * Identical to xtc_exit_pid (same idempotent flag, same reason
 * encoding), but waits up to timeout_ns for the target to act, then
 * writes one of the enum xtc_kill_status values to *out_status
 * (out_status may be NULL if only the wait is wanted).
 *
 * A zero or negative timeout polls once and reports immediately.
 * The CALLER MUST NOT be the target (killing yourself is
 * xtc_exit_self); returns XTC_E_INVAL for that, for XTC_PID_NONE, and
 * for an unknown pid.  A target that is already dead reports
 * XTC_KILL_DELIVERED with XTC_OK.
 *
 * Callable from a fiber or a plain thread.  On a fiber the wait yields
 * (xtc_proc_sleep); off one it sleeps the OS thread, so a supervisor
 * thread can use it directly.  Returns XTC_OK whenever a status was
 * determined -- the STATUS, not the return code, says whether the kill
 * landed.
 *
 * IMPORTANT -- WHAT XTC_KILL_DELIVERED DOES *NOT* PROVE.  It means the
 * target is no longer ALIVE, i.e. it observed the kill and left its
 * body.  It is NOT proof that the proc's at-exit hooks and scope
 * finalizers have COMPLETED, and it is NOT proof that the runtime has
 * reclaimed the proc's task/fiber stack.
 *
 * Why: the exit path clears `alive` BEFORE it runs the at-exit list
 * (see proc_exit in src/ptc/proc.c), and this call reports DELIVERED as
 * soon as the pid no longer resolves to a live proc.  A hook that parks
 * -- on a lock, an fd, a mailbox -- therefore leaves cleanup IN
 * PROGRESS while this function already returned DELIVERED.  An earlier
 * version of this comment said DELIVERED meant the hooks had run; that
 * was stronger than the implementation and is corrected here.
 *
 * So do NOT use DELIVERED as the signal to release, reset, or hand a
 * shared resource to a replacement -- that is exactly the overlap it
 * cannot rule out.  The library itself does not rely on `!alive` for
 * that purpose: arena-group discard waits for the pid to leave the proc
 * TABLE (see src/ptc/mctx.c), which happens only after the at-exit list
 * has returned.  Use that same stronger condition when you need
 * cleanup-complete, not merely kill-accepted.
 *
 * DELIVERED is also returned for a target that was already dead (still
 * unwinding, or long gone), so it cannot distinguish "this request's
 * reason was delivered" from "it had already died of something else".
 * Treat it as "not running any more", nothing more.  A pid this
 * runtime never issued is XTC_E_INVAL, exactly as for xtc_exit_pid;
 * releases before 1.50 reported XTC_OK + DELIVERED for it, and
 * XTC_E_INVAL for a target that was still running its at-exit hooks.
 * A pid whose loop has since been finalized cannot be told from one
 * never issued, and is XTC_E_INVAL too.
 *
 * Nor does it mean shared state the fiber was mutating is consistent:
 * releasing a lock does not undo a half-finished mutation.  If a fiber
 * can be killed mid-mutation of state other fibers keep using, an async
 * kill is the wrong tool -- see xtc_proc(3).
 */
XTC_API int xtc_exit_pid_deadline(xtc_pid_t target, int reason,
                                  int64_t timeout_ns, int *out_status);
 
/*
 * Resume a process parked in xtc_proc_wait_fd / xtc_recv, from ANY OS
 * thread (including a thread libxtc does not manage).  The explicit
 * "poke the target loop" primitive: after a foreign thread makes a
 * watched condition true (writes a self-pipe an fd-park watches, sets
 * an embedder latch, completes an async read), xtc_proc_wake(pid)
 * nudges the target loop out of its I/O wait so the parked proc
 * re-checks its condition.  It delivers no message; the woken proc just
 * re-evaluates, so a spurious wake is always safe.  Returns XTC_OK
 * (including when the target is not parked, already runnable, or gone),
 * XTC_E_INVAL for XTC_PID_NONE.
 */
XTC_API int xtc_proc_wake(xtc_pid_t target);
 
XTC_API xtc_pid_t xtc_self(void);
 
/* Load / store an xtc_atomic_pid_t (see above).  At least acquire /
 * release (what the storing thread wrote before the store is visible to
 * a thread whose load returned that pid), and both take part in the
 * single seq_cst total order, like an atomic_store / atomic_load. */
XTC_API xtc_pid_t xtc_atomic_pid_load(const xtc_atomic_pid_t *a);
XTC_API void      xtc_atomic_pid_store(xtc_atomic_pid_t *a, xtc_pid_t p);
 
/*
 * Per-proc opaque consumer pointer, on the CALLING proc.
 *
 * xtc_proc_set_userdata stores an opaque `void *` on the calling proc
 * (NULL by default); xtc_proc_userdata reads it back.  The pointer
 * belongs to the proc, not the loop or OS thread, so it SURVIVES
 * work-stealing migration -- a migratable proc
 * (xtc_proc_opts_t.migratable) that resumes on a different loop still
 * reads its own value.  This is the supported way to associate
 * per-proc consumer state that must track the running proc across a
 * carrier change (keyed implicitly by xtc_self()).
 *
 * O(1), allocation-free, lock-free: a plain field access on the
 * calling proc, which is running on this thread by definition.  The
 * runtime never dereferences or frees the pointer -- the consumer owns
 * whatever it points to (the same lifetime contract as
 * xtc_proc_at_exit's arg); it is simply dropped when the proc exits.
 *
 * xtc_proc_set_userdata returns XTC_OK, or XTC_E_INVAL when called off
 * a proc (xtc_self() == XTC_PID_NONE).  xtc_proc_userdata returns NULL
 * off a proc.
 */
XTC_API int   xtc_proc_set_userdata(void *ud);
XTC_API void *xtc_proc_userdata(void);
 
/*
 * L1 proportional-share scheduler: place the CALLING proc's task in the
 * scheduling class `cls` (created with xtc_exec_class_create on the
 * proc's loop).  The runtime-side equivalent of setting
 * xtc_proc_opts_t.sched_class at spawn, but callable from inside a
 * running proc so a proc can reclassify itself.  Returns XTC_OK, or
 * XTC_E_INVAL called off a proc or with a handle that is not on the
 * calling proc's loop.  INSPIRED BY Glommio's task-queue placement.
 */
XTC_API int   xtc_proc_set_class(xtc_exec_class_t cls);
 
/*
 * Send a message.  Copies `size` bytes from `data` (once: into a pooled
 * envelope up to 256 bytes, else into a buffer the receiver is then handed
 * without a second copy); the caller retains ownership of `data`.  To send
 * without any copy, build the message in an xtc_malloc'd buffer and use
 * xtc_send_owned below.  Returns:
 *   XTC_OK            queued successfully
 *   XTC_E_INVAL       NULL data with non-zero size, or stale/unknown pid
 *   XTC_E_AGAIN       target mailbox at capacity
 *   XTC_E_RESOURCE    global slot cap (XTC_RES_CHAN_SLOTS) hit
 *
 * BACKPRESSURE CONTRACT -- read this.  Mailboxes are bounded (the
 * cap is xtc_proc_opts_t.mailbox_cap, default 4096).  This is
 * deliberate: an unbounded mailbox is how an actor system OOMs when
 * a fast sender outruns a slow receiver (the classic unbounded-mailbox failure).
 * The price is that send can fail with XTC_E_AGAIN when the target
 * is full, and a dropped XTC_E_AGAIN is a SILENT MESSAGE LOSS.
 *
 * Senders MUST check the return value and decide a policy:
 *   - retry later (re-arm on a timer, or yield and resend),
 *   - shed load (drop the message and account it),
 *   - apply end-to-end flow control (e.g. stop reading the upstream
 *     socket until the target drains -- see examples/07_kaka for a
 *     credit-based scheme), or
 *   - treat it as fatal for a must-deliver path.
 * Ignoring the return is a bug, not a shortcut.
 *
 * WAKE GUARANTEE.  A successful send WAKES a receiver parked in
 * xtc_recv / xtc_recv_match / xtc_proc_wait_fd, and this holds from ANY
 * thread -- fiber-to-fiber, cross-loop, and from a plain OS thread that
 * libxtc knows nothing about (no loop, no proc identity, so the
 * envelope's `from` is XTC_PID_NONE).  There is no weaker cross-thread
 * mode: the receiver arms its waker under the same mailbox lock that
 * observed the mailbox empty, so a delivery either finds the waker armed
 * and fires it, or lands before the receiver commits to parking and the
 * receiver sees the message on its own re-check.  A cross-thread wake
 * posts to the target loop's inbox and pings its I/O backend, so a loop
 * blocked in epoll_wait / io_uring / kqueue / IOCP returns and
 * re-polls.  If a send returns XTC_OK and the target then stays parked
 * with a non-empty mailbox, that is a libxtc bug -- report it.
 *
 * A parked receiver is therefore never left holding an undelivered
 * message, but note what the guarantee does NOT promise: it says the
 * receiver is made runnable, not that it runs before the sender
 * continues.  Send is asynchronous and never blocks waiting for a
 * receive.
 */
XTC_API int       xtc_send(xtc_pid_t to, const void *data, size_t size);
 
/*
 * Send a message WITHOUT copying it: move `buf` itself into the target's
 * mailbox.  `buf` must come from libxtc's allocator (xtc_malloc /
 * xtc_calloc / xtc_realloc, or a buffer libxtc handed you to free with
 * xtc_free, e.g. one from xtc_recv); the receiver gets the same pointer
 * from xtc_recv / xtc_recv_match / xtc_recv_correlate and frees it with
 * xtc_free.  Zero copies end to end, at any size, same-loop or
 * cross-thread.
 *
 * OWNERSHIP: on XTC_OK the buffer belongs to the library (and then to
 * the receiver); the caller must not touch it again.  On ANY error the
 * caller still owns it, unchanged, and must free or retry it -- the same
 * XTC_E_AGAIN backpressure contract as xtc_send.  buf == NULL is allowed
 * only with size == 0 (an empty message).
 *
 * Returns the same codes as xtc_send.  Unlike xtc_send it never returns
 * XTC_E_NOMEM for the payload (there is nothing to allocate but the
 * fixed-size envelope header, which may still fail).
 */
XTC_API int       xtc_send_owned(xtc_pid_t to, void *buf, size_t size);
 
/*
 * Receive the next envelope from this process's mailbox.  The caller
 * owns the returned buffer and frees it with xtc_free.  A message from
 * xtc_send_owned, or an xtc_send larger than 256 bytes, is handed over
 * in the buffer it already travels in (no copy, no allocation here); a
 * small xtc_send payload is copied out of its pooled envelope.  Blocks
 * (yields the coroutine) up to
 * timeout_ns; -1 is
 * indefinite, 0 is non-blocking.
 *
 * Returns:
 *   XTC_OK            *out / *size set
 *   XTC_E_AGAIN       timeout fired with no message
 *   XTC_E_INVAL       called outside a process
 */
XTC_API int       xtc_recv(void **out, size_t *out_size, int64_t timeout_ns);
 
/*
 * Selective receive.  match_fn is called for each envelope in
 * arrival order; the first one for which match_fn returns 1 is
 * delivered.  Non-matching envelopes are kept in the save queue.
 */
XTC_API int       xtc_recv_match(xtc_match_fn match_fn, void *user_data,
                                  void **out, size_t *out_size,
                                  int64_t timeout_ns);
 
/*
 * Receive `n_expected` messages whose leading `corr_size` bytes
 * match `corr_value`.  The first `n_expected` matching messages
 * are delivered as an array via `out_msgs[]`; non-matching
 * messages stay in the mailbox / save queue for subsequent
 * receives.  Returns XTC_OK on full collection; XTC_E_AGAIN if
 * the timeout fires before n_expected matches arrive (in which
 * case `*out_n` is the number actually collected; out_msgs[0..*out_n]
 * are still owned by the caller and must be freed).
 *
 * This is the canonical helper for fork-join and request-reply
 * patterns: pick a correlation id, send N children a request
 * containing that id, wait for N replies whose first corr_size
 * bytes equal the id.  Avoids manual save-queue management.
 *
 * Each delivered message conforms to the same ownership contract
 * as xtc_recv: the caller owns the buffer and must free() it.
 */
typedef struct xtc_msg {
        void   *data;
        size_t  size;
} xtc_msg_t;
 
XTC_API int       xtc_recv_correlate(const void *corr_value, size_t corr_size,
                                      int n_expected,
                                      xtc_msg_t *out_msgs,
                                      int *out_n,
                                      int64_t timeout_ns);
 
/*
 * Wait until ANY of the following becomes true:
 *   - the given fd has any of `interest` bits set
 *     (XTC_IO_READABLE / WRITABLE / ERR / HUP),
 *   - a message arrives in the calling proc's mailbox,
 *   - the timeout elapses (only if `timeout_ns >= 0`),
 *   - the proc is killed (xtc_exit_pid raises the exit as usual).
 *
 * Returns:
 *   XTC_OK       on a non-timeout wakeup.  *out_revents has the
 *                XTC_IO_* bits that fired plus XTC_WAIT_MAILBOX if
 *                a message is queued.  Multiple bits can be set if
 *                more than one source raced to wake.
 *   XTC_E_AGAIN  timeout fired with nothing else.  *out_revents has
 *                XTC_WAIT_TIMEOUT.
 *   XTC_E_INVAL  bad args (NULL out_revents, fd<0, interest == 0, an
 *                fd that is not open -- POSIX), called from
 *                outside a process, OR the fd could not be registered
 *                because ANOTHER waiter already holds a live
 *                registration for it on this loop's io.  One fd, one
 *                waiter: two procs cannot wait on the same fd on the
 *                same loop at the same time.  A closed fd was reported
 *                as XTC_E_INTERNAL (epoll) or as a timeout / XTC_IO_ERR
 *                wake (io_uring) before 1.50.
 *   XTC_E_NOMEM / XTC_E_RESOURCE / XTC_E_NOSYS
 *                propagated unchanged from the fd registration.
 *   XTC_E_INTERNAL
 *                a libxtc invariant broke.  This is now reserved for
 *                genuinely unexpected failures: it previously ALSO
 *                covered every registration error above, which left a
 *                consumer unable to tell a bad argument from resource
 *                pressure, and led one to classify the opaque code as a
 *                spurious wake and retry it forever.
 *
 * EVERY non-XTC_OK return above means the proc did NOT park.  None of
 * them is a wake, and none should be retried in a tight loop: treat an
 * error as an error.  (A spurious wake IS possible, but it arrives as
 * XTC_OK -- see the note on re-checking your condition.)
 *
 * The fd is auto-unregistered before return -- including on the
 * cancellation path, and including when the fiber MIGRATED while parked
 * (the unregister is routed to the io that owns the registration, and
 * deferred to its owning thread when that is not this one).  A
 * subsequent wait on the SAME fd is therefore expected to succeed, and a
 * pending deferred unregister no longer makes it fail: the re-register
 * consumes it.  The caller never needs to drive a poll or drain step to
 * make that true.
 *
 * The mailbox is left untouched (caller still calls xtc_recv to
 * actually drain).
 */
#define XTC_WAIT_MAILBOX  0x10000u   /* in out_revents only */
#define XTC_WAIT_TIMEOUT  0x20000u   /* in out_revents only */
 
XTC_API int       xtc_proc_wait_fd(int fd, uint32_t interest, int64_t timeout_ns,
                                    uint32_t *out_revents);
 
/* Sleep the calling process for at least ns nanoseconds by parking it
 * on a timer (the loop runs other work meanwhile -- it does not block
 * the thread).  Unlike a timed xtc_recv it does not touch the mailbox.
 * Returns XTC_E_INVAL if not called from a process. */
XTC_API int       xtc_proc_sleep(int64_t ns);
 
/* Explicit exit from inside a process; reason is delivered via
 * EXIT/DOWN signals to linked / monitoring procs. */
XTC_API int       xtc_exit_self(int reason);
 
/*
 * Link / unlink: bidirectional fate (BEAM semantics, since 1.55.1).
 * When a linked proc exits with a NON-normal reason (!= 0), each linked
 * peer that does not trap exits is killed with the same reason (as if by
 * xtc_exit_pid).  A normal exit (reason 0) is silent to a non-trapping
 * peer.  A peer that traps exits (xtc_proc_trap_exit(1)) is never killed
 * by a link; it receives an 'E' message for every linked exit, normal or
 * not (decode with xtc_down_decode_ex; ref is 0).
 *
 * Before 1.55.1 a link never killed anything: every peer received an 'E'
 * message for every exit, normal included.  Code that links and then
 * waits for that 'E' must now call xtc_proc_trap_exit(1) first.
 */
XTC_API int       xtc_link(xtc_pid_t other);
XTC_API int       xtc_unlink(xtc_pid_t other);
 
/*
 * Set whether the CALLING proc traps exits (default off).  Returns the
 * previous setting (0 or 1), or XTC_E_INVAL off a proc.
 */
XTC_API int       xtc_proc_trap_exit(int on);
#define XTC_HAVE_PROC_TRAP_EXIT 1
 
/* ---- Monitor DOWN reasons ------------------------------------------
 *
 * A monitor's DOWN carries an int `reason` describing how the target
 * ended.  The reason space is:
 *
 *   0            -- clean exit (the target returned, or called
 *                   xtc_exit_self(0)).
 *   > 0          -- an application exit code the target passed to
 *                   xtc_exit_self(code) (including a contained fault
 *                   that ran xtc_exit_self(sig), which passes the
 *                   POSITIVE signal number, e.g. 11 for SIGSEGV).
 *   XTC_DOWN_NOPROC -- the monitor was registered on a target that had
 *                   ALREADY exited (the monitor raced the target's
 *                   exit), so its real exit reason was already reaped
 *                   and is unknown.  This is NOT a crash: a short-lived
 *                   target that a supervisor monitors just after it
 *                   finished delivers this, and it is expected.  It is a
 *                   distinct value (not XTC_E_NOTFOUND, and outside the
 *                   1..255 signal-number range) precisely so a
 *                   supervisor can tell "already gone" apart from a real
 *                   fault exit -- a DOWN reason of, say, 11 is a
 *                   contained SIGSEGV, whereas XTC_DOWN_NOPROC is not.
 *
 * xtc_down_is_noproc(reason) is the readable test for the last case.
 */
#define XTC_DOWN_NOPROC  (-100000)
 
static inline int
xtc_down_is_noproc(int reason)
{
        return reason == XTC_DOWN_NOPROC;
}
 
/* Monitor: unidirectional notification.  out_ref is filled with the
 * monitor reference; the watcher receives a DOWN message of shape
 * { uint8_t kind = 'D'; uint64_t ref; xtc_pid_t pid; int reason; }
 * when the monitored process exits (reason per the DOWN-reason space
 * above).  Registering a monitor on an ALREADY-dead target is not an
 * error: it delivers an immediate DOWN with reason XTC_DOWN_NOPROC. */
XTC_API int       xtc_monitor(xtc_pid_t target, uint64_t *out_ref);
 
/* Snapshot a process's mailbox statistics into *out.  Returns XTC_OK,
 * or XTC_E_INVAL if the pid is dead / unknown.  Safe to call from any
 * thread. */
int       xtc_proc_mailbox_stats(xtc_pid_t pid, xtc_mailbox_stats_t *out);
 
/* ---- R1: per-fiber fault containment ----
 *
 * Turns a real synchronous fault (SIGSEGV / SIGBUS / SIGFPE / SIGILL
 * on POSIX; the equivalent EXCEPTION_* on Windows) inside one
 * coroutine into an unwind of only that process, leaving siblings on
 * the same loop untouched -- the runtime support PG's "let it crash"
 * session containment needs.
 *
 * POSIX: sigaltstack + sigaction + siglongjmp.  Windows: a Vectored
 * Exception Handler restores the CONTEXT captured at
 * xtc_proc_recovery_arm() (no stack unwind).  Both paths are
 * runtime-verified on their hosts: a contained fault outside a
 * critical section unwinds the one proc and delivers DOWN to its
 * monitors; a fault inside a critical section escalates to process
 * abort (POSIX re-raise; Windows EXCEPTION_CONTINUE_SEARCH ->
 * 0xC0000005), preserving PG's critical-section PANIC semantics.
 */
#if (defined(__sun) || defined(__illumos__)) && !defined(__EXTENSIONS__)
/* illumos/Solaris gate sigjmp_buf / sigsetjmp / siglongjmp behind a
 * feature-test macro; under -std=c11 (strict ISO C) <setjmp.h> hides
 * them.  A consumer that includes this PUBLIC header need not know to
 * set the macro itself, so expose the POSIX setjmp surface here before
 * the include.  No effect on other platforms. */
#define __EXTENSIONS__ 1
#endif
#include <setjmp.h>
 
#if defined(_WIN32)
#include <windows.h>
/*
 * Windows recovery uses CONTEXT capture/restore rather than
 * setjmp/longjmp.  The fault is caught by a Vectored Exception Handler
 * that restores this saved CONTEXT via EXCEPTION_CONTINUE_EXECUTION --
 * the OS reloads the thread's registers and resumes at the capture
 * point.  longjmp out of (or via) a VEH is unsafe: on a fiber stack it
 * walks unwind tables that no longer match and corrupts the CRT; a
 * context restore does no unwinding at all.
 */
typedef struct xtc_recovery_buf { CONTEXT ctx; } xtc_recovery_buf_t;
#else
typedef sigjmp_buf xtc_recovery_buf_t;
#endif
 
/* Install the process-wide fault handler.  On POSIX it registers a
 * SIGSEGV/SIGBUS/SIGFPE/SIGILL handler on an alternate signal stack
 * (call once per loop thread for the alt stack; the handler is
 * installed once).  On Windows it registers a Vectored Exception
 * Handler.  Returns XTC_OK on success. */
int       xtc_fault_guard_install(void);
 
/* Internal arm-slot for the xtc_proc_recovery_arm() macro (POSIX). */
xtc_recovery_buf_t *__xtc_proc_recovery_slot(void);
 
#if defined(_WIN32)
/* Windows recovery-arm helpers (used by the macro below).
 * __xtc_recovery_prep arms the frame and clears the fired flag;
 * __xtc_recovery_ctx returns the CONTEXT to capture into;
 * __xtc_recovery_result returns 0 on the arming pass and the fault
 * code when the VEH has restored the context. */
void      __xtc_recovery_prep(void);
CONTEXT  *__xtc_recovery_ctx(void);
int       __xtc_recovery_result(void);
#endif
 
/*
 * Arm a recovery frame for the calling process, exactly like
 * sigsetjmp: returns 0 on the normal path and the fault signal number
 * (POSIX) or exception code (Windows) when control returns here via a
 * contained fault.  Use it as:
 *
 *     int sig = xtc_proc_recovery_arm();
 *     if (sig != 0) {                 // recovered from a contained fault
 *         ... release locks, reset the memory context, close fds ...
 *         xtc_exit_self(reason);       // delivers DOWN to the supervisor
 *     }
 *     ... session work ...
 *
 * The frame is disarmed automatically when a fault fires it (so a
 * fault during recovery escalates to process abort); re-arm or
 * xtc_proc_recovery_disarm() as needed.
 *
 * IMPORTANT: containment only unwinds the fiber's CALL STACK.  Any
 * resources the proc held at fault time -- locks, fds, allocations,
 * buffer pins -- are the recovery block's responsibility to release:
 * abort any in-progress transaction and release every held lock and
 * resource before returning.  Hold those under an xtc_mctx you
 * can reset, and release lock-manager locks with the lock manager's
 * release-all; otherwise a contained fault leaks or, worse, leaves a
 * lock held and wedges peers.
 */
#if defined(_WIN32)
/* Capture the proc fn's own frame inline (like setjmp), so the VEH can
 * restore it; the comma expression returns 0 while arming and the
 * fault code after a contained fault resumes execution here. */
#define xtc_proc_recovery_arm() \
        (__xtc_recovery_prep(), \
         RtlCaptureContext(__xtc_recovery_ctx()), \
         __xtc_recovery_result())
#else
#define xtc_proc_recovery_arm() (sigsetjmp(*__xtc_proc_recovery_slot(), 1))
#endif
 
/* Disarm the calling process's recovery frame. */
void      xtc_proc_recovery_disarm(void);
 
/* Critical section: while crit_depth > 0, a fault is NOT contained --
 * it escalates to process abort, because shared state may be torn.
 * Nestable.  Mirrors PG's START_CRIT_SECTION / END_CRIT_SECTION. */
void      xtc_proc_critical_enter(void);
void      xtc_proc_critical_leave(void);
 
/* Register a callback to run when the calling process exits -- on a
 * normal return OR a contained-fault recovery (after
 * xtc_proc_recovery_arm -> xtc_exit_self).  Callbacks run LIFO,
 * outside signal context, with the proc still current, BEFORE its
 * monitors observe DOWN.  This is where an embedder guarantees a
 * faulted session releases what it held -- e.g. register
 * xtc_lock_release_all so no lock-manager lock outlives the proc, or
 * a memory-context reset.  Up to a small fixed number per proc;
 * returns XTC_E_RESOURCE past the limit, XTC_E_INVAL off a proc. */
int       xtc_proc_at_exit(void (*fn)(void *), void *arg);
 
/* A memory context scoped to the calling process: created lazily on
 * first call, destroyed automatically on proc exit (a backstop so a
 * faulted session's allocations are reclaimed even if its recovery
 * block itself faults).  Returns NULL off a proc.  See xtc_mctx.h. */
struct xtc_mctx *xtc_proc_mctx(void);
 
/*
 * Recovery resource registry.
 *
 * A contained fault unwinds the faulting fiber's call stack but frees
 * NONE of the resources the proc held -- locks stay locked, fds stay
 * open, memory arenas stay live -- and a leaked lock can wedge every
 * peer.  Register the resources a proc acquires so the runtime can
 * release them automatically:
 *
 *   xtc_proc_recovery_track_fd(fd);          // close(fd) on cleanup
 *   xtc_proc_recovery_track_mctx(mctx);      // xtc_mctx_reset(mctx)
 *   xtc_proc_recovery_track_locks(mgr, locker, release_all);
 *   xtc_proc_recovery_track(fn, arg);        // generic fn(arg)
 *
 * xtc_proc_recovery_cleanup() releases everything registered (LIFO).
 * It is the DEFAULT recovery action and is ALSO callable from a custom
 * recovery block to finish the standard bits after the block's own
 * application-specific unwinding:
 *
 *   int sig = xtc_proc_recovery_arm();
 *   if (sig != 0) {                 // recovered from a contained fault
 *       my_app_abort_txn();          // custom unwinding first
 *       xtc_proc_recovery_cleanup();  // then the registered standard bits
 *       xtc_exit_self(sig);
 *   }
 *
 * Or use xtc_proc_recovery_arm_clean(), which performs the cleanup and
 * xtc_exit_self automatically on the recovered branch (no custom block).
 *
 * Registered resources are ALSO released automatically on a NORMAL
 * proc exit (before the at-exit hooks), so a proc that simply returns
 * without explicitly releasing still cleans up.  Use
 * xtc_proc_recovery_untrack_fd() when the proc releases an fd itself,
 * to avoid a double close on a later recovery.
 *
 * Each registration returns XTC_OK, XTC_E_RESOURCE past the per-proc
 * limit, or XTC_E_INVAL off a proc / on a bad argument.
 */
int  xtc_proc_recovery_track_fd(int fd);
int  xtc_proc_recovery_track_mctx(struct xtc_mctx *mctx);
int  xtc_proc_recovery_track_locks(void *mgr, uint64_t locker,
                                   void (*release_all)(void *, uint64_t));
int  xtc_proc_recovery_track(void (*fn)(void *), void *arg);
int  xtc_proc_recovery_untrack_fd(int fd);
void xtc_proc_recovery_cleanup(void);
 
/*
 * Arm a recovery frame whose default recovered action is to release
 * all tracked resources and exit the proc with the fault code.  On the
 * normal (arming) pass it returns 0 and execution continues into the
 * session work; on a contained fault it does NOT return -- it runs
 * xtc_proc_recovery_cleanup() then xtc_exit_self(sig).  Use this when
 * the registered resources are the whole cleanup story; use the bare
 * xtc_proc_recovery_arm() + a custom block when they are not.
 */
#define xtc_proc_recovery_arm_clean()                       \
        do {                                                \
                int __xtc_rsig = xtc_proc_recovery_arm();   \
                if (__xtc_rsig != 0) {                      \
                        xtc_proc_recovery_cleanup();        \
                        (void)xtc_exit_self(__xtc_rsig);    \
                }                                           \
        } while (0)
 
/* ---- A2: cancellation masking (uncancelable / poll) ----
 *
 * MonadCancel's masking discipline, for C.  Structured cancellation via
 * xtc_abort / xtc_exit_pid is cooperative -- a running fiber observes it
 * only at a yield/recv point.  Masking makes it COMPOSABLE: inside an
 * xtc_uncancelable() region an asynchronous kill delivered at a park
 * point is DEFERRED, not acted on, and is observed only when the region
 * returns (mask depth back to 0).  This is what lets a resource acquired
 * in the region always register its release before cancellation unwinds
 * the fiber -- the guarantee xtc_scope / xtc_bracket rely on.
 *
 * Run `body(ud)` with cancellation masked; returns body's return value
 * (or XTC_E_INVAL if body is NULL).  Nests: each call bumps a per-proc
 * mask counter.  Off a proc it simply runs body.
 *
 * PUBLIC: int xtc_uncancelable __P((int (*)(void *), void *));
 */
XTC_API int xtc_uncancelable(int (*body)(void *), void *ud);
 
/*
 * Cats Effect's poll: inside an xtc_uncancelable() body, run `body(ud)`
 * with the mask temporarily lifted so cancellation IS observed for that
 * sub-region.  A kill already deferred by the enclosing mask fires at
 * the poll site (before body runs); the caller's mask depth is restored
 * on return.  Outside a masked region it just runs body.  Returns body's
 * value (or XTC_E_INVAL if body is NULL).
 *
 * PUBLIC: int xtc_cancel_poll __P((int (*)(void *), void *));
 */
XTC_API int xtc_cancel_poll(int (*body)(void *), void *ud);
 
/*
 * True iff cancellation is pending for the calling proc -- either an
 * async kill has been requested (xtc_exit_pid) or one was deferred by a
 * mask.  A cheap, allocation-free probe for a masked region that wants
 * to unwind early and cleanly rather than wait for the park point.
 * Returns 0 off a proc.
 *
 * PUBLIC: int xtc_cancel_requested __P((void));
 */
XTC_API int xtc_cancel_requested(void);
 
/*
 * Paired form of the cancellation mask, for straight-line code that
 * cannot be expressed as a callback body.
 *
 * xtc_uncancelable() brackets a `body(ud)` lambda; that is the right
 * shape for a self-contained region, but not for a macro pair wrapped
 * around arbitrary code that goto/break/returns or longjmps out
 * (PostgreSQL's START_CRIT_SECTION() / END_CRIT_SECTION() over WAL
 * insertion, buffer writes, page splits -- straight-line code that
 * cannot be hoisted into a callback without a wholesale control-flow
 * rewrite).  These expose the same per-proc mask counter directly:
 *
 *   xtc_mask_enter()   bumps the mask depth; a kill delivered at a
 *                      later park point is DEFERRED, not acted on.
 *   xtc_mask_leave()   drops the depth (saturating at 0) and, once the
 *                      depth is back to 0, honors any kill latched
 *                      while masked -- which, exactly like the end of
 *                      an xtc_uncancelable() body, may not return
 *                      (it unwinds the fiber via xtc_exit_self).
 *
 * They NEST: N enters need N leaves, and only the outermost leave can
 * unwind.  xtc_uncancelable() and the pair share the one counter and
 * compose freely.
 *
 * Both return XTC_OK on a proc and XTC_E_INVAL off one (mirroring how
 * xtc_uncancelable() just runs body off a proc -- there is nothing to
 * mask, so a bridge macro can ignore the return).  UNLIKE
 * xtc_uncancelable(), which brackets a synchronous body, enter and
 * leave are separated in time and a yield may occur between them, so
 * each independently re-anchors onto the running fiber -- a bridge that
 * enters, yields (any park), and later leaves stays correct even if the
 * fiber migrated in between.
 *
 * A leave with no matching enter is a no-op, not an error: the
 * saturating decrement means an unbalanced END_CRIT_SECTION() cannot
 * drive the counter negative and mask cancellation forever.
 *
 * PUBLIC: int xtc_mask_enter __P((void));
 * PUBLIC: int xtc_mask_leave __P((void));
 */
XTC_API int xtc_mask_enter(void);
XTC_API int xtc_mask_leave(void);
 
/* ---- A1: resource scope / bracket ----
 *
 * A blessed, runtime-ENFORCED resource scope.  Cats Effect's
 * Resource/bracket was, for years, a "paper door": a convention the API
 * carroted you toward but nothing stopped you walking past, leaking a
 * socket on the cancellation path.  xtc_scope makes
 * "this WILL be released on EVERY exit path" a MECHANISM, not a manner.
 *
 * Open a scope on the calling proc, defer finalizers into it, and close
 * it.  Finalizers run LIFO -- on the normal xtc_scope_close, AND on an
 * error return, xtc_exit_self, an async kill (xtc_exit_pid), or a
 * fault-guard-contained crash, because the scope is pushed as a marker
 * on the same recovery registry that releases fds and locks on unwind.
 * Scopes nest; an outer unwind closes inner-then-outer LIFO.
 *
 * xtc_scope_open returns NULL off a proc or on resource exhaustion.
 */
typedef struct xtc_scope xtc_scope_t;
typedef void (*xtc_finalizer_fn)(void *arg);
 
/*
 * PUBLIC: xtc_scope_t *xtc_scope_open __P((void));
 * PUBLIC: int  xtc_scope_defer __P((xtc_scope_t *, xtc_finalizer_fn, void *));
 * PUBLIC: void xtc_scope_close __P((xtc_scope_t *));
 */
XTC_API xtc_scope_t *xtc_scope_open(void);
XTC_API int  xtc_scope_defer(xtc_scope_t *s, xtc_finalizer_fn fn, void *arg);
XTC_API void xtc_scope_close(xtc_scope_t *s);
 
/*
 * bracket sugar (acquire -> use -> guaranteed release), the load-bearing
 * correctness core.  `acquire` runs abort-MASKED so `release` is always
 * registered before cancellation can be observed; `release` then runs on
 * EVERY exit path of `use` (normal, error, kill, crash).  acquire writes
 * the resource through *res and returns XTC_OK (else bracket returns its
 * code and nothing else runs); use returns a code that bracket returns;
 * release is void.  `ud` threads a caller context through all three.
 *
 * PUBLIC: int xtc_bracket __P((int (*)(void **, void *), int (*)(void *, void *), void (*)(void *, void *), void *));
 */
XTC_API int xtc_bracket(int (*acquire)(void **res, void *ud),
                        int (*use)(void *res, void *ud),
                        void (*release)(void *res, void *ud),
                        void *ud);
 
/* Decode a DOWN signal (delivered to a monitor when its target exits)
 * into the target pid and exit reason, without hand-rolling the
 * on-wire layout.  The DOWN/EXIT signals are sent packed; a mismatched
 * (unpacked) mirror struct misreads `reason`.  Returns XTC_OK if msg
 * is a DOWN, XTC_E_INVAL otherwise.  out_pid / out_reason may be NULL. */
int       xtc_down_decode(const void *msg, size_t len,
                          xtc_pid_t *out_pid, int *out_reason);
 
/*
 * Self-describing DOWN classification (requested by embedders whose
 * app exit codes and signal numbers would otherwise share the single
 * `reason` integer: a bare xtc_exit_self(1) was indistinguishable from
 * a signal-1 (SIGHUP) contained fault).  xtc_down_decode_ex fills an
 * xtc_down_info_t whose `kind` says HOW the target ended, with the
 * signal number and the app exit code in SEPARATE fields that never
 * collide.  The legacy single-integer xtc_down_decode still works and
 * returns the same `reason` it always did.
 */
typedef enum {
        XTC_DOWN_KIND_CLEAN  = 0,  /* target returned or xtc_exit_self(0) */
        XTC_DOWN_KIND_EXIT   = 1,  /* xtc_exit_self(code), code in .exit_code */
        XTC_DOWN_KIND_SIGNAL = 2,  /* R1 contained fault, signal in .signal */
        XTC_DOWN_KIND_NOPROC = 3,  /* monitor raced a dead target (benign) */
        XTC_DOWN_KIND_NOCONNECTION = 4  /* the cross-process channel died
                                         * before a clean exit was seen
                                         * (xtc_xproc: the fork'd child's
                                         * control socket closed) */
} xtc_down_kind_t;
 
typedef struct xtc_down_info {
        size_t          size;       /* sizeof(xtc_down_info_t): XTC_DOWN_INFO_INIT */
        xtc_pid_t       pid;        /* the target that went DOWN */
        xtc_down_kind_t kind;       /* how it ended (never ambiguous) */
        int             signal;     /* signal number iff kind == SIGNAL, else 0 */
        int             exit_code;  /* app code iff kind == EXIT, else 0 */
        int             reason;     /* the legacy xtc_down_decode reason value */
        uint64_t        ref;        /* the monitor reference (0 for a link EXIT) */
} xtc_down_info_t;
 
#define XTC_DOWN_INFO_INIT { .size = sizeof(xtc_down_info_t) }
 
/*
 * Decode a DOWN or EXIT signal into a fully-classified xtc_down_info_t.
 * Accepts both the monitor DOWN ('D') and the link EXIT ('E') signal
 * shapes.  Returns XTC_OK on either, XTC_E_INVAL for any other message.
 * A monitor need no longer know the producer's encoding convention:
 * kind + signal + exit_code are unambiguous by construction.
 *
 * PUBLIC: int xtc_down_decode_ex __P((const void *, size_t, xtc_down_info_t *));
 */
XTC_API int       xtc_down_decode_ex(const void *msg, size_t len,
                                     xtc_down_info_t *out);
 
/* Predicate + accessor helpers over a legacy `reason` integer, for
 * callers that keep using xtc_down_decode.  A signal-N fault and a
 * bare xtc_exit_self(N) are STILL not distinguishable from `reason`
 * alone (that is the whole reason to prefer xtc_down_decode_ex); these
 * helpers only classify the two unambiguous sentinels. */
static inline int xtc_down_is_signal_reason(int reason)
{
        return reason >= 1 && reason <= 255;
}
static inline int xtc_down_is_exit_reason(int reason)
{
        return reason == 0 || reason >= 256;
}
 
/* The internal current-proc context save/restore across a yield
 * (__xtc_proc_ctx_save / __xtc_proc_ctx_restore) is library-internal
 * (the __ prefix) and lives in "proc_int.h", not in this installed
 * public header. */
 
#endif /* XTC_PROC_H */