Handle and completion model

• Context exposes one handle per spawned context.
• Construction with the output schema on the stack (() Context, Int32 Context) and INIT create an invalid handle.
• spawn returns a valid handle.
• done? becomes TRUE only after the referenced context stores its completion state.
• wait and get observe the same completion point.
• cancel, wait, and get need a mutable handle view, as in @context.cancel; valid? and done? accept an immutable view. A handle can be moved with @context new, not copied.
• When the declared output schema is not (), the handle retains the stored completion value until destruction.
• Destroying a valid context waits for completion, releases the spawned context state, and destroys any retained non-Meta output storage.

makeContext (in Out -- context)

Constructs and schedules one Context from a callable and its declared output schema.

• in is the callable executed in the new context, Out is its declared output schema, and context is the resulting scheduled Context.
• The callable's returned value must match Out; the context stores it for get when it finishes.
• spawn is defined as [makeContext]; use spawn.

Methods

Output mapping

• The declared output schema is selected by the out argument of spawn.
• The callable output is required to match that declared output schema.
• When the declared output schema is (), get produces no object.
• When the declared output schema is Meta, get returns that stored Meta object directly.
• For a non-Meta In-place output schema, get returns a mutable borrowed Ref to the context-owned output, valid until the handle is destroyed (Int32 Ref for an Int32 output). Text and Code outputs retain their schema kinds.
• A direct Text output comes back empty (known issue); return an owned String when the contents must be retained.
• get leaves the handle valid.

Known issue: A Context that stores a borrowed Ref retains its target address without copying and destroys and reinitializes that target on destruction, even with an In-place output descriptor; return an owned value, such as target new through an immutable view, instead.

Waiting and cancellation semantics

• If the target is already done, wait and get return without propagating cancellation. Otherwise, an already-canceled current context requests cancellation of the target before waiting.
• While the current context is suspended in wait or get, canceling it requests cancellation of the target; waiting still continues until the target completes.
• After the target context becomes done, repeated wait and get calls return without additional suspension.

Examples

Initial state

"control"      use
"sync/Context" use

{} Int32 {} [
  context: () Context;
  context.valid? printStack _:;
  0
] "main" exportFunction

Expected Output During Compilation

FALSE

done? and get

"String"       use
"control"      use
"sync/Context" use
"sync/sync"    use

{} Int32 {} [
  context: [2] Int32 spawn;
  context.done? [
    ("done" LF) printList
  ] [
    ("waiting" LF) printList
  ] if
  yield
  context.done? [
    ("done" LF) printList
  ] [
    ("waiting" LF) printList
  ] if
  value: @context.get;
  value isRef [
    ("ref" LF) printList
  ] [
    ("not-ref" LF) printList
  ] if
  drop
  ("value=" @value new LF) printList
  0
] "main" exportFunction

Expected Output

waiting
done
ref
value=2

Cancellation request and get

"String"       use
"control"      use
"sync/Context" use
"sync/sync"    use

{} Int32 {} [
  context: [10.0r64 sleepFor canceled?] FALSE spawn;
  @context.cancel
  result: @context.get;
  (result LF) printList
  0
] "main" exportFunction

Expected Output

TRUE

See also

• sync/sync: Cross-platform scheduling, sleep, time, IPv4 formatting, and TCP helpers.
• sync/ContextGroup: Group of spawned contexts with shared waiting and cancellation.
• sync/Event: Persistent event state with clear, set, wait, wake, and wakeOne.
• windows/dispatcher: Windows completion-port dispatcher and callback posting helpers.