Module weave

seq_runtime

Module weave 

Source
Expand description

Weave operations for generator/coroutine-style concurrency

A “weave” is a strand that can yield values back to its caller and be resumed. Unlike regular strands (fire-and-forget), weaves allow bidirectional communication with structured yield/resume semantics.

§Zero-Mutex Design

Like channels, weaves pass their communication handles directly on the stack. There is NO global registry and NO mutex contention. The weave context travels with the stack values.

§API

  • strand.weave: ( Quotation – WeaveHandle ) - creates a woven strand, returns handle
  • strand.resume: ( WeaveHandle a – WeaveHandle a Bool ) - resume with value
  • strand.weave-cancel: ( WeaveHandle – ) - cancel a weave and release its resources
  • yield: ( WeaveCtx a – WeaveCtx a ) - yield a value (only valid inside weave)

§Architecture

Each weave has two internal channels that travel as values:

  • The WeaveHandle (returned to caller) contains the yield_chan for receiving
  • The WeaveCtx (on weave’s stack) contains both channels for yield to use

Flow:

  1. strand.weave creates channels, spawns coroutine with WeaveCtx on stack
  2. The coroutine waits on resume_chan for the first resume value
  3. Caller calls strand.resume with WeaveHandle, sending value to resume_chan
  4. Coroutine wakes, receives value, runs until yield
  5. yield uses WeaveCtx to send/receive, returns with new resume value
  6. When quotation returns, WeaveCtx signals completion

§Resource Management

Important: Weaves must either be resumed until completion OR explicitly cancelled with strand.weave-cancel. Dropping a WeaveHandle without doing either will cause the spawned coroutine to hang forever waiting on resume_chan.

Proper cleanup options:

Option 1: Resume until completion

[ generator-body ] strand.weave  # Create weave
0 strand.resume                   # Resume until...
if                                # ...has_more is false
  # process value...
  drop 0 strand.resume           # Keep resuming
else
  drop drop                       # Clean up when done
then

Option 2: Explicit cancellation

[ generator-body ] strand.weave  # Create weave
0 strand.resume                   # Get first value
if
  drop                           # We only needed the first value
  strand.weave-cancel            # Cancel and clean up
else
  drop drop
then

§Limitations

  • Yielding i64::MIN (-9223372036854775808) is not supported as it’s used as the completion sentinel. This value will be interpreted as weave completion.
  • Yielding i64::MIN + 1 (-9223372036854775807) is not supported as it’s used as the cancellation sentinel.

Re-exports§

pub use patch_seq_resume as resume;
pub use patch_seq_weave as weave;
pub use patch_seq_weave_cancel as weave_cancel;
pub use patch_seq_yield as weave_yield;

Functions§

patch_seq_resume⚠
Resume a woven strand with a value
patch_seq_weave⚠
Create a woven strand from a quotation
patch_seq_weave_cancel⚠
Cancel a weave, releasing its resources
patch_seq_yield⚠
Yield a value from within a woven strand