acton_core/actor/
managed_agent.rs

1/*
2 * Copyright (c) 2024. Govcraft
3 *
4 * Licensed under either of
5 *   * Apache License, Version 2.0 (the "License");
6 *     you may not use this file except in compliance with the License.
7 *     You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
8 *   * MIT license: http://opensource.org/licenses/MIT
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the applicable License for the specific language governing permissions and
14 * limitations under that License.
15 */
16
17use std::fmt;
18use std::fmt::Debug;
19use std::fmt::Formatter;
20
21use acton_ern::prelude::*;
22use tokio::sync::mpsc::Receiver;
23use tokio_util::task::TaskTracker;
24
25pub use idle::Idle;
26
27use crate::common::{AgentHandle, AsyncLifecycleHandler, BrokerRef, HaltSignal, ParentRef, ReactorMap};
28use crate::message::Envelope;
29use crate::prelude::AgentRuntime;
30
31mod idle;
32/// Contains the `Started` type-state marker and associated implementations for running agents.
33pub mod started;
34
35/// Represents an agent whose lifecycle and message processing are managed by the Acton framework.
36///
37/// `ManagedAgent` acts as a runtime wrapper around user-defined agent logic and state (`Model`).
38/// It utilizes a type-state pattern via the `AgentState` generic parameter (e.g., [`Idle`], [`started::Started`])
39/// to enforce valid operations during different phases of the agent's lifecycle (configuration vs. active processing).
40///
41/// The framework handles the underlying task spawning, message reception from the `inbox`,
42/// dispatching messages to registered `message_handlers`, executing lifecycle hooks
43/// (like `before_start`, `after_stop`), and managing graceful shutdown via the `halt_signal`.
44///
45/// Users typically interact with `ManagedAgent` indirectly through an [`AgentHandle`] after the agent
46/// has been started, or directly during the configuration phase (when in the [`Idle`] state)
47/// to register message handlers and lifecycle hooks.
48///
49/// # Type Parameters
50///
51/// *   `AgentState`: A marker type (e.g., [`Idle`], [`started::Started`]) indicating the current lifecycle state of the agent.
52/// *   `Model`: The user-defined type containing the agent's state and associated logic. It must
53///     implement `Default`, `Send`, `Debug`, and be `'static`. Message handlers and lifecycle
54///     hooks operate on an instance of this `Model`.
55pub struct ManagedAgent<AgentState, Model: Default + Send + Debug + 'static> {
56    /// Handle for external interaction with this agent.
57    pub(crate) handle: AgentHandle,
58
59    /// Optional handle to the parent (supervisor) agent.
60    pub(crate) parent: Option<ParentRef>,
61
62    /// Handle to the system message broker.
63    pub(crate) broker: BrokerRef,
64
65    /// Signal used for initiating graceful shutdown.
66    pub(crate) halt_signal: HaltSignal,
67
68    /// The agent's unique and potentially hierarchical identifier.
69    pub(crate) id: Ern,
70    /// Reference to the Acton system runtime.
71    pub(crate) runtime: AgentRuntime,
72
73    /// The user-defined state and logic associated with this agent.
74    ///
75    /// This field holds the instance of the type provided as the `Model` generic
76    /// parameter. Message handlers (registered via `act_on` in the [`Idle`] state)
77    /// and lifecycle hooks (e.g., `before_start`, `after_stop`) receive mutable
78    /// access to this `model` to implement the agent's specific behavior and manage its data.
79    pub model: Model,
80
81    /// Tracks associated Tokio tasks, primarily the agent's main loop.
82    pub(crate) tracker: TaskTracker,
83
84    /// MPSC receiver for incoming messages.
85    pub(crate) inbox: Receiver<Envelope>,
86    /// Asynchronous hook executed before the agent starts its message loop.
87    pub(crate) before_start: AsyncLifecycleHandler<Model>,
88    /// Asynchronous hook executed after the agent starts its message loop.
89    pub(crate) after_start: AsyncLifecycleHandler<Model>,
90    /// Asynchronous hook executed just before the agent stops its message loop.
91    pub(crate) before_stop: AsyncLifecycleHandler<Model>,
92    /// Asynchronous hook executed after the agent stops its message loop.
93    pub(crate) after_stop: AsyncLifecycleHandler<Model>,
94    /// Map storing registered message handlers (`TypeId` -> handler function).
95    pub(crate) message_handlers: ReactorMap<Model>,
96    /// Phantom data to associate the `AgentState` type parameter.
97    _actor_state: std::marker::PhantomData<AgentState>,
98}
99
100// implement getter functions for ManagedAgent
101impl<AgentState, Model: Default + Send + Debug + 'static> ManagedAgent<AgentState, Model> {
102    /// Returns a reference to the agent's unique identifier (`Ern`).
103    #[inline]
104    pub fn id(&self) -> &Ern {
105        &self.id
106    }
107
108    /// Returns the root name segment of the agent's identifier (`Ern`).
109    #[inline]
110    pub fn name(&self) -> &str {
111        self.id.root.as_str()
112    }
113
114    /// Returns a reference to the agent's [`AgentHandle`].
115    ///
116    /// The handle is the primary means for external interaction with the agent
117    /// once it has started.
118    #[inline]
119    pub fn handle(&self) -> &AgentHandle {
120        &self.handle
121    }
122
123    /// Returns a reference to the optional parent agent's handle ([`ParentRef`]).
124    ///
125    /// Returns `None` if this is a top-level agent.
126    #[inline]
127    pub fn parent(&self) -> &Option<ParentRef> {
128        &self.parent
129    }
130
131    /// Returns a reference to the system message broker's handle ([`BrokerRef`]).
132    #[inline]
133    pub fn broker(&self) -> &BrokerRef {
134        &self.broker
135    }
136
137    /// Returns a reference to the [`AgentRuntime`] this agent belongs to.
138    #[inline]
139    pub fn runtime(&self) -> &AgentRuntime {
140        &self.runtime
141    }
142}
143
144impl<AgentState, Model: Default + Send + Debug + 'static> Debug
145for ManagedAgent<AgentState, Model>
146{
147    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
148        f.debug_struct("ManagedAgent")
149            .field("id", &self.id) // Changed from "key" to "id" for clarity
150            .field("model", &self.model) // Optionally include model debug info
151            .field("parent", &self.parent)
152            .field("broker", &self.broker)
153            // Avoid showing channels/handlers in Debug output
154            .finish_non_exhaustive() // Indicate not all fields are shown
155    }
156}
acton_core/actor/managed_agent.rs

acton_core/actor/
managed_agent.rs
