acton_reactive/
lib.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
17#![forbid(unsafe_code)]
18#![forbid(missing_docs)] // Keep this to enforce coverage
19
20//! # Acton Reactive
21//!
22//! This crate provides the foundational components for the Acton asynchronous
23//! agent system, built on top of Tokio. It establishes a robust, message-passing
24//! framework with clear separation of concerns for agent state, runtime management,
25//! communication, and lifecycle.
26//!
27//! ## Key Concepts
28//!
29//! - **Agents (`ManagedAgent`)**: Core computational units wrapping user-defined state
30//!   and logic, managed by the runtime.
31//! - **Handles (`AgentHandle`)**: External references for interacting with agents
32//!   (sending messages, stopping, supervising).
33//! - **Messaging**: Asynchronous communication via Tokio MPSC channels, using
34//!   messages implementing the `ActonMessage` trait.
35//! - **Broker (`AgentBroker`)**: Central publish-subscribe mechanism for topic-based
36//!   message distribution.
37//! - **Lifecycle & Supervision**: Type-state pattern (`Idle`, `Started`) for agents,
38//!   lifecycle hooks, and hierarchical supervision.
39//! - **Runtime (`AgentRuntime`)**: Manages the overall system, including agent
40//!   creation and shutdown.
41//! - **Traits**: Core interfaces (`AgentHandleInterface`, `Broker`, `Subscriber`, etc.)
42//!   define the framework's capabilities.
43//!
44//! ## Quick Start
45//!
46//! ```rust,ignore
47//! use acton_reactive::prelude::*;
48//!
49//! #[acton_message]
50//! struct MyMessage {
51//!     content: String,
52//! }
53//! ```
54
55/// Internal utilities and structures used throughout the Acton framework.
56pub(crate) mod common;
57
58/// Defines the core agent structures and logic.
59pub(crate) mod actor;
60
61/// Defines message types and envelopes used for communication.
62pub(crate) mod message;
63
64/// Defines core traits used throughout the Acton framework.
65pub(crate) mod traits;
66
67/// A prelude module for conveniently importing the most commonly used items.
68///
69/// This module re-exports essential types, traits, and macros from the Acton
70/// framework and dependencies like `acton-ern` and `async-trait`, simplifying
71/// the import process for users.
72///
73/// # Re-exports
74///
75/// ## Macros (from `acton-macro`)
76/// *   [`acton_macro::acton_message`]: Attribute macro for defining Acton messages.
77/// *   [`acton_macro::acton_actor`]: Attribute macro for defining Acton actors.
78///
79/// ## External Crates
80/// *   [`acton_ern::*`](https://docs.rs/acton-ern): All items from the `acton-ern` crate for unique resource naming.
81/// *   [`async_trait::async_trait`](https://docs.rs/async-trait/latest/async_trait/attr.async_trait.html): The macro for defining async functions in traits.
82///
83/// ## Core Types
84/// *   [`crate::actor::AgentConfig`]: Configuration for creating new agents.
85/// *   [`crate::actor::Idle`]: Type-state marker for an agent before it starts.
86/// *   [`crate::actor::ManagedAgent`]: The core agent structure managing state and runtime.
87/// *   [`crate::actor::Started`]: Type-state marker for a running agent.
88/// *   [`crate::common::ActonApp`]: Entry point for initializing the Acton system.
89/// *   [`crate::common::AgentBroker`]: The central message broker implementation.
90/// *   [`crate::common::AgentHandle`]: Handle for interacting with an agent.
91/// *   [`crate::common::AgentReply`]: Utility for creating standard message handler return types.
92/// *   [`crate::common::AgentRuntime`]: Represents the initialized Acton runtime.
93/// *   [`crate::message::BrokerRequest`]: Wrapper for messages intended for broadcast.
94/// *   [`crate::message::BrokerRequestEnvelope`]: Specialized envelope for broadcast messages.
95/// *   [`crate::message::MessageAddress`]: Addressable endpoint of an agent.
96/// *   [`crate::message::OutboundEnvelope`]: Represents a message prepared for sending.
97/// *   [`crate::traits::ActonMessage`]: Marker trait for all valid messages.
98/// *   [`crate::traits::AgentHandleInterface`]: Core trait defining agent interaction methods.
99/// *   [`crate::traits::Broker`]: Trait defining message broadcasting capabilities.
100/// *   [`crate::traits::Subscribable`]: Trait for managing message subscriptions.
101/// *   [`crate::traits::Subscriber`]: Trait for accessing the message broker.
102pub mod prelude {
103    // Macros from acton-macro
104    pub use acton_macro::*;
105
106    // External crate re-exports
107    pub use acton_ern::*;
108    pub use async_trait::async_trait;
109
110    // Core types
111    pub use crate::actor::{AgentConfig, Idle, ManagedAgent, Started};
112    pub use crate::common::{ActonApp, AgentBroker, AgentHandle, AgentReply, AgentRuntime};
113    pub use crate::message::{BrokerRequest, BrokerRequestEnvelope, MessageAddress, OutboundEnvelope};
114    pub use crate::traits::{ActonMessage, AgentHandleInterface, Broker, Subscribable, Subscriber};
115}
acton_reactive/lib.rs

acton_reactive/
lib.rs
