Enum BitDomain

pub enum BitDomain<'a, M = Const, T = usize, O = Lsb0>
where
    M: Mutability,
    T: 'a + BitStore,
    O: BitOrder,
    Address<M, BitSlice<T, O>>: Referential<'a>,
    Address<M, BitSlice<T::Unalias, O>>: Referential<'a>,
{
    Enclave(Reference<'a, M, BitSlice<T, O>>),
    Region {
        head: Reference<'a, M, BitSlice<T, O>>,
        body: Reference<'a, M, BitSlice<T::Unalias, O>>,
        tail: Reference<'a, M, BitSlice<T, O>>,
    },
}

Bit-Slice Partitioning

This enum partitions a bit-slice into its head- and tail- edge bit-slices, and its interior body bit-slice, according to the definitions laid out in the module documentation.

It fragments a BitSlice into smaller BitSlices, and allows the interior bit-slice to become ::Unaliased. This is useful when you need to retain a bit-slice view of memory, but wish to remove synchronization costs imposed by a prior call to .split_at_mut() for as much of the bit-slice as possible.

Why Not Option?

The Enclave variant always contains as its single field the exact bit-slice that created the Enclave. As such, this type is easily replaceäble with an Option of the Region variant, which when None is understood to be the original.

This exists as a dedicated enum, even with a technically useless variant, in order to mirror the shape of the element-domain enum. This type should be understood as a shortcut to the end result of splitting by element-domain, then mapping each PartialElement and slice back into BitSlices, rather than testing whether a bit-slice can be split on alias boundaries.

You can get the alternate behavior, of testing whether or not a bit-slice can be split into a Region or is unsplittable, by calling .bit_domain().region() to produce exactly such an Option.

Variants

Enclave(Reference<'a, M, BitSlice<T, O>>)

Indicates that a bit-slice’s contents are entirely in the interior indices of a single memory element.

The contained value is always the bit-slice that created this view.

Region

Indicates that a bit-slice’s contents touch an element edge.

This splits the bit-slice into three partitions, each of which may be empty: two partially-occupied edge elements, with their original type status, and one interior span, which is known to not have any other aliases derived from the bit-slice that created this view.

Fields

head: Reference<'a, M, BitSlice<T, O>>

Any bits that partially-fill the first element of the underlying storage region.

This does not modify its aliasing status, as it will already be appropriately marked before this view is constructed.

body: Reference<'a, M, BitSlice<T::Unalias, O>>

Any bits that wholly-fill elements in the interior of the bit-slice.

This is marked as unaliased, because it is statically impossible for any other handle derived from the source bit-slice to have conflicting access to the region of memory it describes. As such, even a bit-slice that was marked as ::Alias can revert this protection on the known-unaliased interior.

Proofs:

• Rust’s &/&mut exclusion rules universally apply. If a reference exists, no other reference has unsynchronized write capability.
• BitStore::Unalias only modifies unsynchronized types. Cell and atomic types unalias to themselves, and retain their original behavior.

tail: Reference<'a, M, BitSlice<T, O>>

Any bits that partially-fill the last element of the underlying storage region.

This does not modify its aliasing status, as it will already be appropriately marked before this view is constructed.

Implementations

impl<'a, M, T, O> BitDomain<'a, M, T, O>

where M: Mutability, T: 'a + BitStore, O: BitOrder, Address<M, BitSlice<T, O>>: Referential<'a>, Address<M, BitSlice<T::Unalias, O>>: Referential<'a>,

pub fn enclave(self) -> Option<Reference<'a, M, BitSlice<T, O>>>

Attempts to unpack the bit-domain as an Enclave variant. This is just a shorthand for explicit destructuring.

pub fn region( self, ) -> Option<(Reference<'a, M, BitSlice<T, O>>, Reference<'a, M, BitSlice<T::Unalias, O>>, Reference<'a, M, BitSlice<T, O>>)>

Attempts to unpack the bit-domain as a Region variant. This is just a shorthand for explicit destructuring.

Trait Implementations

impl<T, O> Clone for BitDomain<'_, Const, T, O>

where T: BitStore, O: BitOrder,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a, M, T, O> Debug for BitDomain<'a, M, T, O>

where M: Mutability, T: 'a + BitStore, O: BitOrder, Address<M, BitSlice<T, O>>: Referential<'a>, Address<M, BitSlice<T::Unalias, O>>: Referential<'a>, Reference<'a, M, BitSlice<T, O>>: Debug, Reference<'a, M, BitSlice<T::Unalias, O>>: Debug,

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

Formats the value using the given formatter.

impl<'a, M, T, O> Default for BitDomain<'a, M, T, O>

where M: Mutability, T: 'a + BitStore, O: BitOrder, Address<M, BitSlice<T, O>>: Referential<'a>, Address<M, BitSlice<T::Unalias, O>>: Referential<'a>, Reference<'a, M, BitSlice<T, O>>: Default, Reference<'a, M, BitSlice<T::Unalias, O>>: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<T, O> Copy for BitDomain<'_, Const, T, O>

where T: BitStore, O: BitOrder,