Enum bitvec::domain::DomainMut

pub enum DomainMut<'a, T> where
    T: BitStore,  {
    Enclave {
        head: BitIdx<T::Mem>,
        elem: &'a T::Access,
        tail: BitTail<T::Mem>,
    },
    Region {
        head: Option<(BitIdx<T::Mem>, &'a T::Access)>,
        body: &'a mut [T::Unalias],
        tail: Option<(&'a T::Access, BitTail<T::Mem>)>,
    },
}

Granular representation of the memory region containing a BitSlice.

BitSlice regions can be described in terms of edge and center partitions, where the edge partitions must retain the aliasing status of the source BitSlice handle, and the center partition is known to be completely unaliased by any other view. This property allows any BitSlice handle to be decomposed into smaller regions, and safely remove any aliasing markers from the center partition that no longer requires such safeguarding.

This enum splits the underlying element slice [T] into the maybe-aliased edge elements and known-unaliased center elements. If you do not need to work with the memory elements directly, and only need to firmly specify the access behavior of the BitSlice handle, use the BitDomain and BitDomainMut enums.

Lifetimes

• 'a: The lifetime of the referent storage region.

Type Parameters

• T: The register type of the source BitSlice handle, including any aliasing markers.

Mutability

The immutable view produces T::Alias references, which permit foreign writes to the referent location but disallow writes through itself. The mutable view produces T::Access references, because &mut _ references can only ever be produced when no other aliasing handle exists. The write permissions must be weakened from &mut T::Alias to &T::Access in order to satisfy the Rust memory rules.

The edge references do not forbid modifying bits outside of the source BitSlice domain, and writes out of bounds will be correctly handled by any other handles capable of viewing those elements. Doing so is still incorrect, though defined, and you are responsible for writing only within bounds when using DomainMut.

Variants

Enclave

Fields

head: BitIdx<T::Mem>

The start index of the BitSlice.

elem: &'a T::Access

An aliased view of the element containing the BitSlice.

This is necessary even on immutable views, because other views to the referent element may be permitted to modify it.

tail: BitTail<T::Mem>

The end index of the BitSlice.

Indicates that a BitSlice is contained entirely in the interior indices of a single memory element.

Region

Fields

head: Option<(BitIdx<T::Mem>, &'a T::Access)>

If the BitSlice started in the interior of its first element, this contains the starting index and the base address.

body: &'a mut [T::Unalias]

All fully-spanned, unaliased, elements.

This is marked as bare memory without any access protections, because it is statically impossible for any other handle to have write access to the region it covers. As such, a BitSlice that was marked as entirely aliased, but contains interior unaliased elements, can safely remove its aliasing protections.

tail: Option<(&'a T::Access, BitTail<T::Mem>)>

If the BitSlice ended in the interior of its last element, this contains the ending index and the last address.

Indicates that a BitSlice region touches at least one edge index of any number of elements.

This contains two optional references to the aliased edges, and one reference to the unaliased middle. Each can be queried and used individually.

Implementations

impl<'a, T> DomainMut<'a, T> where
    T: BitStore, 

pub fn enclave(self) -> Option<(BitIdx<T::Mem>, &'a T::Access, BitTail<T::Mem>)>

Attempts to view the domain as an enclave variant.

Parameters

• self

Returns

If self is the Enclave variant, this returns Some of the enclave fields, as a tuple. Otherwise, it returns None.

pub fn region(
    self
) -> Option<(Option<(BitIdx<T::Mem>, &'a T::Access)>, &'a mut [T::Unalias], Option<(&'a T::Access, BitTail<T::Mem>)>)>

Attempts to view the domain as the region variant.

Parameters

• self

Returns

If self is the Region variant, this returns Some of the region fields, as a tuple. Otherwise, it returns None.

Trait Implementations

impl<'a, T: Debug> Debug for DomainMut<'a, T> where
    T: BitStore,
    T::Mem: Debug,
    T::Access: Debug,
    T::Mem: Debug,
    T::Mem: Debug,
    T::Access: Debug,
    T::Unalias: Debug,
    T::Access: Debug,
    T::Mem: Debug, 

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

Formats the value using the given formatter.