#colmugx/fuwaroid

#Why "Fuwaroid"

#The model

            tell(cmd) ───────────────┐   ask(query) ───────────┐
   callers                             │  (with timeout)         │
                                       ▼                         ▼
                             ┌──────────────────────────────────────┐
   host task group ─────────►│  mailbox (typed, FIFO, bounded or not)│
   (owns the lifetime)       └──────────────────┬───────────────────┘
                                                │ one serial loop
                                                ▼ yields every 32
                                                  complete messages
                            state = on_cmd(state, cmd)              ← sync
                            (state, reply) = on_query(state, query) ← sync
                                                │
                 async work: ctx.group.spawn_bg(work) …
                            work finishes → ctx.address.tell(result)

#Guarantees

1. Handlers are synchronous by signature. A callback runs to return without another mailbox message interleaving it, so the loop applies each returned state in one serial step. Because handlers are plain synchronous functions and ask is an async method, the compiler rejects an ask call from inside a handler — report results back with tell instead. The generic API cannot prove that State has no aliases or that a callback is pure; callers must keep actor state owned by the loop and avoid mutating it from spawned work or replies.
2. Fair scheduling happens between complete messages. After every fuwaroid_yield_batch (32) complete messages the loop yields the scheduler, so an instance that keeps its own mailbox non-empty cannot monopolize the cooperative runtime: other instances, timers and cancellation all get scheduled. This is a scheduling opportunity, not a real-time guarantee: no millisecond bound is promised, and one long CPU-bound handler still blocks the whole runtime for its duration (measured in docs/concurrency-benchmarks.md §2.5: a 2,000-iteration arithmetic handler drops end-to-end throughput from 1.87M to 423k msg/s).
3. Async work lives outside the Fuwaroid. Spawn it on the host group from a handler; report the outcome back with tell. The loop is the only place that applies a handler's returned state. The library does not guarantee reliable delivery of background results: a report that arrives after close, or into a full bounded mailbox, is refused, and the host must collect that refusal itself (see Background work).
4. Lifecycle: close, cancel, join. close is idempotent: it refuses new messages and drains the already-queued ones in FIFO order, then the loop exits; close returning does not mean the drain completed. Host cancellation outranks draining: the loop stops at the next cancellation boundary instead of finishing the backlog. join waits for the loop task to terminate and returns the recorded StopReason; close(); join() is the way to confirm a graceful drain.
5. Stranded asks fail fast. If the loop stops abnormally (host cancellation or another terminal mailbox error), asks that were already accepted get Stopped immediately instead of hanging until their timeout. Cancellation of the asker itself propagates unchanged.
6. Backpressure is explicit. The mailbox is this library's own Mailbox: Unbounded, or Bounded(n) whose sends are refused synchronously with MailboxFull — nothing is silently dropped, and there is no drop-style mailbox. An invalid capacity (Bounded(0) or a negative value) aborts at spawn time.

#API

#Usage

// A counter Fuwaroid with a query flow.
enum CounterCmd {
  Add(Int)
}

enum CounterQuery {
  GetCount
}

struct Count {
  mut n : Int
}

async test "counter" {
  @async.with_task_group(group => {
    let f = @fuwaroid.Fuwaroid::spawn(
      group~, // the host's long-lived task group — never a per-call one
      init=Count::{ n: 0 },
      on_cmd=(_, state, cmd) => {
        match cmd {
          CounterCmd::Add(k) => { state.n = state.n + k; state }
        }
      },
      on_query=(_, state, _query) => (state, state.n),
    )
    let _ = f.tell(CounterCmd::Add(2))
    // FIFO: the reply certifies Add(2) was already served.
    let count = f.ask(CounterQuery::GetCount, timeout_ms=1000) // Ok(2)
    debug_inspect(count, content="Ok(2)")
  })
}

#Background work

enum WorkCmd {
  StartWork
  Report(Int)
}

fn run_delegation() -> Int {
  42 // stand-in for IO, a subprocess, anything slow
}

