Module bitvec::ptr

Expand description

Mirror of the core::ptr module and bitvec-specific pointer structures.

Types

As bitvec is not the standard library, it does not have the freedom to use language builtins such as actual pointers. Instead, bitvec uses its own analagous structures:

BitPtr<M, O, T>: This represents a pointer to a single bit, and is vaguely similar to *const bool, *mut bool, and NonNull<bool>. It consists of a (non-null, well-aligned) pointer to a T memory element and a bit-index within that element. It uses the O ordering implementation to access the selected bit, and uses M to determine whether it has write permissions to the location.
BitPtrRange<M, O, T>: This is equivalent to Range<BitPtr<M, O, T>>. It exists because Range has some associated types that are still unstable to implement for its type parameters. It is also smaller than the Range would be, because it can take advantage of layout optimizations.
BitRef<M, O, T>: This is a proxy reference type, equivalent to the C++ bitset<N>::reference. It implements Deref and, if M is Mut, DerefMut to bool, so that it can be read from and written to as if it were an &bool or &mut bool. It is not a referent type, and cannot be used in APIs that expect actual references. It is implemented under the hood as a BitPtr with a bool cached in one of the padding bytes.
BitSpan<M, O, T>: This is a crate-internal type that encodes a BitPtr and a length counter into a two-word structure that can be transmuted into *BitSlice<O, T>. This type enforces the non-null/well-aligned rule, and is the source of the limitation that bitvec region types can only address ⅛ of a usize, rather than the ½ limitation of the standard library collections.

This type is not public API; it will only ever appear in its transmuted form, *BitSlice<O, T>. Users are not permitted to use any of the core::ptr or pointer functions to view or modify *BitSlice pointers, or their referent locations, in any way.

The functions in this module take bitvec equivalents to raw pointers as their arguments and read from or write to them. For this to be safe, these pointers must be valid. Whether a pointer is valid depends on the operation it is used for (reading or writing), and the extent of the memory that is accessed (i.e. how many bits are read/written in and how many underlying memory elements are accessed). Most functions use BitPtr to access only a single bit, in which case the documentation omits the size and implicitly assumes it to be one bit in one T element.

The Rust rules about pointer validity are always in effect; bitvec refines them to a bit-precision granularity, but must still respect the byte-level and element-level rules.

Crate-Specific Restrictions

bitvec uses an internal encoding scheme to make bit-region pointers fit into a standard Rust slice pointer. This encoding requires that the base element address of a bit-pointer be non-null and well-aligned for all pointers that are used in the encoding scheme.

The bitvec structure used to emulate a pointer to a single bit is larger than one processor word, and thus cannot be encoded to fit in a *const Bit. To ease internal complexity, these restrictions are universal in bitvec: the crate as a whole refuses to operate on null pointers, or pointers that are not aligned to their referent type, even if your usage never touches the span encoding.

As such, the pointer types in this module can essentially only be sourced from references, not from arbitrary address values. While this module attempts to rely on actual Rust references as much as possible, and instead use only the ordinary core::ptr and pointer functions. This is not always possible; in particular, Rust does not offer stable atomic intrinsics, and instead only allows them to be used on references.

!

Structs

Address

A non-null, well-aligned, BitStore element address.

BitPtr

Pointer to an individual bit in a memory element. Analagous to *bool.

BitPtrRange

Equivalent to Range<BitPtr<M, O, T>>.

BitRef

A proxy reference, equivalent to C++ std::bitset<N>::reference.

Const

An immutable pointer.

Mut

A mutable pointer. Contexts with a Mutable may lower to Immutable, then re-raise to Mutable; contexts with Immutable may not raise to Mutable on their own.

Enums

AddressError

An error produced when consuming BitStore memory addresses.

BitPtrError

Errors produced by invalid bit-pointer components.

BitSpanError

An error produced when creating BitSpan encoded references.

Functions

bitslice_from_raw_parts

Forms a raw bit-slice from a bit-pointer and a length.

bitslice_from_raw_parts_mut

Performs the same functionality as bitslice_from_raw_parts, except that a raw mutable bit-slice is returned, as opposed to a raw immutable bit-slice.

copy ^⚠

Copies count bits from src to dst. The source and destination may overlap.

copy_nonoverlapping ^⚠

Copies count bits from src to dst. The source and destination must not overlap.

eq

Compares raw bit-pointers for equality.

hash

Hash a raw bit-pointer.

read ^⚠

Reads the bit from src.

read_volatile ^⚠

Performs a volatile read of the bit from src.