Struct Environment 

pub struct Environment { /* private fields */ }

High-level container that owns one or more runtimes, exposes a unified event receiver, and provides lifecycle helpers for running and shutting down the underlying actor system.

Run lifecycle state machine

An internal [RuntimeLaunchState] records how runtimes were last started:

• Idle — no active launch mode; safe to call run() or run_background().
• Managed — run spawned a join handle tracked by this environment. Await it with wait or stop with shutdown.
• Background — run_background started runtimes without storing a handle on the environment. Call shutdown before run().

run() and run_background() both call reconcile_finished_managed_launch first. When a managed run task finished without wait() or shutdown(), that helper joins the stale handle and surfaces any runtime or join error before a new launch proceeds.

wait temporarily takes the managed join handle. If the future is dropped early (for example when another branch wins in tokio::select!), [RestoreRunHandleOnDrop] puts the handle back so a later shutdown() can still stop runtimes and join the task. A successful wait() clears the handle and returns the launch state to Idle.

Implementations

impl Environment

pub fn new(config: Option<EnvironmentConfig>) -> Self

Create a new environment with optional configuration.

pub async fn register_runtime( &mut self, runtime: Arc<dyn Runtime>, ) -> Result<(), Error>

Register a runtime with this environment and make it the default if none is set yet.

pub fn config(&self) -> &EnvironmentConfig

Access the environment configuration.

pub async fn get_runtime( &self, runtime_id: &RuntimeID, ) -> Option<Arc<dyn Runtime>>

Get a runtime by its id, if present.

pub async fn get_runtime_or_default( &self, runtime_id: Option<RuntimeID>, ) -> Result<Arc<dyn Runtime>, Error>

Get the specified runtime or the default one when None is passed.

pub fn run(&mut self) -> Result<(), EnvironmentError>

Start all registered runtimes in the background.

Stores the spawned task handle so shutdown can stop runtimes and await completion. Returns EnvironmentError::AlreadyRunning if a run task is already in progress.

If a previous managed run task finished without wait or shutdown, its result is joined and returned before spawning a new run task.

Use wait to await the background run task, or shutdown to stop runtimes and join the task.

pub async fn wait(&mut self) -> Result<Result<(), RuntimeError>, JoinError>

Await the background task started by run.

Returns Ok(Ok(())) when no run task has been started. After the task completes, the stored handle is cleared so subsequent calls return immediately.

If this future is dropped before completion (for example when a tokio::select! branch wins elsewhere), the join handle is restored on the environment so a later shutdown can still stop runtimes and join the run task.

pub async fn run_background(&mut self) -> Result<(), EnvironmentError>

Start all registered runtimes and return immediately without waiting for completion.

Cannot be combined with run on the same environment instance without calling shutdown first.

pub async fn take_event_receiver( &mut self, runtime_id: Option<RuntimeID>, ) -> Result<BoxEventStream<Event>, EnvironmentError>

Take the event receiver for a specific runtime (or the default one) so the caller can consume protocol events. This can only be taken once.

pub async fn subscribe_events( &self, runtime_id: Option<RuntimeID>, ) -> Result<BoxEventStream<Event>, EnvironmentError>

Subscribe to runtime events without consuming the receiver.

pub async fn shutdown(&mut self) -> Result<(), EnvironmentError>

Request shutdown on all runtimes and await the run handle if present.

pub fn is_running(&self) -> bool

Returns whether the environment has an active runtime launch.

For run this checks the managed join handle. For run_background this returns true until shutdown clears the launch state.