titanrt/
lib.rs

1//! # TitanRt
2//!
3//! Model‑first, typed reactive runtime for real‑time systems.
4//!
5//! This crate focuses on **models that own connectors and streams**. The runtime
6//! only orchestrates lifecycle (start/restart/hot‑reload/shutdown) and back‑pressure,
7//! while your model pulls typed events from its streams and pushes typed actions back.
8//!
9//! **Read the full guide & architecture in the project README.**
10//! – <https://crates.io/crates/titanrt>
11//!
12//! ## When to use
13//! - You need a compact event loop with predictable back‑pressure.
14//! - You want typed boundaries between model, I/O adapters and state.
15//! - You care about graceful, hierarchical cancellation and optional core pinning.
16//!
17//! ## Core types (jump in)
18//! - [`runtime::Runtime`] — control thread that feeds commands and drives the model.
19//! - [`model::BaseModel`] — your app logic (owns connectors/streams).
20//! - [`connector::BaseConnector`] — spawns typed worker **streams**.
21//! - [`connector::Stream`] — handle with action TX, event RX, health, state and cancel.
22//! - [`utils::CancelToken`] — hierarchical cooperative cancellation.
23//!
24//! ## Minimal model loop (owning a stream)
25//! ```rust,ignore
26//! use titanrt::model::{BaseModel, ExecutionResult, StopKind, StopState};
27//! use titanrt::runtime::{Runtime, RuntimeConfig};
28//! use titanrt::utils::CancelToken;
29//! use titanrt::io::base::{NullTx};
30//! use anyhow::Result;
31//!
32//! // Your connector implements StreamRunner + StreamSpawner; omitted here.
33//! // struct EchoConnector { /* ... */ }
34//! // impl BaseConnector for EchoConnector { /* ... */ }
35//!
36//! struct MyModel {
37//!     // connector: EchoConnector,
38//!     // echo: Stream<...>, echo_tx: ..., echo_rx: ...
39//! }
40//!
41//! impl BaseModel for MyModel {
42//!     type Config   = ();
43//!     type OutputTx = NullTx;         // or your own transport
44//!     type Event    = ();             // events normally come from streams, not control plane
45//!     type Ctx      = ();
46//!
47//!     fn initialize(_: (), _: (), _: Option<usize>, _: NullTx, _cancel: CancelToken) -> Result<Self> {
48//!         // 1) Build connector(s) and spawn stream(s) here.
49//!         // 2) Keep action_tx, event_rx and state handles in the model.
50//!         Ok(Self{})
51//!     }
52//!
53//!     fn execute(&mut self) -> ExecutionResult {
54//!         // Drain events from stream(s), push actions if needed, publish state snapshots.
55//!         // self.echo.try_recv().ok();
56//!         ExecutionResult::Relax
57//!     }
58//!
59//!     fn on_event(&mut self, _e: Self::Event) {}
60//!
61//!     fn stop(&mut self, _kind: StopKind) -> StopState {
62//!         // Cancel and join streams here.
63//!         StopState::Done
64//!     }
65//! }
66//!
67//! fn main() -> Result<()> {
68//!     let cfg = RuntimeConfig {
69//!         init_model_on_start: true,
70//!         core_id: None,
71//!         max_inputs_pending: Some(1024),
72//!         max_inputs_drain: Some(64),
73//!         stop_model_timeout: Some(5),
74//!     };
75//!     let rt = Runtime::<MyModel>::spawn(cfg, (), (), NullTx)?;
76//!     rt.run_blocking()?;
77//!     Ok(())
78//! }
79//! ```
80//!
81//! ## Notes
82//! - Prefer delivering data via **streams** (event plane inside the model).
83//!   Use the control plane for **commands** only.
84//! - Pin to specific cores through stream descriptors and [`utils::CorePickPolicy`].
85//! - See README for a full, compiling connector/stream example and real transports.
86//!
87//! ---
88//! Re‑exports live under modules like `runtime`, `model`, `connector`, `io`, and `utils`.
89
90pub mod config;
91pub mod control;
92pub mod error;
93pub mod io;
94pub mod model;
95pub mod runtime;
96mod test;
97pub mod utils;
98
99pub mod bridges;
100#[cfg(feature = "connector")]
101pub mod connector;
102pub mod prelude;
titanrt/lib.rs

titanrt/
lib.rs
