Expand description
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 optionalon_start/on_stop/on_reloadlifecycle hooks, all with default no-op bodies.OpEvent: a lean mirror ofastrs_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 anOperator::on_eventcall decided —Status::ContinueorStatus::Finished.OpError/OpResult: this crate’s typed failure type.OperatorRegistryandregister_operator!: the static registration tableastrs-runtimeiterates to build the operators a manifest’soperators: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!
exports a type through a stable #[repr(C)] vtable
([dylib::OperatorVTable]) a shared library can be dlopened 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 AstrsMessage and the attribute as
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();
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]);Macros§
- register_
operator - Builds one
(name, constructor)registry entry for$ty.
Structs§
- OpOutput
- The buffered output side an
crate::Operatorwrites through. - OpSend
- One buffered send, ready for the runtime host to deliver.
- Operator
Registry - The static registration table
astrs-runtimeiterates by name.
Enums§
- OpError
- A failure inside the operator host’s boundary (blueprint §9.3).
- OpEvent
- One event delivered to an
crate::Operator(blueprint §9.3). - Status
- What an
Operator::on_eventcall decided.
Traits§
- Astrs
Message - A Rust type that maps onto a single-column AstRS payload (blueprint §6.1, §9.2).
- Operator
- An in-process dataflow stage hosted by
astrs-runtime(blueprint §9.3).
Type Aliases§
- OpResult
- The result type every
crate::Operatormethod and everycrate::OpOutputsend returns. - Operator
Constructor - A registered operator’s constructor.
Attribute Macros§
- operator
- Optional sugar adding a ready-made
astrs_operator_api::OperatorRegistryentry to anastrs_operator_api::Operatorimpl (blueprint §9.3).
Derive Macros§
- Astrs
Message - Derives
astrs_data::AstrsMessagefor a struct (blueprint §9.1, §9.2).