logos.std.rt.fiber

Bounded FIFO channel between fibers on one thread, backed by a ring buffer.

At most one suspended sender AND one suspended receiver at a time; violating this invariant is a caller error (see chan_send / chan_recv).

Represents one cooperative fiber: saved context, owned stack, FLS slots, and intrusive ready-queue link.

Holds the register state of a suspended fiber (callee-saved regs + rsp). Maps 1:1 to the register save area in fiber_ctx.S; field order and sizes MUST NOT change without updating the asm offsets.

Heap-allocated one-shot slot shared between a producer and its consumer.

Count-down latch: a single waiter fiber suspends until the count reaches 0.

Single-thread only; supports at most one concurrent waiter.

Per-thread io_uring reactor: one ring plus a count of fibers parked on in-flight I/O.

Owns one thread’s cooperative fiber state: intrusive ready FIFO, running fiber, deferred-free slot, and optional retired-stack pool.

A bounded single-producer/single-consumer ring of (fn_ptr, arg) pairs. One slot stays unused: a ring of capacity cap holds at most cap - 1 entries.

A worker thread: cooperative Scheduler, io_uring Reactor, SPSC inbox, wakeup eventfd.

A fixed set of worker Threads, each running its own per-thread reactor loop.

Deallocates the channel, its ring buffer, and any pending suspended-send value.

Creates a heap-allocated channel holding up to cap items; free with chan_free.

Receives a value from the channel; suspends the current fiber while the channel is empty.

Unblocks a suspended sender by moving its pending value into the ring. If another receiver is already suspended (caller error), the result is undefined (null read).

Sends val into the channel; suspends the current fiber while the channel is full.

Wakes a suspended receiver if one is waiting. If another sender is already suspended (caller error), returns immediately and val is silently dropped.

Returns a pointer-sized identifier of the current fiber, or 0 if none. The reactor stores this as io_uring SQE user_data to know which fiber to re-enqueue on CQE delivery.

Sleeps the current fiber for ms milliseconds. Same return contract as fiber_sleep_ns; negative ms returns -22.

Sleeps the current fiber for ns nanoseconds via IORING_OP_TIMEOUT. Must run inside a fiber on a thread with a reactor installed. Returns 0 on success (kernel -ETIME normalised); -22 for no reactor or negative ns, -12 when the SQ is full.

Returns the current fiber’s FLS value for key, or 0 when no fiber is running. key is not bounds-checked; valid range is 0..fls_slots().

Returns the FLS key reserved for the fiber reactor’s CQE result (slot 0).

Sets the current fiber’s FLS value for key; no-op when no fiber is running. key is not bounds-checked; valid range is 0..fls_slots().

Returns the number of fiber-local storage slots per fiber.

Stores val into slot and wakes its waiting consumer, if any. Wakes cross-thread via cross_thread_enqueue when the waiter lives on another thread.

Returns the value from slot, suspending the current fiber until it is ready. Caller is responsible for freeing slot itself after future_get returns.

Allocates a new FutureSlot<T>, shared between the producer and consumer.

Decrements the count (called by workers); wakes the waiter when the count reaches 0.

Extra calls after the count hits 0 are no-ops (no underflow).

Deallocates a Latch created by latch_new.

Creates a heap-allocated Latch with the given initial count; free with latch_free.

Suspends the current fiber until the count reaches 0; returns immediately if already 0.

Single waiter only: a second concurrent latch_wait overwrites the first, deadlocking it.

Terminates the current fiber: marks it for freeing and switches back to the scheduler context; never returns. Called by the logos_fiber_entry trampoline (fiber_ctx.S) after the fiber function returns.

Parks the current fiber: like yield_fiber() but WITHOUT re-enqueueing it. The caller must arrange re-enqueueing later (e.g. unpark_fiber from a reactor CQE handler). Returns when the fiber is resumed; no-op when no fiber is running.

Returns the current thread’s reactor, or 0 if none is installed.

Tears down the reactor and frees its allocations; no-op on null r.

Obtains a free SQE from the reactor’s ring; returns 0 if the ring is full. Caller must fill the SQE via a logos_io_uring_prep_* function before reactor_submit_and_park.

Returns true if any fibers are parked awaiting CQEs; false for a null r.

Allocates and initialises a new reactor with entries SQ/CQ slots. Returns 0 (null) on io_uring init failure.

Drains completions from the ring, re-enqueuing each CQE’s fiber with the result in its FLS[0]. If blocking, waits (unconditionally) for the first CQE, then drains the rest non-blocking. Returns the number of CQEs processed, or a negative errno from the blocking wait.

Drives scheduler s and reactor r until both the run queue and the parked set are empty. Suits single-threaded tests and simple drivers without the full thread-pool machinery.

Installs r as the current thread’s reactor (asm TLS slot).

Submits sqe with the current fiber attached as user_data, parking until its CQE arrives. Returns the CQE result (stashed in FLS slot 0 by reactor_poll) on resume; -22 (EINVAL) when not running inside a fiber; negative submit errors pass through.

Frees the scheduler, munmapping any pooled stacks (does NOT free live fibers).

Allocates and initialises a new scheduler. The caller owns it and must call sched_free() when done.

Runs the scheduler loop until the ready queue is empty. Sets the per-thread scheduler pointer so spawn() and yield_fiber() work.

Registers this scheduler as the current one for this thread. Must be called before spawn() or yield_fiber() (sched_run sets it itself).

Enables (or resizes) the retired-stack pool; cap = 0 disables pooling. Call after sched_new() and before the first spawn(). Existing pool contents are munmap’d before the slot buffer is replaced.

Spawns a fiber that will call f(arg) on its own stack and enqueues it as ready. The current scheduler must have been set (sched_set_current or sched_run).

Frees all per-thread resources (inbox, scheduler, reactor, eventfd) and the pool itself. Call only after thread_pool_join.

Blocks until every worker’s OS thread exits (pthread_join on each).

Creates a pool of n workers, each with a scheduler, bounded SPSC inbox, eventfd, and io_uring reactor. No OS threads run until thread_pool_start.

Configures the per-fiber stack-pool capacity on every worker’s scheduler. Must be called BEFORE thread_pool_start — once a worker thread is running, its scheduler is accessed concurrently and touching it from outside is a data race.

Sets the shutdown flag and wakes every worker; each exits once its scheduler, inbox, and parked I/O are all drained.

Spawns one OS thread per worker; each runs its reactor loop until shutdown.

Submits f(arg) to run as a new fiber on worker target_idx, waking it if asleep. Spins while the target inbox is full. Assumes a single producer per inbox.

Re-enqueues a previously-parked fiber into the ready queue. Called by the reactor when a CQE for a parked fiber arrives; no-op when no scheduler is set.

Yields voluntarily: re-enqueues the current fiber and switches to the scheduler. Returns when the scheduler picks this fiber again.