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//! actor system, built on top of Tokio. It establishes a robust, message-passing
24//! framework with clear separation of concerns for actor state, runtime management,
25//! communication, and lifecycle.
26//!
27//! ## Key Concepts
28//!
29//! - **Actors (`ManagedActor`)**: Core computational units wrapping user-defined state
30//!   and logic, managed by the runtime.
31//! - **Handles (`ActorHandle`)**: External references for interacting with actors
32//!   (sending messages, stopping, supervising).
33//! - **Messaging**: Asynchronous communication via Tokio MPSC channels, using
34//!   messages implementing the `ActonMessage` trait.
35//! - **Broker (`Broker`)**: Central publish-subscribe mechanism for topic-based
36//!   message distribution.
37//! - **Lifecycle & Supervision**: Type-state pattern (`Idle`, `Started`) for actors,
38//!   lifecycle hooks, and hierarchical supervision.
39//! - **Runtime (`ActorRuntime`)**: Manages the overall system, including actor
40//!   creation and shutdown.
41//! - **Traits**: Core interfaces (`ActorHandleInterface`, `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 actor 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/// IPC (Inter-Process Communication) module for external process integration.
68///
69/// This module provides Unix Domain Socket communication infrastructure for
70/// sending messages to actors from external processes.
71///
72/// This module provides all the public IPC types and functions for building
73/// IPC clients and working with the IPC infrastructure.
74///
75/// # Feature Gate
76///
77/// This module is only available when the `ipc` feature is enabled.
78#[cfg(feature = "ipc")]
79pub mod ipc {
80    pub use crate::common::ipc::{
81        socket_exists, socket_is_alive, start_listener, ActorInfo, IpcConfig, IpcDiscoverRequest,
82        IpcDiscoverResponse, IpcEnvelope, IpcError, IpcListenerHandle, IpcListenerStats,
83        IpcPushNotification, IpcResponse, IpcStreamFrame, IpcSubscribeRequest,
84        IpcSubscriptionResponse, IpcTypeRegistry, IpcUnsubscribeRequest, ProtocolCapabilities,
85        ProtocolVersionInfo, ShutdownResult,
86    };
87
88    /// Wire protocol for IPC message framing.
89    ///
90    /// This module provides functions for reading and writing IPC messages
91    /// using the length-prefixed binary wire protocol.
92    pub mod protocol {
93        pub use crate::common::ipc::protocol::{
94            is_discover, is_heartbeat, is_stream, is_subscribe, is_unsubscribe, read_envelope,
95            read_frame, read_response, write_discover, write_discover_with_format,
96            write_discovery_response, write_discovery_response_with_format, write_envelope,
97            write_envelope_with_format, write_frame, write_heartbeat, write_push_with_format,
98            write_response, write_response_with_format, write_stream_frame,
99            write_stream_frame_with_format, write_subscribe_with_format,
100            write_subscription_response, write_subscription_response_with_format,
101            write_unsubscribe_with_format, Format, ProtocolVersion, HEADER_SIZE, HEADER_SIZE_V1,
102            HEADER_SIZE_V2, MAX_FRAME_SIZE, MAX_SUPPORTED_VERSION, MIN_SUPPORTED_VERSION,
103            MSG_TYPE_DISCOVER, MSG_TYPE_ERROR, MSG_TYPE_HEARTBEAT, MSG_TYPE_PUSH, MSG_TYPE_REQUEST,
104            MSG_TYPE_RESPONSE, MSG_TYPE_STREAM, MSG_TYPE_SUBSCRIBE, MSG_TYPE_UNSUBSCRIBE,
105            PROTOCOL_VERSION,
106        };
107    }
108}
109
110/// A prelude module for conveniently importing the most commonly used items.
111///
112/// This module re-exports essential types, traits, and macros from the Acton
113/// framework and dependencies like `acton-ern` and `async-trait`, simplifying
114/// the import process for users.
115///
116/// # Re-exports
117///
118/// ## Macros (from `acton-macro`)
119/// *   [`acton_macro::acton_message`]: Attribute macro for defining Acton messages.
120/// *   [`acton_macro::acton_actor`]: Attribute macro for defining Acton actors.
121///
122/// ## External Crates
123/// *   [`acton_ern::*`](https://docs.rs/acton-ern): All items from the `acton-ern` crate for unique resource naming.
124/// *   [`async_trait::async_trait`](https://docs.rs/async-trait/latest/async_trait/attr.async_trait.html): The macro for defining async functions in traits.
125///
126/// ## Core Types
127/// *   [`crate::actor::ActorConfig`]: Configuration for creating new actors.
128/// *   [`crate::actor::Idle`]: Type-state marker for an actor before it starts.
129/// *   [`crate::actor::ManagedActor`]: The core actor structure managing state and runtime.
130/// *   [`crate::actor::Started`]: Type-state marker for a running actor.
131/// *   [`crate::common::ActonApp`]: Entry point for initializing the Acton system.
132/// *   [`crate::common::Broker`]: The central message broker implementation.
133/// *   [`crate::common::ActorHandle`]: Handle for interacting with an actor.
134/// *   [`crate::common::Reply`]: Utility for creating standard message handler return types.
135/// *   [`crate::common::ActorRuntime`]: Represents the initialized Acton runtime.
136/// *   [`crate::message::BrokerRequest`]: Wrapper for messages intended for broadcast.
137/// *   [`crate::message::BrokerRequestEnvelope`]: Specialized envelope for broadcast messages.
138/// *   [`crate::message::MessageAddress`]: Addressable endpoint of an actor.
139/// *   [`crate::message::OutboundEnvelope`]: Represents a message prepared for sending.
140/// *   [`crate::traits::ActonMessage`]: Marker trait for all valid messages.
141/// *   [`crate::traits::ActorHandleInterface`]: Core trait defining actor interaction methods.
142/// *   [`crate::traits::Broker`]: Trait defining message broadcasting capabilities.
143/// *   [`crate::traits::Subscribable`]: Trait for managing message subscriptions.
144/// *   [`crate::traits::Subscriber`]: Trait for accessing the message broker.
145///
146/// ## IPC Types (requires `ipc` feature)
147/// *   [`crate::common::ipc::IpcTypeRegistry`]: Registry for IPC message type deserialization.
148/// *   [`crate::common::ipc::IpcEnvelope`]: Envelope format for IPC messages.
149/// *   [`crate::common::ipc::IpcResponse`]: Response envelope format for IPC.
150/// *   [`crate::common::ipc::IpcError`]: Error types for IPC operations.
151/// *   [`crate::common::ipc::IpcConfig`]: Configuration for IPC listener.
152/// *   [`crate::common::ipc::IpcListenerHandle`]: Handle for managing IPC listener lifecycle.
153/// *   [`crate::common::ipc::IpcListenerStats`]: Statistics for IPC listener.
154pub mod prelude {
155    // Macros from acton-macro
156    pub use acton_macro::*;
157
158    // External crate re-exports
159    pub use acton_ern::*;
160    pub use async_trait::async_trait;
161    pub use tokio;
162
163    // Core types
164    pub use crate::actor::{
165        ActorConfig, Idle, ManagedActor, RestartLimitExceeded, RestartLimiter, RestartLimiterConfig,
166        RestartPolicy, RestartStats, Started, SupervisionDecision, SupervisionStrategy,
167        TerminationReason,
168    };
169    pub use crate::common::{ActonApp, ActorHandle, ActorRuntime, Broker, Reply};
170    pub use crate::message::{
171        BrokerRequest, BrokerRequestEnvelope, ChildTerminated, MessageAddress, OutboundEnvelope,
172    };
173    pub use crate::traits::{
174        ActonMessage, ActorHandleInterface, Broadcaster, Subscribable, Subscriber,
175    };
176
177    // IPC types (feature-gated)
178    #[cfg(feature = "ipc")]
179    pub use crate::common::ipc::{
180        IpcConfig, IpcEnvelope, IpcError, IpcListenerHandle, IpcListenerStats, IpcResponse,
181        IpcTypeRegistry, ShutdownResult,
182    };
183}
acton_reactive/lib.rs

acton_reactive/
lib.rs
