The host

What a Mojo application's main hands over: handlers and producers, workers, threads and a handler pool, flags, the doctor, every refusal and exit code.

m0_host is what a Mojo application's main calls. It owns the listener, the workers, the signals and the drain; the application supplies a handler and, if it has work on a cadence, a producer.

from m0_host.flags import host_config
from m0_host.host import ViewsApp, serve

from views import Items

def main() raises:
    serve[ViewsApp[Items]](host_config())

What an application supplies

serve[H, P](config) takes two types.

H: AppHandler is an HTTPService with a static make(ctx). The host calls make once per worker, after the fork, so each worker builds its own handler. Three more static methods have defaults:

An application whose state lives in the handler answers max_workers() -> 1. M0_WORKERS=2 is then refused at startup: two workers would hold two different copies.

ViewsApp[S] is the AppHandler for an application that is a views table. S: ViewState has make(ctx) and urls(), and the same three optional methods. Both scaffolds use it.

P: Producer is work on a cadence, off the event loop: make(ctx), and step(mut self, mut out: Publisher) -> Int, which returns the nanoseconds until the next step. One producer runs, on a thread of worker 0, and out.publish(channel, id, frame) reaches every worker's streams. Number frames with out.next_id(): the counter is shared memory, so it survives a worker being replaced. publish returns False for a frame a channel refused; count those. NoProducer is the default.

HostContext, the argument to every make:

A make that raises, in a handler or a producer, ends the process with exit 78 and its message. It is not retried.

Execution modes

One loop in one process is the default.

M0_WORKERS=N forks N processes that share the listener. A worker that dies is replaced. The worker that wins an accept hands the connection to the least-loaded sibling, so keep-alive load spreads.

M0_THREADS=N runs N loops on N threads of one process. Nothing is forked, so a runtime that cannot survive a fork (Core ML, CoreFoundation) works, and the loops share an address space. There is no supervisor: a loop that dies takes the process. It is refused beside M0_WORKERS above 1.

Measured against each other, threads and workers are level on throughput (0.95x to 1.03x) and on the tail, and threads use a fifth to a third less memory. Reach for workers first; use threads for one of the reasons above. ctx.worker and ctx.workers count either, so an application runs under both unchanged.

M0_BLOCKING_THREADS=N puts N handler threads behind each loop, and composes with either mode. The loop keeps accepting and parsing while a slow view runs on a pool thread. Each pool thread builds its own handler with make (ctx.thread says which). A view registered with add_loop, or on_loop=True, is answered on the loop and never queued. A stream must be opened on the loop: one begun on a pool thread is refused with 409.

Configuration

A flag overrides its M0_ variable, which overrides the default.

host_config() is an AppConfig with the command line applied, for an application that prints its own address before serving. serve(AppConfig()) applies the flags itself.

Exit codes and refusals

Every 78 is one line on stderr: what was found, then the fix in parentheses. The checks, in the order the host applies them:

A count is refused the same way whether it came from a flag or a variable.

The doctor

bin/server --doctor prints one JSON object as the last line of stdout and binds nothing. It holds the resolved configuration, where each value came from (flag, env or default), the topology that adds up to, what the application declares (max_workers, max_threads, page_slots), and a checks array in which every failure carries its fix. The API key is never printed. It exits with the code serving would exit with for the same arguments, because serve and the doctor read the same list of checks.

uv run m0 doctor runs the toolchain's checks first (platform, mojo-installed, mojo-gated, c-compiler, project), then this one.

Shutdown

SIGTERM and SIGINT drain: in-flight requests finish, held streams are closed from the server, and the process exits 0. The drain, the handler pool's join and the producer's join share one five-second bound. A thread still running after it is named on stderr and the process exits anyway, so docker stop never waits for SIGKILL. The binary runs correctly as PID 1.

The capability rows are E21 to E31 in Capabilities. The design is recorded in the Mojo host, loops on threads and flags and a doctor for the host.