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> { ... }
fn security(&self) -> Option<SecurityProperties> { ... }
fn counters(&self) -> Vec<Counter> { ... }
}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. Several implementors in this workspace
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).
Sourcefn security(&self) -> Option<SecurityProperties>
fn security(&self) -> Option<SecurityProperties>
What this device guarantees about the bytes it carries (I6), as
properties. None, the default, is a device that provides nothing,
which every medium in this workspace is: the management plane
publishes that as provider: none with an empty guarantee set, never
as encrypted: false. A layer that seals SDUs, or a radio that
encrypts below the driver, answers with what it provides and only
that. Decorators must forward this, like everything else here.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".