async test "background work" {
  let refusals : Array[@fuwaroid.SendRefusal] = []
  @async.with_task_group(group => {
    let f = @fuwaroid.Fuwaroid::spawn_fold(
      group~,
      init=0,
      on_cmd=(ctx, state, cmd) => {
        match cmd {
          StartWork => {
            ctx.group.spawn_bg(() => {
              let outcome = run_delegation() // IO, subprocess, anything slow
              match ctx.address.tell(Report(outcome)) {
                Ok(_) => () // admitted; a later message folds it in
                // Refused: record it somewhere the host owns. The report is
                // lost — state changes only via messages that are admitted.
                Err(refusal) => refusals.push(refusal)
              }
            })
            state // unchanged here — the report arrives as a message
          }
          Report(n) => state + n
        }
      },
    )
    let _ = f.tell(StartWork)
    f.close()
    let _ = f.join() // Graceful — the drain completed
    debug_inspect(refusals, content="[MailboxClosed]")
  })
}

#Lifecycle: close, cancel, join

async test "close then join" {
  @async.with_task_group(group => {
    let f = @fuwaroid.Fuwaroid::spawn_fold(
      group~,
      init=0,
      on_cmd=(_, state, _cmd) => state + 1,
    )
    let _ = f.tell(1)
    f.close() // refuse new; drain what is left; the loop then exits
    let reason = f.join() // wait for the loop task and learn why it ended
    debug_inspect(reason, content="Graceful")
  })
}

• close is idempotent and returns before the drain completes; the loop drains the backlog in FIFO order, yielding between batches while doing so.
• join returns the recorded StopReason: Graceful after a closed-and-empty drain, Cancelled when the host cancelled the loop, and Failed(original error) after an ordinary terminal error. In moonbitlang/async 0.22.x cancellation is a runtime signal of its own, distinct from Error — Fuwaroid never wraps it into a fake error. The cancelled loop task ends cancelled (an external Task::wait observer sees @async.TaskCancelled), and join reports the recorded Cancelled. Multiple waiters are fine, and a join after termination returns immediately. If the waiter itself is cancelled, that cancellation propagates unchanged, including when the loop has already terminated.
• Abnormal cleanup closes admission and enters Closing, then abandons queued messages in batches of 32 under cancellation protection. It yields between batches so other tasks can run; join completes only after all stranded reply queues are closed and the stop reason is recorded.
• Cancellation outranks draining. The loop is spawned no_wait on the host group. close() followed by an immediate return from the host scope cancels the still-running loop — the backlog is NOT fully processed and join (observed from another scope) reports Cancelled. To confirm a graceful drain, close();join() before leaving the scope.
• An ask issued just before close proves ordering by FIFO: its reply certifies every message enqueued before it was already served.

#Supervisor: bounded task settlement

Fuwaroid serializes mutable state. Supervisor owns cancellable async work. Neither is an actor system.

async test "supervisor settles a selected foreground set" {
  @async.with_task_group(group => {
    let sup = @fuwaroid.Supervisor(group~)
    let foreground = []
    for i in 0..<2 {
      match sup.spawn(() => i, label="fg\{i}") {
        Ok(handle) => foreground.push(handle)
        Err(_) => abort("open supervisor refuses nothing")
      }
    }
    // Background work is spawned the same way and simply never selected;
    // it keeps running while the foreground set settles.
    let outcome = sup.cancel_and_wait(
      tasks=foreground.clamped_view(),
      timeout_ms=5000,
    )
    debug_inspect(outcome, content="Settled")
    // Later: stop owning tasks altogether.
    debug_inspect(sup.shutdown(timeout_ms=5000), content="Settled")
  })
}

