silk/execution

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Independently owned, caller-funded lazy computations with explicit external parking.

When to use

Use make when a lazy Effect must outlive the caller which constructs it and be resumed by a later owner. Use park inside the body when readiness comes from an external registration. Use drive for the initial activation and each later eligible activation.

Details

Construction obtains one combined package from the selected Allocator and does not start the Effect. The body representation, continuation, and fixed readiness endpoint remain private. A nested Effect.suspend transfers execution immediately. In contrast, park relinquishes the Execution until one Wake makes it eligible.

Gotchas

Execution is affine. The readiness callback must be detached and non-parking. make can report package allocation refusal. Later private execution-stack growth is a fatal trap. Dropping a dormant Execution cancels it. A retained Wake keeps the complete inert package alive until the Wake is consumed or dropped. drive returns continued ownership only to onSuspend.

Import as Execution with import silk.execution { Execution }.

Public declarations: 1.

Execution

pub struct Execution

The owner of the execution lifecycle operations.

Details

This struct carries no data and is never constructed by the library. Every operation is an inherent member declared in impl Execution, so import silk.execution { Execution } is the one import that reaches Execution.make(...) and the rest. It is unrelated to the builtin Intrinsic.Execution<A> type.

Associated function Execution.make

pub effect<'static> fn make<A, F, O, R>(body: F, readyState: O, onReady: R) -> Intrinsic.Execution<A> ! OutOfMemoryError ? &mut Allocator

Allocates one combined package and transfers the lazy body and fixed endpoint into it.

Details

The returned Execution is Initial. The body does not start during this call. Allocation refusal produces no Execution and leaves every input under ordinary Effect cleanup. Later private stack growth is a fatal trap and is not a OutOfMemoryError.

Associated function Execution.drive

pub effect<'env1> fn drive<'env: 'env1, A: 'env1, D: 'env1, C, S, 'env1>(execution: Intrinsic.Execution<A>, branchState: D, onComplete: C, onSuspend: S) -> ()

Drives one Initial, InitialReady, or Eligible activation and transfers branchState to one outcome callback.

Details

Completion calls onComplete. Relinquishment calls onSuspend with the dormant Execution. Each activation calls exactly one callback. Nested transfer can complete in the same drive. External parking relinquishes ownership until the fixed readiness endpoint reports eligibility. The body starts an independent diagnostic invocation. Install observation inside the body to retain it across parking. Outcome callbacks run in the driving caller's diagnostic context.

Gotchas

Driving a dormant, notifying, completed, or destroyed Execution is a fatal state trap.

Associated function Execution.notifyInitial

pub fn notifyInitial<A, 'life1>(execution: &'life1 mut Intrinsic.Execution<A>) -> ()

Notifies the fixed readiness endpoint for one Initial Execution exactly once.

Details

This operation changes the package to InitialReady before it invokes the endpoint. It is synchronous, does not park, and does not run the body. A later drive starts the body.

Gotchas

The Execution must still be Initial. Calling this operation again, or calling it after the Execution has been driven, parked, completed, or destroyed, is a fatal state trap.

Associated function Execution.park

pub effect<'env> fn park<'env, G, F>(register: F) -> ()

Relinquishes the currently Running Execution until one external readiness signal arrives.

Details

The registration callback receives the generation's sole affine Wake. Its returned guard is retained while dormant and dropped immediately before source continues after this call. The Wake makes this Execution eligible and invokes its fixed readiness endpoint at most one time.

Gotchas

A caller that keeps a cancelled Wake also keeps the complete inert Execution package alive. Consuming or dropping that Wake releases the final package authority.