Skip to main content

Device

Trait Device 

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

Source

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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Implementors§