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

acton_core/
lib.rs
