pub trait Device: Send + Sync {
// Provided methods
fn report(&self) -> Report { ... }
fn oper(&self) -> OperStatus { ... }
fn identity(&self) -> Identity { ... }
fn next_event<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<DeviceEvent, DeviceError>> + Send + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait { ... }
fn close<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<(), DeviceError>> + Send + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait { ... }
fn configuration(&self) -> Option<&dyn Configure> { ... }
fn actions(&self) -> Option<&dyn Actions> { ... }
}Expand description
A device: anything the driver serves on the management plane.
The core and introspection planes of docs/design/device-planes.md, and
nothing about how bytes move — that is Medium for an SDU device, and
a netdev’s is the kernel’s. Every method is defaulted, because a device
that says nothing about itself is a legitimate device and every simulator
was one until #49; the split from the old Backend (#117) changed no
behaviour, only which trait a method belongs to.
Provided Methods§
Sourcefn report(&self) -> Report
fn report(&self) -> Report
What this device says about itself.
Defaulted to “nothing”, because a medium that knows nothing about its
own condition is a legitimate medium and every simulator was one until
#49. Sync rather than async on purpose: the driver calls this from
mgmt/telemetry.rs’s five-second publish loop, and an async signature
would invite a backend to put an AT-command round trip there. A device
that needs I/O to answer keeps atomics and a cached snapshot, and says
how old the snapshot is through Report::age_ms.
Decorators must forward this. Seven of this crate’s implementors wrap
another Medium, and one that inherits the default answers None to
everything — which reads as “unknown” rather than as a wrong number, but
is still a lie about the medium underneath. The conformance kit’s
conformance::medium_decorator_forwards is what catches it, and it
covers the whole trait rather than this method alone — which is new: the
check this comment named for three issues asserted report and
nothing else, and close, configure_lanes and next_event had gone
unforwarded behind the claim (#50, #51, #52).
Sourcefn oper(&self) -> OperStatus
fn oper(&self) -> OperStatus
Whether this device is working, as RFC 2863 has it (#121).
Sync and cached, for report’s reason. Defaulted to
OperStatus::unknown: a device that cannot tell says so, and the
plane publishes that rather than a guess. A medium that has failed
need not report it here — the driver knows, and overlays down with
recoverable: false on whatever the device says. What a device does
know that the driver cannot is the recoverable kind of down: a
coverage gap, a closed contact window, a carrier that dropped.
Decorators must forward this, like everything else here.
Sourcefn identity(&self) -> Identity
fn identity(&self) -> Identity
What this device is (#122): RFC 8348’s fields and the bearer’s equipment identifier, as much of it as the device knows.
Sync and cached, for report’s reason: a modem
reads its model, firmware and IMEI once, at open, and answers from
that. Defaulted to Identity::unknown, which is a legitimate
answer — the management plane publishes it as a document with only
the device’s name, and a reader knows the device was asked. The plane
polls it and raises identity_change when it differs: a terminal
swapped, or its firmware updated, under a running driver.
Never a subscriber identifier (I5). Decorators must forward this, like everything else here.
Sourcefn next_event<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<DeviceEvent, DeviceError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn next_event<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<DeviceEvent, DeviceError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
Wait for the next thing the medium wants to say.
Mirrors recv deliberately: a driver drains this in
its own task, so a backend may block here for as long as it likes and a
medium with nothing to report simply never resolves. The default is
exactly that, which is why every medium in this workspace needs no
implementation.
Edge-triggered. One event when a condition starts and one when it
stops, not a repeat while it persists — see Edge. A backend that
repeated itself would produce a rate the events keyspace cannot
honestly declare, and the driver deduplicating on its behalf would be
guessing at which repeats meant something.
Sourcefn close<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<(), DeviceError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn close<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = Result<(), DeviceError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
Stop, cleanly.
Called once, on the way down, after every lane task has been aborted and before the process exits. The default does nothing, because an in-process medium has nothing to release.
A real device does (#50). Teardown used to be: Driver::shutdown
aborts its tasks, the Arc<dyn Medium> is dropped, and anything a
radio needed to be told happened in Drop with no async available. A
radio left keyed, or a modem left in binary-write mode, is the
observable consequence — and neither is visible while a simulator is the
only implementor, because a simulator never needs telling.
Errors are reported and not propagated: the process is going away, and there is nothing a caller could do differently. Say what failed.
Sourcefn configuration(&self) -> Option<&dyn Configure>
fn configuration(&self) -> Option<&dyn Configure>
This device’s configuration plane, if it has one (#125).
None is the honest default: a device with nothing to configure
declares no resource, and the management plane serves none for it.
Sourcefn actions(&self) -> Option<&dyn Actions>
fn actions(&self) -> Option<&dyn Actions>
The operator actions this device offers (#129): explicit, costed,
never scheduled — an operator deciding, once, now. None for a
device with none. There is no reset and there will not be one
(architecture §4.11): recovery is a restart, of the device (the
driver’s own reopen action) or of the daemon (#96).
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".