std::concurrent::fiber

std/src/concurrent/fiber.mo

typeFiber#
pub type Fiber (A : Type) {
    fiber
}
typeFiberError#
pub type FiberError {
    /// `cancel_fiber` (or a dropped scope, or a lost `race`) reached the
    /// fiber before it finished. Cancellation is cooperative: the body
    /// stops at its next IO bind (a native or pure computation already in
    /// progress finishes), and its result is discarded either way.
    cancelled,
    /// The runtime could not create the fiber's thread (a thread-count or
    /// address-space limit), so the action never ran.
    never_started
}

Why a fiber has no result to hand back.

defFiberError.of_code#
pub def FiberError.of_code (code : I64) : FiberError

The natives' error codes, in this order: 1 is cancelled, 2 is never_started.

defFiberError.message#
pub def FiberError.message (e : FiberError) : String
defforkIO#
pub def forkIO (action : Unit -> IO A) : IO (Fiber A)
defawait_fiber#
pub def await_fiber (f : Fiber A) : IO (Result FiberError A)

Wait for the fiber to stop and take its result, or the reason there is none. Awaiting the same fiber again in compiled code returns the same answer; on the Rust host it is an error, because the host runs the action at the first await.

defcancel_fiber#
pub def cancel_fiber (f : Fiber A) : IO Unit
defwait_any#
pub def wait_any {A : Type} (fibers : List (Fiber A)) : IO (Option I64)

Park until ANY fiber in fibers has stopped, then that fiber's INDEX in list order; none for an empty list or when the waiting fiber is itself cancelled. The index comes back rather than the answer so the winner is taken through the ordinary await_fiber reaping path -- one implementation of that protocol, not two.

This exists so race and select stop polling. Both used to re-derive "wait for one of N" as "probe all N, sleep 1 ms, repeat", which cost a timer wakeup per millisecond and delayed a win by up to a millisecond. A fiber that has not started yet (forkIO could not get a thread) counts as stopped, so it is picked up immediately rather than waited on forever.

Compiled-only: the Rust host cannot park (its fibers are deferred thunks), so it answers -1 and its combinators keep the documented lazy degradation.

defpollFiber#
pub def pollFiber (f : Fiber A) : IO (Option (Result FiberError A))

The non-blocking sibling of await_fiber: none while the fiber still runs, then some of exactly what await_fiber would answer. A cancelled fiber answers some (err cancelled) once it has stopped, never a silent none, so a poll loop on an abandoned fiber ends. On the Rust host the action is deferred and asking IS doing: poll runs it to completion and always returns some, so no test may assert interleaving through pollFiber there.