pub struct ActorRuntime(/* private fields */);Expand description
Represents the initialized and active Acton actor system runtime.
This struct is obtained after successfully launching the system via [ActonApp::launch_async().await].
It holds the internal state of the running system, including a reference to the
central message broker and a registry of top-level actors.
ActorRuntime provides the primary methods for interacting with the system as a whole,
such as creating new top-level actors (new_actor, spawn_actor, etc.) and initiating
a graceful shutdown of all actors (shutdown_all).
It is cloneable, allowing different parts of an application to hold references to the runtime environment.
Implementations§
Source§impl ActorRuntime
impl ActorRuntime
Sourcepub fn new_actor_with_name<State>(
&mut self,
name: String,
) -> ManagedActor<Idle, State>
pub fn new_actor_with_name<State>( &mut self, name: String, ) -> ManagedActor<Idle, State>
Creates a new top-level actor builder (ManagedActor<Idle, State>) with a specified root name.
This method initializes a ManagedActor in the Idle state, configured with a
root Ern derived from the provided name and linked to the system’s broker.
The actor is registered as a top-level actor within the runtime.
The returned actor is ready for further configuration (e.g., adding message handlers
via act_on) before being started by calling .start() on it.
§Type Parameters
State: The user-defined state type for the actor. Must implementDefault,Send,Debug, and be'static.
§Arguments
name: A string that will form the root name of the actor’sErn.
§Returns
A ManagedActor<Idle, State> instance, ready for configuration and starting.
§Panics
Panics if creating the root Ern from the provided name fails or if creating the internal ActorConfig fails.
Sourcepub fn new_actor<State>(&mut self) -> ManagedActor<Idle, State>
pub fn new_actor<State>(&mut self) -> ManagedActor<Idle, State>
Creates a new top-level actor builder (ManagedActor<Idle, State>) with a default name (“actor”).
Similar to ActorRuntime::new_actor_with_name, but uses a default root name “actor”
for the actor’s Ern. The actor is registered as a top-level actor within the runtime.
The returned actor is ready for further configuration before being started via .start().
§Type Parameters
State: The user-defined state type for the actor. Must implementDefault,Send,Debug, and be'static.
§Returns
A ManagedActor<Idle, State> instance, ready for configuration and starting.
§Panics
Panics if creating the internal ActorConfig fails.
Sourcepub fn actor_count(&self) -> usize
pub fn actor_count(&self) -> usize
Returns the number of top-level actors currently registered in the runtime.
This count only includes actors directly created via the ActorRuntime and
does not include child actors supervised by other actors.
Sourcepub fn new_actor_with_config<State>(
&mut self,
config: ActorConfig,
) -> ManagedActor<Idle, State>
pub fn new_actor_with_config<State>( &mut self, config: ActorConfig, ) -> ManagedActor<Idle, State>
Creates a new top-level actor builder (ManagedActor<Idle, State>) using a provided configuration.
This method initializes a ManagedActor in the Idle state using the specified
ActorConfig. It ensures the actor is configured with the system’s broker if not
already set in the config. The actor is registered as a top-level actor within the runtime.
The returned actor is ready for further configuration before being started via .start().
§Type Parameters
State: The user-defined state type for the actor. Must implementDefault,Send,Debug, and be'static.
§Arguments
config: TheActorConfigto use for the new actor. The broker field will be overridden with the system broker if it’sNone.
§Returns
A ManagedActor<Idle, State> instance, ready for configuration and starting.
Sourcepub fn broker(&self) -> ActorHandle
pub fn broker(&self) -> ActorHandle
Returns a clone of the handle ([BrokerRef]) to the system’s central message broker.
Sourcepub async fn spawn_actor_with_setup_fn<State>(
&mut self,
config: ActorConfig,
setup_fn: impl FnOnce(ManagedActor<Idle, State>) -> Pin<Box<dyn Future<Output = ActorHandle> + Send + 'static>>,
) -> Result<ActorHandle>
pub async fn spawn_actor_with_setup_fn<State>( &mut self, config: ActorConfig, setup_fn: impl FnOnce(ManagedActor<Idle, State>) -> Pin<Box<dyn Future<Output = ActorHandle> + Send + 'static>>, ) -> Result<ActorHandle>
Creates, configures, and starts a top-level actor using a provided configuration and setup function.
This method combines actor creation (using config), custom asynchronous setup (setup_fn),
and starting the actor. The setup_fn receives the actor in the Idle state, performs
necessary configurations (like adding message handlers), and must call .start() to
transition the actor to the Started state, returning its ActorHandle.
The actor is registered as a top-level actor within the runtime.
§Type Parameters
State: The state type of the actor. Must implementDefault,Send,Debug, and be'static.
§Arguments
config: TheActorConfigto use for creating the actor. The broker field will be overridden with the system broker if it’sNone.setup_fn: An asynchronous closure that takes theManagedActor<Idle, State>, configures it, calls.start(), and returns the resultingActorHandle. The closure must beSend + 'static.
§Returns
A Result containing the ActorHandle of the successfully spawned actor, or an error if
actor creation or the setup_fn fails.
Sourcepub async fn shutdown_all(&mut self) -> Result<()>
pub async fn shutdown_all(&mut self) -> Result<()>
Initiates a graceful shutdown of the entire Acton system.
This method attempts to stop all registered top-level actors (and consequently their
descendant children through the stop propagation mechanism) by sending them a
[SystemSignal::Terminate]. It waits for all top-level actor tasks to complete.
Finally, it stops the central message broker actor.
§Returns
An anyhow::Result<()> indicating whether the shutdown process completed successfully.
Errors during the stopping of individual actors or the broker will be propagated.
Sourcepub async fn spawn_actor<State>(
&mut self,
setup_fn: impl FnOnce(ManagedActor<Idle, State>) -> Pin<Box<dyn Future<Output = ActorHandle> + Send + 'static>>,
) -> Result<ActorHandle>
pub async fn spawn_actor<State>( &mut self, setup_fn: impl FnOnce(ManagedActor<Idle, State>) -> Pin<Box<dyn Future<Output = ActorHandle> + Send + 'static>>, ) -> Result<ActorHandle>
Creates, configures, and starts a top-level actor using a default configuration and a setup function.
This is a convenience method similar to ActorRuntime::spawn_actor_with_setup_fn, but it
automatically creates a default ActorConfig (with a default name and the system broker).
The provided setup_fn configures and starts the actor.
The actor is registered as a top-level actor within the runtime.
§Type Parameters
State: The state type of the actor. Must implementDefault,Send,Debug, and be'static.
§Arguments
setup_fn: An asynchronous closure that takes theManagedActor<Idle, State>, configures it, calls.start(), and returns the resultingActorHandle. The closure must beSend + 'static.
§Returns
A Result containing the ActorHandle of the successfully spawned actor, or an error if
actor creation or the setup_fn fails.
§Errors
Returns an error if the default ActorConfig cannot be created.
Trait Implementations§
Source§impl Clone for ActorRuntime
impl Clone for ActorRuntime
Source§fn clone(&self) -> ActorRuntime
fn clone(&self) -> ActorRuntime
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more