xtc_launch(3)
---xtc_launch(3)
run a function on a fiber with a precise one-shot deadline
| XTC_LAUNCH(3) | Library Functions Manual | XTC_LAUNCH(3) |
NAME
xtc_launch — run a
function on a fiber with a precise one-shot deadline
SYNOPSIS
#include
<xtc_launch.h>
int
xtc_launch(xtc_loop_t *loop,
xtc_launch_fn fn, void *arg,
int64_t timeout_ns, const
xtc_launch_opts_t *opts, intptr_t *result);
DESCRIPTION
xtc_launch runs
fn(arg) on a child fiber with a
one-shot timeout_ns deadline, the native libxtc form
of libinger's
launch(f,
timeout). It blocks (parks) the calling fiber until
fn finishes or the deadline fires. A
NULL loop means the loop the
caller is currently running on, the natural default for launching from
inside a fiber.
If fn completes within the deadline,
xtc_launch returns XTC_OK
and, when result is non-NULL, stores
fn's intptr_t return value. If
fn exceeds the deadline it is cancelled at the
deadline: its per-fiber recovery and at-exit cleanup run, so any locks, file
descriptors, or memory contexts it registered are released with no leak, and
xtc_launch returns
XTC_E_AGAIN (the runtime's timeout / try-again
code). If fn faults and the fault is contained by the
per-fiber recovery, xtc_launch returns
XTC_E_ABORTED. A negative
timeout_ns means no deadline (a plain awaited
spawn).
opts, if non-NULL, may set the child proc name (for logs), mailbox_cap, and the loop index when launched on an executor loop.
xtc_launch is composable: a launched
function may itself call xtc_launch. It must be
called from a fiber (it parks the caller).
CANCELLATION AND UNCOOPERATIVE WORK
xtc_launch bounds a
cooperating
function precisely: one that yields, receives, sleeps, or does I/O is
cancelled at its next such point, which for a short deadline is at the
deadline within a bounded slop. This is the statement-timeout / bounded-work
primitive.
A purely uncooperative function -- a tight CPU loop with no yield point at all -- is a harder case. Involuntary preemption (xtc_preempt(3)) time-slices such a loop so its loop-mates make progress, and a resume-point kill hook honors a pending cancel the instant the fiber is next scheduled through a yield. Reliably bounding a runaway to a specific deadline additionally requires the launching fiber's deadline timer to be serviced ahead of the re-scheduled runaway, which the single-loop scheduler does not currently guarantee under full monopolization. For unconditionally bounding untrusted pure-CPU work, offload it to an OS process with xtc_osproc(3), which the kernel preempts.
RETURN VALUES
XTC_OK on a clean finish;
XTC_E_AGAIN on deadline (cancelled);
XTC_E_ABORTED on a contained fault;
XTC_E_INVAL for bad arguments;
XTC_E_NOMEM or a spawn error otherwise.
SEE ALSO
| July 5, 2026 | Debian |