Skip to main content

astrs_operator_api/
lib.rs

1//! The AstRS operator API.
2//!
3//! Operators are lightweight stages that share one event loop inside an
4//! `astrs-runtime` host (blueprint §9.3):
5//!
6//! - [`Operator`]: the trait a stage implements — event handling plus
7//!   optional `on_start`/`on_stop`/`on_reload` lifecycle hooks, all with
8//!   default no-op bodies.
9//! - [`OpEvent`]: a lean mirror of `astrs_wire::NodeEvent` — the five
10//!   variants an operator, as opposed to the node hosting it, ever needs.
11//! - [`OpOutput`]: the buffered send side an operator writes through
12//!   instead of holding a connection.
13//! - [`Status`]: what an [`Operator::on_event`] call decided —
14//!   [`Status::Continue`] or [`Status::Finished`].
15//! - [`OpError`] / [`OpResult`]: this crate's typed failure type.
16//! - [`OperatorRegistry`] and [`register_operator!`](crate::register_operator): the static
17//!   registration table `astrs-runtime` iterates to build the operators a
18//!   manifest's `operators:` node names.
19//!
20//! Operators are Rust trait objects by default — the flagship,
21//! zero-overhead path (blueprint §9.3). The optional `dylib` feature adds a
22//! second path: [`export_dylib_operator!`](crate::export_dylib_operator)
23//! exports a type through a stable `#[repr(C)]` vtable
24//! ([`dylib::OperatorVTable`]) a shared library can be `dlopen`ed and
25//! driven through, consumed by `astrs-runtime`'s `dylib-operators` feature
26//! (blueprint §9.3, §22). See the [`dylib`] module docs for the ABI itself.
27//!
28//! # Typed messages
29//!
30//! `astrs-data` owns the [`astrs_data::AstrsMessage`] trait
31//! (`astrs-operator-macros` — a normal dependency of this crate — hosts
32//! the derive itself, `#[derive(AstrsMessage)]`, plus `#[operator]`
33//! sugar for [`Operator`]; see that crate's docs for why the trait and the
34//! derive that implements it live in different crates). Both the trait and
35//! the derive/attribute macros are re-exported here — the trait as
36//! [`AstrsMessage`], and (in the macro namespace, so the shared name is no
37//! conflict) the derive as [`derive@AstrsMessage`] and the attribute as
38//! [`macro@operator`] — so `use astrs_operator_api::*;` reaches everything
39//! a node or operator author needs in one import, matching the unified
40//! feel of blueprint §9.1's own `use astrs::prelude::*;`.
41//!
42//! # Quick tour
43//!
44//! ```
45//! use astrs_operator_api::{Operator, OpEvent, OpOutput, OpResult, Status, register_operator};
46//!
47//! #[derive(Default)]
48//! struct Echo;
49//!
50//! impl Operator for Echo {
51//!     fn on_event(&mut self, event: &OpEvent, out: &mut OpOutput) -> OpResult<Status> {
52//!         match event {
53//!             OpEvent::Input { metadata, payload, .. } => {
54//!                 out.send_bytes("echo", metadata.clone(), payload.clone())?;
55//!                 Ok(Status::Continue)
56//!             }
57//!             OpEvent::Stop { .. } => Ok(Status::Finished),
58//!             _ => Ok(Status::Continue),
59//!         }
60//!     }
61//! }
62//!
63//! let registry = astrs_operator_api::OperatorRegistry::from_entries([
64//!     register_operator!(Echo),
65//! ])?;
66//! let mut echo = registry.build("Echo")?;
67//! let mut out = OpOutput::new();
68//! # use astrs_time::HlcTimestamp;
69//! # use astrs_wire::{DataId, Metadata};
70//! let event = OpEvent::Input {
71//!     id: DataId::new("in")?,
72//!     source: "camera/image".parse()?,
73//!     metadata: Metadata::new(HlcTimestamp::EPOCH),
74//!     payload: vec![1, 2, 3],
75//! };
76//! assert_eq!(echo.on_event(&event, &mut out)?, Status::Continue);
77//! assert_eq!(out.drain()[0].payload(), &[1, 2, 3]);
78//! # Ok::<(), Box<dyn std::error::Error>>(())
79//! ```
80
81#[cfg(feature = "dylib")]
82pub mod dylib;
83mod error;
84mod event;
85mod operator;
86mod output;
87mod registry;
88
89pub use crate::error::{OpError, OpResult};
90pub use crate::event::OpEvent;
91pub use crate::operator::{Operator, Status};
92pub use crate::output::{OpOutput, OpSend};
93pub use crate::registry::{OperatorConstructor, OperatorRegistry};
94
95pub use astrs_data::AstrsMessage;
96// `AstrsMessage` here names the *derive macro* (macro namespace); the line
97// above names the *trait* (type namespace) — the same pattern `serde`
98// itself uses to offer `Serialize` as both a trait and a derive from one
99// `use` path, and legal for the same reason: the two never collide.
100pub use astrs_operator_macros::{AstrsMessage, operator};