mmo-runtime

Runtime library for MMO gRPC tools.

Worker execution

stream_in_worker(workflow, request, ctx, *, pool=None, timeout=None) yields ProgressEvent objects in order, then one ResultEnvelope or ErrorEnvelope. Even without a supplied pool the workflow runs on a worker thread, so progress is available before completion. Progress is buffered up to 64 events; slow consumers apply backpressure rather than dropping events or growing memory without bound. Close abandoned iterators to release blocked producers.

Timeout is measured from the first iterator advance and includes queue time. None disables the deadline; zero (or a negative value) expires immediately. Cancellation, timeout, and iterator closure signal ctx.cancel and cancel jobs which have not started. Running workflows must cooperatively check the token and bound their own blocking I/O. Python threads are not forcibly terminated; an uncooperative job can retain its worker slot and delay process exit.

run_in_worker retains its legacy (terminal, progress_list) API, including inline execution without a pool and pooled cancellation/admission exceptions. Its accumulated progress list is intentionally not memory-bounded; use the streaming API for long-running jobs. WorkerPool.shutdown(cancel_futures=True) cancels waiting jobs; it does not interrupt running jobs.

Transport and lifecycle

ToolClient.channel is public for constructing service stubs. Unary and stream calls accept deadline (including zero) and keyword-only metadata, a sequence of (key, value) pairs. Unknown error-envelope codes normalize to INTERNAL. Unavailable transports map to retryable PROVIDER_ERROR; resource exhaustion, invalid requests, cancellation, and expired deadlines retain their error codes. Health polling limits each probe and sleep to the remaining polling budget.

Plain Unix socket paths, explicit unix:// targets, TCP host:port (including IPv6), and resolver targets are normalized without duplicate Unix prefixes. The default on Windows is 127.0.0.1:50051; choose explicit per-tool ports to avoid collisions. Unix keeps /tmp/tool.sock as its default.

The server tracks the full handler lifetime of unary and streaming application RPCs. Health probes do not keep an otherwise idle server alive. The idle period restarts after the last active handler exits. Shutdown is one-shot, marks health not-serving, signals the server cancellation token, waits for gRPC's graceful stop, then cleans up transport resources and invokes on_stop once. Signal handlers are installed only on the Unix main thread and restored on exit. An instance is single-use; create a new instance to restart.

The server cancellation token is available for embedded workflows; generated servicers use their own per-RPC token and gRPC cancellation callback. Graceful shutdown therefore lets existing generated RPCs finish until grace expires. Neither job_timeout_sec nor the server token is automatically injected into arbitrary registered handlers: pass explicit worker deadlines and cancellation tokens when implementing custom handlers.