sx/library/modules/std/io.sx

// std.io — the `Io` capability's default impl + the async ergonomic layer.
//
// `Io` itself (the protocol) lives in std/core.sx next to `Allocator`, so
// the compiler-coupled `Context` field + the `__sx_default_context`
// materializers can reference it. This file carries the parts that are
// pure library sx: the stateless blocking impl (`CBlockingIo`, the mirror
// of `CAllocator`) + the generic free-fns layered over the protocol
// (`async` / `await` / `cancel` + the `Future($R)` type).
//
// Consumers reach these through std.sx (`Future` / `async` / `await` /
// `cancel` / `CBlockingIo` re-exports), never by importing this file
// directly.
//
// BLOCKING SEMANTICS (B1.2): the M:1 default has no scheduler and no
// suspension. `async(worker, ..args)` runs the worker to COMPLETION
// inline, so the returned `Future` is born `.ready` and `await` yields
// immediately. `spawn_raw`/`suspend_raw`/`ready`/`poll`/`arm_timer` are
// trivial no-ops/0 — they exist for the fiber scheduler [B1.3+].
// `now_ms` returns a real monotonic clock. Fully deterministic/testable.
//
// Worker form (B1.2): a `Closure(..$args) -> $R` whose params are
// annotated at the call site (a lambda `(a: i64) -> i64 => ...`).
// Named-fn workers need a `::` callable-parameter language feature that
// does not exist yet and are DEFERRED.
#import "modules/std/core.sx";
#import "modules/std/atomic.sx";
time :: #import "modules/std/time.sx";

// --- IoErr: the error channel async rides (cancellation = model (a)) ---
//
// A canceled future raises `.Canceled` out of `await`; a failed task
// raises `.Failed`. The `(T, !IoErr)` value-failable shape is the same
// one the rest of the stdlib uses (see examples/1011-, 1012-).
IoErr :: error { Canceled, Failed }

// --- CBlockingIo: stateless Io that runs tasks synchronously ---
//
// Zero-sized struct (mirror of CAllocator). Used as the default
// `context.io` at program start (see `__sx_default_context` in codegen).
// The thunks never dereference `self`, so the protocol value's ctx field
// is `null` — which is what keeps the static-constant default context an
// inline vtable with a null receiver.

CBlockingIo :: struct {}

impl Io for CBlockingIo {
    // No fiber bootstrap in the blocking model: the generic `async`
    // free-fn calls the worker directly and fills the Future. `spawn_raw`
    // is here for the protocol shape the scheduler [B1.3] will use; the
    // blocking impl never routes through it, so it is a no-op handle.
    spawn_raw :: (self: *CBlockingIo, entry: *void, arg: *void, opts: SpawnOpts) -> *void {
        return null;
    }
    // Blocking never suspends — a suspend at the bottom of the M:1 stack
    // would deadlock. No-op (returns success). The `!` is part of the
    // protocol contract (a suspending impl raises `.Canceled` out here),
    // so the conforming blocking impl keeps it even though it never raises.
    suspend_raw :: (self: *CBlockingIo, park: ParkToken) -> ! {
        return;
    }
    ready :: (self: *CBlockingIo, park: ParkToken) {}
    poll :: (self: *CBlockingIo, deadline_ms: i64) -> i64 { return 0; }
    now_ms :: (self: *CBlockingIo) -> i64 { return time.mono_ms(); }
    arm_timer :: (self: *CBlockingIo, deadline_ms: i64, park: ParkToken) -> *void {
        return null;
    }
}

// --- Future($R): the handle to an async task's eventual result ---
//
// Fixed-shape product (NOT the metatype sum machinery). `Value :: $R`
// exposes the projection `Future(X) → X`. B1.2 supports NON-void `$R`
// only — `Future(void)` (a `void` struct field) SIGTRAPs the compiler
// (issue 0150, deferred to B1.4 along with `timeout`).
FutureState :: enum { pending; ready; failed; canceled; }

Future :: struct ($R: Type) {
    Value :: R;

    value: R;
    state: FutureState = .pending;
    err: IoErr;
    park: ParkToken;
    task: *void = null;
    // Cancellation flag — atomic so a future scheduler thread can flip it.
    // In the blocking model there is no concurrency, but the type is the
    // one the M:N model [later] needs.
    canceled: Atomic(bool);
}

// --- The async ergonomic layer (generic free-fns over the protocol) ---

// `async(io, worker, ..args)` — submit `worker(..args)`. Blocking: runs
// the worker to completion inline, Future born `.ready`. The worker is a
// `Closure(..$args) -> $R` (a lambda whose params are annotated at the
// call site); `..$args` forwards the call-site arguments to it.
//
// NOTE on construction shape: the Future is built with `= ---` + per-field
// assignment, NOT a `return Future.{...}` struct-literal. A struct-literal
// in `return` position trips a generic-instantiation gap for the `Atomic`
// field; the `= ---` (uninit) + field-assign form is the verified idiom.
async :: ufcs (io: Io, worker: Closure(..$args) -> $R, ..$args) -> Future($R) {
    f : Future($R) = ---;
    f.value = worker(..args);
    f.state = .ready;
    f.canceled = Atomic(bool).init(false);
    return f;
}

// (A nullary worker needs no separate entry: the variadic `async` above binds
// `..$args` to the empty pack, so `context.io.async(() -> $R => …)` calls
// `worker()` and returns `Future($R)`. Locked by examples/1805.)

// `await(f)` — value-carrying failable. `.ready` → the result; `.failed`
// / `.canceled` → raise the stored / cancellation error.
await :: ufcs (f: *Future($R)) -> ($R, !IoErr) {
    if f.canceled.load(.acquire) { raise error.Canceled; }
    if f.state == .canceled      { raise error.Canceled; }
    if f.state == .failed        { raise error.Failed; }
    return f.value;
}

// `cancel(f)` — request cancellation. Sets the per-future cancel flag +
// marks the state so a subsequent `await` raises `.Canceled`. (In the
// blocking model the task already ran; cancel still rides the `!`
// channel — model (a).)
cancel :: ufcs (f: *Future($R)) {
    f.canceled.store(true, .release);
    f.state = .canceled;
}