Module scheduler 

M:N flows, mailboxes, timer, supervisor and Runtime.

A flow is Byteflow’s unit of concurrent work (not an OS thread). Flows exchange Atomic Hops (crate::Value::Message) — never bare scalars on bytecode Send / Ask.

Authority boundary

The VM only validates types. This module owns delivery:

1. Resolve crate::Value::Cap → FlowId + rights (CapRights)
2. Stamp Message.sender and mint reply_cap (SEND-only)
3. Push into the target Mailbox (anti lost-wakeup under one mutex)

crate::Value::Pid is identity inside hops, not an ambient address. Host Runtime::send takes FlowId directly (trusted).

See crate::docs::security and crate::docs::atomic_hop.

Structs

CapId

Opaque capability identifier carried in crate::Value::Cap.

CapRights

Rights attached to a capability (bitflags as u8).

ChildSpec

A child the supervisor should start (and possibly restart).

Flow

A single flow: VM state, mailbox, and bookkeeping.

FlowHandle

A reference to a spawned flow, returned by super::runtime::Runtime::spawn.

FlowId

Identifier of a flow — Byteflow’s unit of concurrent work.

FlowMetrics

Live counters for one flow (updated only by the worker currently running it).

Mailbox

A flow’s inbox, plus (when the owning flow is blocked on Receive / ReceiveMatch / Ask with nothing to read) the parked flow itself.

Runtime

A running Byteflow runtime: worker pool + timer thread over one shared Chunk.

RuntimeConfig

Tunables for Runtime::new. Everything has a sensible default via RuntimeConfig::default so the common case is Runtime::new(chunk).

RuntimeMetrics

Runtime-wide counters (design notes §26). Every field is a plain AtomicU64 bumped with Relaxed ordering: these are monitoring counters, not synchronization primitives, so we don’t pay for anything stronger than “eventually visible to a metrics scrape.”

RuntimeMetricsSnapshot

Point-in-time, non-atomic copy of RuntimeMetrics suitable for printing or exporting.

RuntimeSpawner

A Send + Sync, freely cloneable capability to spawn processes into a Runtime, detached from the Runtime value itself. Exists because super::supervisor::Supervisor needs to respawn processes from a background monitor thread whose lifetime isn’t tied to the Runtime object’s own (which owns non-Sync JoinHandles for its workers).

Supervisor

Host-side child restarter (design notes §15-16).

SupervisorConfig

Tunables for Supervisor::with_config.

Enums

Delivery

Outcome of pushing a message: either it was queued for later, or it immediately handed off to a flow that was parked waiting for it — in which case the caller (see worker::deliver) is responsible for feeding the value back into that flow’s VM and re-enqueuing it as Ready.

FlowOutcome

Terminal outcome of a flow, delivered to whoever holds its super::handle::FlowHandle.

FlowState

Where a flow currently sits in its lifecycle.

RestartPolicy

Restart policy consulted by a super::supervisor::Supervisor when a supervised flow terminates.

RuntimeError

Scheduler / host infrastructure error — not a bytecode flow fault.

SendError

Why Runtime::send could not deliver a hop.

SpawnError

User-facing spawn / load errors (category A in the taxonomy above).

Constants

DEFAULT_QUANTUM

Default instruction budget per scheduling turn (design notes §10). Chosen as a middle ground: large enough that the per-yield bookkeeping cost is amortized over meaningful work, small enough that a pathological loop {} in one flow can’t visibly stall the others — at 10k simple instructions/turn and even a conservative tens-of-millions of instructions/sec per core, worst-case added latency for a sibling flow is sub-millisecond.

Functions

fault_count

How many report_fault calls have been made (tests / diagnostics).

flow_id_from_u64

A convenience Pid constructor for embedders that stored a raw u64 (e.g. round-tripped through Value::Pid) and need a FlowId to call APIs that take one.

next_flow_id

report_fault

Record an infrastructure fault (stderr + counter). Does not panic.