Skip to main content

Operator

Trait Operator 

Source
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§

Source

fn on_event(&mut self, event: &OpEvent, out: &mut OpOutput) -> OpResult<Status>

Handles one event, optionally producing output.

§Errors

Any crate::OpError the operator wants to report as a failure (surfaced as NodeFailed by the host, blueprint §9.3).

Provided Methods§

Source

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).

Source

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.

Source

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.

Source

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".

Implementors§