Module global_context

Expand description

Process-global context, root client actor, external-runtime registrations, and supervision bridge.

This module has two separate root-context roles:

Rust callers use the lazy [GLOBAL_CONTEXT] path, exposed through context(), this_host(), and this_proc(). A singleton Host is created with the GlobalClientActor on its local_proc.
External runtimes such as Python do not use [GLOBAL_CONTEXT]. They may register their already-bootstrapped client root meshes through register_client_host and register_client_proc. Registration getters are non-bootstrapping and must not initialize [GLOBAL_CONTEXT].

let cx = context().await;
cx.actor_instance    // c.f. Python: context().actor_instance
this_host().await    // c.f. Python: this_host()
this_proc().await    // c.f. Python: this_proc()

§Undeliverables → supervision

When the runtime detects that a message cannot be delivered, it produces an Undeliverable<MessageEnvelope>. The global root client observes these failures, converts them into ActorSupervisionEvents, and forwards them to the currently active mesh supervision sink.

GC-1 (undeliverable routing): Any Undeliverable<MessageEnvelope> observed by the global root client must be reported as an ActorSupervisionEvent to the active ProcMesh, and handling that failure must never crash the global client. The root client acts as a monitor, not a participant: routing failures are treated as signals to be reported, not fatal errors.

§Multiple ProcMeshes

A process may allocate more than one ProcMesh (e.g. internal/controller meshes plus an application mesh). The root client is a process-wide singleton, so its supervision sink is also process-global.

The active mesh is defined using last-sink-wins semantics: each newly allocated ProcMesh installs its sink, overriding the previous one.

If no sink has been installed yet (early/late binding), undeliverables are logged and dropped, preserving forward progress until a mesh becomes available.

§External runtime registration

GC-2 (external registration is non-bootstrapping): External-runtime registration lookups must never initialize the lazy Rust [GLOBAL_CONTEXT]. They read only already-initialized cells via .get() (OnceCell::get for GLOBAL_CONTEXT, OnceLock::get for the registration slots), never a get_or_init. In particular, try_registered_client_proc returns only the externally registered proc mesh and deliberately ignores any coexisting Rust global context; absence is reported as None, not filled by bootstrapping a Rust root.

Structs§

GlobalClientActor: Process-global “root client” actor.
GlobalContext: Process-global Monarch context for Rust programs. Symmetric with Python’s context().

Functions§

context: Returns the process-global Monarch context, lazily initialized.
register_client_host: Register the client host mesh from an external runtime (Python). Called by Python’s bootstrap_host() so that try_this_host() can discover C for the A/C invariant. First registration wins: a later call is silently ignored (the OnceLock is already set).
register_client_proc: Register the client proc mesh from an external runtime (Python). Mirrors register_client_host; called from Python’s bootstrap_host() so try_registered_client_proc can discover the client proc. First registration wins: a later call is silently ignored (the OnceLock is already set).
this_host: Returns the singleton HostMesh c.f. Python’s this_host().
this_proc: Returns the local ProcMesh c.f Python’s this_proc().
try_registered_client_proc: Returns the externally-registered client proc mesh, or None if none was registered. Non-bootstrapping: reads only the registration (.get(), never get_or_init), so it never spins up GLOBAL_CONTEXT. This getter has a single source of truth: it reads only the external registration; a coexisting Rust GLOBAL_CONTEXT root is ignored, with no fallback (unlike try_this_host, which does consult GLOBAL_CONTEXT).
try_this_host: Returns the client host mesh if available, without triggering lazy bootstrap. Checks both the Rust global context and the external registration (Python). Used by MeshAdminAgent to discover C at query time (A/C invariant).