Module runtime_identity 

Runtime-identity tagging: which Tokio runtime a thread belongs to.

Monarch runs Python on more than one Tokio runtime: the shared control-plane runtime that drives PythonActor dispatch, and separate data-plane runtimes where GIL work runs safely, off the control plane (the tensor streams; the RDMA managers, during buffer registration). The hazard is contention on the shared runtime, where a thread holding the GIL while blocked stalls every actor loop, supervisor, and network task on it. So data-plane work runs on its own runtime, and control-plane GIL use is kept to brief, sanctioned sites. This module records a thread’s RuntimeKind (stamped at thread start via on_thread_start, read via current_runtime_kind) so GIL-entry sites can tell the two apart. An unstamped thread is not owned by a Monarch runtime and reads as None.

Invariants (RI-*)

• RI-1 (unstamped-is-none): current_runtime_kind returns None on any thread no runtime builder has tagged.
• RI-2 (tagging-is-thread-local-and-once): tag_current_thread sets only the current OS thread’s marker, and only once.
• RI-3 (data-plane-workers-tagged): build_data_plane_runtime stamps every worker thread of the runtime it returns DataPlane(label), via the builder’s on_thread_start.
• RI-4 (tagging-does-not-leak): spawning work onto a tagged runtime does not change the spawning thread’s observed kind.
• RI-5 (process-lifetime-runtime): the handle from build_data_plane_runtime is kept alive by the DATA_PLANE_RUNTIMES registry and stays valid until the runtime is torn down by shutdown_data_plane_runtimes at process teardown; callers must not spawn onto it afterward.
• RI-6 (block-on-host-tagged): a data-plane runtime hosted on a manually spawned thread that drives its work via rt.block_on must tag that hosting thread explicitly; on_thread_start stamps only the runtime’s own worker threads, not the block_on caller.
• RI-7 (teardown-registered): every runtime from build_data_plane_runtime is registered in DATA_PLANE_RUNTIMES and shut down by shutdown_data_plane_runtimes. The pyo3 layer calls that at Python teardown before Py_Finalize; this crate stays Python-free.

Enums

RuntimeKind

Which kind of Tokio runtime a thread belongs to.

Functions

build_data_plane_runtime

Build a dedicated data-plane runtime on its own OS thread, tagged DataPlane(label), and return a handle for spawning onto it.

current_runtime_kind

The RuntimeKind of the current thread, if it is stamped.

shutdown_data_plane_runtimes

Shut down every data-plane runtime built by build_data_plane_runtime, waiting up to timeout for each. Idempotent: a second call finds an empty registry and does nothing. Pure Rust (no Python); the pyo3 layer must call this at Python teardown, before Py_Finalize, so data-plane workers stop before the interpreter is finalized.

tag_current_thread

Stamp the current thread with kind. Call from a runtime builder’s on_thread_start so every worker of that runtime carries the marker.