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