silk/execution

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.

Public declarations: 4.

make

pub effect fn make<A, F, O, R>(body: F, readyState: O, onReady: R) -> Intrinsic.Execution<A> ! Allocator.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 Allocator.OutOfMemoryError.

drive

pub effect fn drive<A, D, C, S>(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.

Gotchas

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

notifyInitial

pub fn notifyInitial<A>(execution: &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.

park

pub effect fn park<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.