Module fiber 

Fibers: lightweight cooperative threads for I/O-bound work (M:N scheduling).

A fiber runs on the OS thread that spawned it, for its whole life. Pinning keeps every rule of the object model intact: a fiber’s objects are owned by its thread, so ownership checks, thread-local young collection and with lock work unchanged, and a fiber block may capture owned values. Many fibers share one thread and interleave only where one of them waits.

Each fiber has its own native stack (a stackful coroutine) and its own Vm context (registers, frames, handles), registered with the thread’s main VM so the collector scans parked fibers. The thread’s main context runs the scheduler whenever it waits: in join, a channel operation, sleep, file or console I/O, or at the end of the thread.

Waiting in a fiber parks it instead of blocking the thread:

• channel send/receive and fiber join register a waker and park;
• sleep sets a timer and parks;
• blocking system calls (files, stdin) run on a small shared pool of I/O threads while the fiber is parked.

A fiber never parks while it holds a lock keyed by its OS thread (with lock, Mutex closures): a sibling fiber could otherwise enter the same lock. It blocks the whole thread instead.

ThreadSanitizer: corosensei switches native stacks behind TSan’s back, which would mix the shadow call stacks of the fibers sharing a thread and report false races. Builds with --cfg catx_tsan (set alongside -Zsanitizer=thread, see the tsan-suite CI job) tell TSan about every switch through its fiber API; elsewhere the hooks compile to nothing.

Functions

blocking_io

Runs a blocking call that does not touch the heap. In a fiber (or a main context that has fibers) it runs on the I/O pool while other fibers run; otherwise the thread blocks in the native state, as crate::blocking does.

drain

Runs every fiber that finished, on any thread, at the end of the thread’s main code.

has_fibers

True if this thread has fibers that have not finished.

in_fiber

True while a fiber (not the thread’s main context) is running.

is_done

Whether fiber id of this thread has finished.

join

Waits for the fiber behind handle (of this thread) and returns its result, or the panic message.

sleep

Sleeps without blocking the thread when it has fibers (or is one).

spawn

Starts a fiber running closure on this thread, recording its id in handle (a Fiber). It first runs when this thread’s main context waits (or when another fiber parks).

wait_event

Waits for an event without blocking the thread when possible. arm(wake) must check the condition and, if it does not hold, arrange for wake to be called when it may (under the same lock as the check); it returns true if the caller must wait. Returns false if this context cannot wait cooperatively (no fibers, or a thread-keyed lock is held): the caller then blocks the thread as before. After a true return, re-check the condition.

wait_event_until

As wait_event, with a deadline: returns Some(timed_out) when it waited cooperatively (timed_out is true if the deadline passed before a wakeup), None when the caller must block the thread itself. After Some(false), re-check the condition.

yield_now

Lets other fibers run. In the main context, runs each ready fiber once.