pub struct AgentRuntime(/* private fields */);Expand description
Represents the initialized and active Acton agent system runtime.
This struct is obtained after successfully launching the system via ActonApp::launch().
It holds the internal state of the running system, including a reference to the
central message broker and a registry of top-level agents.
AgentRuntime provides the primary methods for interacting with the system as a whole,
such as creating new top-level agents (new_agent, spawn_agent, etc.) and initiating
a graceful shutdown of all agents (shutdown_all).
It is cloneable, allowing different parts of an application to hold references to the runtime environment.
Implementations§
Source§impl AgentRuntime
impl AgentRuntime
Sourcepub async fn new_agent_with_name<State>(
&mut self,
name: String,
) -> ManagedAgent<Idle, State>
pub async fn new_agent_with_name<State>( &mut self, name: String, ) -> ManagedAgent<Idle, State>
Creates a new top-level agent builder (ManagedAgent<Idle, State>) with a specified root name.
This method initializes a ManagedAgent in the Idle state, configured with a
root Ern derived from the provided name and linked to the system’s broker.
The agent is registered as a top-level agent within the runtime.
The returned agent 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 agent. Must implementDefault,Send,Debug, and be'static.
§Arguments
name: A string that will form the root name of the agent’sErn.
§Returns
A ManagedAgent<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 AgentConfig fails.
Sourcepub async fn new_agent<State>(&mut self) -> ManagedAgent<Idle, State>
pub async fn new_agent<State>(&mut self) -> ManagedAgent<Idle, State>
Creates a new top-level agent builder (ManagedAgent<Idle, State>) with a default name (“agent”).
Similar to AgentRuntime::new_agent_with_name, but uses a default root name “agent”
for the agent’s Ern. The agent is registered as a top-level agent within the runtime.
The returned agent is ready for further configuration before being started via .start().
§Type Parameters
State: The user-defined state type for the agent. Must implementDefault,Send,Debug, and be'static.
§Returns
A ManagedAgent<Idle, State> instance, ready for configuration and starting.
§Panics
Panics if creating the internal AgentConfig fails.
Sourcepub fn agent_count(&self) -> usize
pub fn agent_count(&self) -> usize
Returns the number of top-level agents currently registered in the runtime.
This count only includes agents directly created via the AgentRuntime and
does not include child agents supervised by other agents.
Sourcepub async fn new_agent_with_config<State>(
&mut self,
config: AgentConfig,
) -> ManagedAgent<Idle, State>
pub async fn new_agent_with_config<State>( &mut self, config: AgentConfig, ) -> ManagedAgent<Idle, State>
Creates a new top-level agent builder (ManagedAgent<Idle, State>) using a provided configuration.
This method initializes a ManagedAgent in the Idle state using the specified
AgentConfig. It ensures the agent is configured with the system’s broker if not
already set in the config. The agent is registered as a top-level agent within the runtime.
The returned agent is ready for further configuration before being started via .start().
§Type Parameters
State: The user-defined state type for the agent. Must implementDefault,Send,Debug, and be'static.
§Arguments
config: TheAgentConfigto use for the new agent. The broker field will be overridden with the system broker if it’sNone.
§Returns
A ManagedAgent<Idle, State> instance, ready for configuration and starting.
Sourcepub fn broker(&self) -> AgentHandle
pub fn broker(&self) -> AgentHandle
Returns a clone of the handle ([BrokerRef]) to the system’s central message broker.
Sourcepub async fn spawn_agent_with_setup_fn<State>(
&mut self,
config: AgentConfig,
setup_fn: impl FnOnce(ManagedAgent<Idle, State>) -> Pin<Box<dyn Future<Output = AgentHandle> + Send + 'static>>,
) -> Result<AgentHandle>
pub async fn spawn_agent_with_setup_fn<State>( &mut self, config: AgentConfig, setup_fn: impl FnOnce(ManagedAgent<Idle, State>) -> Pin<Box<dyn Future<Output = AgentHandle> + Send + 'static>>, ) -> Result<AgentHandle>
Creates, configures, and starts a top-level agent using a provided configuration and setup function.
This method combines agent creation (using config), custom asynchronous setup (setup_fn),
and starting the agent. The setup_fn receives the agent in the Idle state, performs
necessary configurations (like adding message handlers), and must call .start() to
transition the agent to the Started state, returning its AgentHandle.
The agent is registered as a top-level agent within the runtime.
§Type Parameters
State: The state type of the agent. Must implementDefault,Send,Debug, and be'static.
§Arguments
config: TheAgentConfigto use for creating the agent. The broker field will be overridden with the system broker if it’sNone.setup_fn: An asynchronous closure that takes theManagedAgent<Idle, State>, configures it, calls.start(), and returns the resultingAgentHandle. The closure must beSend + 'static.
§Returns
A Result containing the AgentHandle of the successfully spawned agent, or an error if
agent 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 agents (and consequently their
descendant children through the stop propagation mechanism) by sending them a
[SystemSignal::Terminate]. It waits for all top-level agent tasks to complete.
Finally, it stops the central message broker agent.
§Returns
An anyhow::Result<()> indicating whether the shutdown process completed successfully.
Errors during the stopping of individual agents or the broker will be propagated.
Sourcepub async fn spawn_agent<State>(
&mut self,
setup_fn: impl FnOnce(ManagedAgent<Idle, State>) -> Pin<Box<dyn Future<Output = AgentHandle> + Send + 'static>>,
) -> Result<AgentHandle>
pub async fn spawn_agent<State>( &mut self, setup_fn: impl FnOnce(ManagedAgent<Idle, State>) -> Pin<Box<dyn Future<Output = AgentHandle> + Send + 'static>>, ) -> Result<AgentHandle>
Creates, configures, and starts a top-level agent using a default configuration and a setup function.
This is a convenience method similar to AgentRuntime::spawn_agent_with_setup_fn, but it
automatically creates a default AgentConfig (with a default name and the system broker).
The provided setup_fn configures and starts the agent.
The agent is registered as a top-level agent within the runtime.
§Type Parameters
State: The state type of the agent. Must implementDefault,Send,Debug, and be'static.
§Arguments
setup_fn: An asynchronous closure that takes theManagedAgent<Idle, State>, configures it, calls.start(), and returns the resultingAgentHandle. The closure must beSend + 'static.
§Returns
A Result containing the AgentHandle of the successfully spawned agent, or an error if
agent creation or the setup_fn fails.
§Errors
Returns an error if the default AgentConfig cannot be created.
Trait Implementations§
Source§impl Clone for AgentRuntime
impl Clone for AgentRuntime
Source§fn clone(&self) -> AgentRuntime
fn clone(&self) -> AgentRuntime
1.0.0 · Source§const fn clone_from(&mut self, source: &Self)
const fn clone_from(&mut self, source: &Self)
source. Read moreSource§impl Debug for AgentRuntime
impl Debug for AgentRuntime
Source§impl Default for AgentRuntime
impl Default for AgentRuntime
Source§fn default() -> AgentRuntime
fn default() -> AgentRuntime
Source§impl From<ActonApp> for AgentRuntime
Converts an ActonApp marker into an initialized AgentRuntime.
impl From<ActonApp> for AgentRuntime
Converts an ActonApp marker into an initialized AgentRuntime.
This implementation defines the system bootstrap process triggered by ActonApp::launch().
It performs the following steps:
- Spawns a background Tokio task dedicated to initializing the
AgentBroker. - Uses a
oneshotchannel to receive theAgentHandleof the initialized broker back from the background task. - Blocks the current thread using
tokio::task::block_in_placewhile waiting for the broker initialization to complete. This ensures thatActonApp::launch()does not return until the core system components (like the broker) are ready. - Constructs the
AgentRuntimeusing the received broker handle.
Warning: The use of block_in_place means this conversion should typically
only happen once at the very start of the application within the main thread
or a dedicated initialization thread, before the main asynchronous workload begins.
Calling this from within an existing Tokio runtime task could lead to deadlocks
or performance issues.