Struct ControllerHandle 

pub struct ControllerHandle { /* private fields */ }

Non-blocking handle to a running Controller. Returned by spawn_controller; used by the scriptable builtins to drive the distributed compute fabric from .stk code.

Implementations

impl ControllerHandle

pub fn listen_addr(&self) -> SocketAddr

Returns the address the listener is actually bound to (port may have been auto-assigned if 0 was passed in).

pub fn agent_count(&self) -> usize

Current count of connected agents.

pub fn muster(&self) -> Vec<u64>

Return session IDs of all currently connected agents, in numerically sorted order (deterministic for tests and scripts).

pub fn welcome(&self, target_count: usize, timeout: Duration) -> bool

Block until at least target_count agents are connected, or timeout elapses. Returns true if the count was reached. Polls every 50ms.

pub fn scatter(&self, code: &str, agent_ids: &[u64]) -> Result<u64>

Fan EVAL out to agent_ids in parallel. Returns a petition_id used later with gather to collect results. Agents that don’t exist in the roster or whose write fails are silently dropped from the dispatched set, so a stale agent_id in agent_ids does NOT cause the whole scatter to fail.

Returns Err only if the EvalCommand fails to bincode-serialize (which should never happen for plain strings).

pub fn gather( &self, petition_id: u64, timeout: Duration, ) -> Result<HashMap<u64, EvalResult>>

Block for results of petition_id up to timeout (per-agent read timeout, not total wall time). Returns a HashMap of session_id → EvalResult for every agent that replied with a valid EVAL_RESULT frame in time. Agents that timed out, errored, or disconnected are omitted from the map.

Stale frames in the per-agent socket buffer (e.g. METRICS left over from a prior FIRE) are silently skipped — same loop pattern as eval_all so manual REPL behaviour stays consistent with scripted.

Removes the divination from the pending table on return, so a second gather on the same petition_id is an error.

pub fn chant(&self, code: &str, agent_ids: &[u64]) -> Result<u64>

Register an active chant — a prayer that fires at every current agent now AND at every new agent that joins later (via the accept_loop → fire_chants_at path). Returns a chant_id used by amen_chant to stop the rescatter.

Fire-and-forget: chants don’t accumulate replies. Use for state distribution (bestow-like push to current + future workers).

pub fn amen_chant(&self, chant_id: u64) -> bool

Stop an active chant. Late joiners after this call won’t receive it. Returns true if the chant was active and removed, false otherwise.

pub fn set_quiet_accept(&self, quiet: bool)

Silence the accept_loop’s per-agent “[agent connected]” eprintln. Set to true before a bulk-spawn loop (congregation(N) / anoint(N)) to prevent the fork-thread/stdio RefCell race that loses 1-3 children at N>~50 on macOS Rust stdio. Set back to false after the spawn loop completes if you want the REPL UX back.

pub fn set_cloistered(&self, token: Option<&str>)

Turn :cloistered mode on (with a single accepted token) or off (with an empty token). Cloistered accept_loop reads an AGENT_AUTH frame after HELLO and rejects agents that don’t present a valid token. Open mode bypasses the AUTH read entirely.

pub fn excommunicate(&self, agent_ids: &[u64]) -> usize

Send SHUTDOWN to a specific subset of agents (the excommunicate verb). Each agent receives a SHUTDOWN frame and exits its loop; the agent’s TCP connection is dropped. Returns the count of agents that the frame was successfully written to (write failures from disconnected agents are silently swallowed — same convention as scatter).

pub fn pilgrimage( &self, barrier_code: &str, agent_ids: &[u64], timeout: Duration, ) -> bool

Pilgrimage barrier — scatter barrier_code to all agent_ids and block until every agent that received the frame replies, OR timeout elapses. Returns true if every dispatched agent replied in time.

barrier_code is the prayer the agents execute at the barrier; for a pure rendezvous, pass "1" and the agent’s reply is the synchronization signal. For computational barriers, pass code that does the work and returns when done.

pub fn shutdown(&self)

SHUTDOWN every agent, stop the accept loop, join the accept thread. Wakes the blocking listener.incoming() call by self-connecting to the bound address (the connection’s HELLO read will fail and the accept thread will exit its loop now that running is false).

pub fn run_repl_blocking(&self)

Run the existing REPL on the calling thread, then clean shutdown. Used by run_controller for back-compat with the CLI subcommand.