silk/fiber

Affine Fiber handles, typed outcomes, and one-observer completion.

When to use

Use forkChild to create structured child work. Use await to inspect success, failure, or cancellation as data. Use join to propagate a Fiber failure through the current Effect. Use yieldNow to let tasks that are already ready run first under a FIFO provider.

Details

A Fiber owns one completion observer. Observation consumes the Fiber, so one Fiber has at most one waiter. A successful fork publishes the complete child before it returns the Fiber. Completion, cancellation, and cooperative yielding notify an Execution without allocation.

Gotchas

Dropping a Fiber stops observation. It does not cancel the task that produces the result.

Import as Fiber with import silk.fiber.

Public declarations: 16.

CompletionProducer

pub struct CompletionProducer<A, E>

The producer endpoint for one Fiber result.

Details

A Scheduler provider owns this endpoint until it calls completeSuccess or completeFailure. Both operations consume the endpoint and notify one parked observer.

CompletionCanceller

pub struct CompletionCanceller

The type-erased cancellation endpoint for one Fiber result.

Details

A task store can retain this endpoint without storing the Fiber success or failure types. cancel consumes the endpoint and notifies one parked observer.

Fiber

pub struct Fiber<A, E>

An affine handle that observes one task result or cancellation.

Details

await and join consume the handle. Dropping the handle does not cancel its task.

Outcome

pub struct Outcome<A, E>

The three possible terminal observations of a Fiber.

Field value

pub value: silk/fiber.Cancelled | silk/fiber.Failure<E> | silk/fiber.Success<A>

The completed success, typed failure, or cancellation value.

Success

pub struct Success<A>

A successful Fiber outcome.

Field value

pub value: A

The value returned by the task.

Failure

pub struct Failure<E>

A typed failed Fiber outcome.

Field error

pub error: E

The error raised by the task.

Cancelled

pub struct Cancelled

A Fiber outcome that reports structured task cancellation.

PreparedFiber

pub struct PreparedFiber<A, E>

The three endpoints created for one future Fiber result.

Details

A Scheduler provider gives fiber to the caller, captures producer in the task, and stores canceller in its type-erased task entry.

Field producer

pub producer: silk/fiber.CompletionProducer<A, E>

The endpoint that publishes a success or typed failure.

Field canceller

pub canceller: CompletionCanceller

The type-erased endpoint that publishes cancellation.

Field fiber

pub fiber: silk/fiber.Fiber<A, E>

The affine result handle returned after task publication succeeds.

prepare

pub effect fn prepare<A, E>() -> silk/fiber.PreparedFiber<A, E> ! OutOfMemoryError ? &mut Allocator

Allocates the producer, canceller, and affine Fiber endpoints for one task.

When to use

Use this provider operation before a Scheduler constructs and publishes a task.

Details

No endpoint becomes visible until both Shared completion cells exist. Observation and notification allocate no further storage.

completeSuccess

pub fn completeSuccess<A, E>(producer: silk/fiber.CompletionProducer<A, E>, value: A) -> ()

Completes one Fiber with value and notifies its observer.

Details

This operation stores value before it publishes readiness. It consumes the producer endpoint and allocates no storage.

completeFailure

pub fn completeFailure<A, E>(producer: silk/fiber.CompletionProducer<A, E>, error: E) -> ()

Completes one Fiber with error and notifies its observer.

Details

This operation stores error before it publishes readiness. It consumes the producer endpoint and allocates no storage.

cancel

pub fn cancel(canceller: CompletionCanceller) -> ()

Publishes cancellation and notifies one parked Fiber observer.

Details

This operation is independent of the Fiber success and failure types. It consumes the cancellation endpoint and allocates no storage.

await

pub effect fn await<A, E>(self: silk/fiber.Fiber<A, E>) -> silk/fiber.Outcome<A, E>

Consumes a Fiber and returns its success, typed failure, or cancellation as data.

Details

A terminal Fiber returns immediately. A pending Fiber parks the current Execution and installs exactly one Wake. Observation and resumption allocate no storage.

join

pub effect fn join<A, E>(self: silk/fiber.Fiber<A, E>) -> A ! E | Cancelled

Consumes a Fiber, returns its success value, and propagates failure or cancellation.

Details

A typed task failure is raised unchanged. Cancellation raises Cancelled. A pending Fiber parks with the same allocation-free one-observer protocol as await.

forkChild

pub effect fn forkChild<A, E>(child: once Effect<A ! E ? &mut silk/scheduler.Scheduler>) -> silk/fiber.Fiber<A, E> ! OutOfMemoryError | Scheduler.TaskIdExhaustedError ? &mut Scheduler.Scheduler

Prepares and atomically publishes one child task, then returns its affine Fiber.

When to use

Use this operation to run closed work or work that uses the child Scheduler provider.

Details

Preparation finishes its exclusive Scheduler dispatch before publication starts. Publication returns the Fiber only after the provider accepts the complete child. The provider records that acceptance and wakes the parent before it notifies the child's initial readiness. The child body starts only when the Scheduler later drives it.

Gotchas

Allocation refusal or task-identity exhaustion raises the exact preparation failure. Publication refusal raises OutOfMemoryError, returns no Fiber, and does not activate the child.

yieldNow

pub effect fn yieldNow() -> ()

Relinquishes the current Execution once and immediately reports that it is ready.

When to use

Use this operation to let tasks that are already ready run before the current task continues under a FIFO provider.

Details

This operation consumes its Wake during registration. It needs no Scheduler service and allocates no storage. The provider selects the next activation order.