Struct wlan_common::sequestered::Sequestered

pub struct Sequestered<T>(/* private fields */);

Isolates data such that it is inaccessible without explicitly releasing it.

Sequestered data cannot be directly read nor written while contained (though it can be trivially replaced). This is useful for data that must be “ferried” through a system but should not generally be examined nor inspected, in particular when inspection of the data would otherwise seem innocuous but implicitly violates a design contract or introduces an unwanted data dependency.

This type cannot completely prevent reads and writes. Rather, it makes reads and writes very explicit and more obvious in order to avoid mistakes in data APIs.

Sequestering data is trivial and is done via the core From and Into traits. Releasing data is intentionally more explicit and requires the use of fully-qualified syntax that names the Sequestered type.

As sequestered data is considered a “black box”, Sequestered only implements the Clone and Debug traits (so long as the type T provides implementations). Note that Copy is not implemented, because releasing data would not be strictly affine and data could be implicitly copied out of fields via release. This is not only implicit, but can be counterintuitive in some contexts, because release moves a copy of the Sequestered.

Sequestered also implements PartialEq largely for testing. See https://fxbug.dev/42067751.

Implementations

impl<T> Sequestered<T>

pub fn release(sequestered: Self) -> T

Releases the sequestered data.

Releasing should be performed sparingly, carefully, and typically at API boundaries where there is no longer a need to prevent reads of the data. Releases, which are explicit, should be given extra scrutiny, somewhat like unsafe code.

This function does not use a receiver and so requires fully-qualified syntax in order to make releases more explicit and obvious.

Examples

// Sequester data.
let text: Sequestered<&'static str> = "lorem ipsum".into();
// Release data. The fully-qualified syntax is required.
let text = Sequestered::release(text);

Trait Implementations

impl<T: Clone> Clone for Sequestered<T>

fn clone(&self) -> Sequestered<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Sequestered<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> From<T> for Sequestered<T>

fn from(inner: T) -> Self

Converts to this type from the input type.

impl<T: PartialEq> PartialEq for Sequestered<T>

fn eq(&self, other: &Sequestered<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> StructuralPartialEq for Sequestered<T>