pub trait Operator: Send + 'static {
// Required method
fn on_event(
&mut self,
event: &OpEvent,
out: &mut OpOutput,
) -> OpResult<Status>;
// Provided methods
fn configure(
&mut self,
config: &BTreeMap<String, Parameter>,
) -> OpResult<()> { ... }
fn on_start(&mut self, out: &mut OpOutput) -> OpResult<()> { ... }
fn on_stop(&mut self, out: &mut OpOutput) -> OpResult<()> { ... }
fn on_reload(&mut self, out: &mut OpOutput) -> OpResult<()> { ... }
}Expand description
An in-process dataflow stage hosted by astrs-runtime (blueprint §9.3).
pub trait Operator: Default + Send {
fn on_event(&mut self, event: &OpEvent, out: &mut OpOutput) -> OpResult<Status>;
}
astrs::register_operator!(MyOp);is the blueprint’s own sketch (quoted verbatim, hence untested as code
— it does not compile, which is exactly the point below); this trait
realizes it faithfully with one
necessary correction. §9.3 also writes Operator: Default + Send, but
the registry it describes in the same breath —
Box<dyn Fn() -> Box<dyn Operator>> — requires Box<dyn Operator> to be
a legal type, and a trait with Default as a supertrait is not
object-safe (Default::default() has no receiver to dispatch on). This
trait therefore drops Default from its own supertraits and asks for it
at the registration site instead: register_operator!
requires $ty: Default on the type it wraps, so a registered operator
is exactly as default-constructible as the blueprint intends, enforced
at the one place that actually needs it.
Operators compile into the runtime binary via the registry macro by
default — static dispatch, the flagship path. A type that implements
this trait can also be exported from a cdylib via
[crate::export_dylib_operator] (the dylib feature) and loaded at
dlopen time by astrs-runtime’s dylib-operators feature — the same
trait either way; only how the host obtains a Box<dyn Operator>
differs. Each operator runs on its own thread over a bounded channel;
panics are caught, reported as NodeFailed, and honor the operator’s
restart policy without tearing down siblings (blueprint §9.3) — none of
which this trait needs to know about, since it is the contract the
host schedules against, not the scheduler itself.
§Lifecycle
Operator::configure runs once immediately after construction, before
Operator::on_start and before any event — it is how this operator
instance receives its own entry’s manifest config: map (blueprint
§9.3’s operators: list), the one thing Default::default() itself
cannot supply. Operator::on_start runs once after that, before the
first Operator::on_event. Operator::on_stop runs once, when the
host is winding the operator down (typically because
Operator::on_event returned Status::Finished or an
OpEvent::Stop arrived). Operator::on_reload runs on
OpEvent::Reload instead of routing it through on_event, so an
operator that only cares about resetting state does not need a
catch-all arm in its own event match. All four default to a no-op, so a
minimal operator implements only on_event.
Required Methods§
Provided Methods§
Sourcefn configure(&mut self, config: &BTreeMap<String, Parameter>) -> OpResult<()>
fn configure(&mut self, config: &BTreeMap<String, Parameter>) -> OpResult<()>
Runs once immediately after construction, before
Operator::on_start.
config is this operator instance’s manifest config: map
(astrs_manifest::OperatorConfig::config, converted from JSON to
this crate’s own Parameter vocabulary by astrs-runtime — the
same closed value set OpEvent::ParamUpdate already carries, so
an operator author reads static construction-time configuration and
live parameter updates through one shared set of types rather than
two). Because the host always builds a fresh operator via
Default::default() (blueprint §9.3’s static registry), this hook
— not the constructor — is where a crop/nms-style operator
reads a threshold, a label set, or any other per-instance setting
its wiring alone does not carry.
Runs again, with the same map, on every restarted incarnation
(blueprint §9.3): a fresh Default::default() has no memory of the
previous incarnation’s configuration, so re-delivering it here is
what makes a restarted operator behave like the manifest describes
rather than like a blank slate.
The default does nothing, which is correct for an operator with no configuration of its own.
§Errors
Any crate::OpError the operator wants to refuse its
configuration with — folded into the same restart/give-up decision
as any other failed hook (blueprint §9.3).
Sourcefn on_start(&mut self, out: &mut OpOutput) -> OpResult<()>
fn on_start(&mut self, out: &mut OpOutput) -> OpResult<()>
Runs once before the first Operator::on_event call.
The default does nothing.
§Errors
Any crate::OpError the operator wants to fail startup with.
Sourcefn on_stop(&mut self, out: &mut OpOutput) -> OpResult<()>
fn on_stop(&mut self, out: &mut OpOutput) -> OpResult<()>
Runs once when the host is winding the operator down.
The default does nothing. A operator that wants to flush a final
message overrides this instead of trying to catch OpEvent::Stop
in Operator::on_event and remembering to still return
Status::Finished.
§Errors
Any crate::OpError the operator wants to report.
Sourcefn on_reload(&mut self, out: &mut OpOutput) -> OpResult<()>
fn on_reload(&mut self, out: &mut OpOutput) -> OpResult<()>
Runs on OpEvent::Reload instead of on_event.
The default does nothing, which is the correct behavior for an operator with no state to reset.
§Errors
Any crate::OpError the operator wants to report.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".