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> { ... }
    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§

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

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

Source

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.

Source

fn counters(&self) -> Vec<Counter>

Counters beyond the fixed vocabulary (#157): a layer’s refusals, a module’s frames. Empty by default. Sync and cached, like report; the management plane publishes those the registry declares, gated by scope. Decorators must forward this.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§