• Ownership without ceremony. A supervisor is bound to an existing host TaskGroup and creates no runtime. Spawned tasks are real children of the host group: when the host scope ends, remaining tasks are cancelled by the group exactly like any other child. Ordinary failures keep the host group's own fail-fast behavior — the supervisor never swallows them.
• cancel is a request, not a verdict. It records Cancelling synchronously and idempotently, and never demotes a terminal status. The race outcome is honest: a worker that finishes before observing the request ends Completed (or Failed), not Cancelled.
• wait is Task::wait. Results, original error identity and @async.TaskCancelled for a cancelled target come straight from the underlying task; handles stay waitable after the supervisor's live registry has reaped their task, with any number of waiters.
• One deadline for the whole settlement operation. cancel_and_wait computes deadline = now + timeout_ms once; every selected task shares it. Waiting for N tasks never costs N × timeout inside Supervisor. On expiry, DeadlineExceeded carries snapshots of exactly the still-nonterminal selected tasks in their TRUE status (Running / Cancelling) — it never fabricates a terminal status, never clears the live registry, and the stragglers may still terminate later.
• The deadline works from shielded contexts. Settlement runs in a local task group of waiter helpers plus one timer, so it never relies on "cancel the caller to stop the wait" — it is safe to call from cleanup code running under @async.protect_from_cancel. Cancelling the settlement caller tears down only the helpers; a waiter helper's cancellation never reaches its target.
• Shutdown is admission control plus settlement. The first shutdown closes admission synchronously and forever (Open ->Closing -> Closed; spawn refuses with SupervisorClosed from that moment), then cancels and bounded-settles exactly the tasks that were live at entry. Repeated shutdowns are safe; after a deadline exceeded they can wait again for the stragglers, and the registry converges by itself once those terminate.

#Mailbox configuration

async test "bounded mailbox" {
  @async.with_task_group(group => {
    let f = @fuwaroid.Fuwaroid::spawn_fold(
      group~,
      init=0,
      on_cmd=(_, state, _cmd) => state + 1,
      mailbox=@fuwaroid.Mailbox::Bounded(1),
    )
    @async.pause() // let the loop reach its mailbox park (its steady state)
    // A Bounded mailbox never waits for capacity: a send that finds it
    // full is refused synchronously with MailboxFull.
    let mut refused = 0
    for i in 0..<3 {
      match f.tell(i) {
        Ok(_) => ()
        Err(refusal) => {
          debug_inspect(refusal, content="MailboxFull")
          refused = refused + 1
        }
      }
    }
    if refused == 0 {
      fail("Bounded(1) never refused within the window")
    }
    // A refused send admitted nothing, so retrying it is side-effect free;
    // each pause lets the loop serve queued messages and recover capacity.
    let mut served = false
    for _ in 0..<100 {
      match f.ask((), timeout_ms=10000) {
        Ok(_) => { served = true; break }
        Err(NotDelivered(MailboxFull)) => @async.pause()
        Err(other) => fail("unexpected ask failure: \{Repr(other)}")
      }
    }
    if !served {
      fail("the barrier was never admitted")
    }
    // The barrier's reply certifies every admitted message was served.
    let snap = f.snapshot()
    if snap.accepted != snap.processed || snap.abandoned != 0L {
      fail("conservation violated after the barrier")
    }
  })
}

• The effective admission window is capacity + 1. While the loop is parked in queue.get() — its steady state while idle — the first send is handed to that parked reader point-to-point, bypassing the buffer. One uninterrupted producer turn can therefore admit up to capacity + 1 messages in flight (1 handoff slot + capacity buffered); the next send is the one refused with MailboxFull.
• Bounded(n) requires a positive integer n. Bounded(0) and negative capacities are a configuration error: spawn aborts synchronously with a fail-fast message — capacities are never clamped, remapped, or silently treated as rendezvous.

#Fair scheduling

• With 16 hot self-chaining instances, a cold instance's observed latency stays in the hundreds of microseconds at batch 32 (P50 212µs, max 276µs), versus 52µs/77µs at batch 1 and 737µs/1,484µs at batch 128.
• Batch 32 delivers ~24x the drain throughput of batch 1 (1.80M vs 74.5k msg/s end-to-end) while loaded ask P99 stays at 51µs (batch 1: 3,611µs).

#Diagnostics

#Migrating from the pre-R1 API

#Migrating to 0.2.0 (moonbitlang/async 0.22.x)

#Purity

#License