Struct HeaderMetadataSpec

pub struct HeaderMetadataSpec {
    pub bit_offset: isize,
    pub num_of_bits: usize,
}

This struct stores the specification of a header metadata bit-set. It supports either bits metadata of 1-7 bits in the same byte, or u8/u16/u32/u64 at an offset of their natural alignment.

For performance reasons, objects of this struct should be constants.

Fields

bit_offset: isize

bit_offset is the index of the starting bit from which the data should be read or written. It is counted from the right (least significant bit) of the byte. Positive values refer to the bit positions within the current byte, starting with 0 for the least significant bit (rightmost) up to 7 for the most significant bit (leftmost). Negative values are used to refer to bit positions in the previous bytes, where -1 indicates the most significant bit (leftmost) of the byte immediately before the current one.

num_of_bits: usize

num_of_bits specifies the number of consecutive bits to be read or written starting from the bit_offset. This value is used to define the size of the data field in bits. For instance, if num_of_bits is set to 1, only a single bit is considered, whereas a value of 8 would indicate a full byte. This field must be a positive integer and typically should not exceed the size of the data type that will hold the extracted value (for example, 8 bits for a u8, 16 bits for a u16, etc.). The num_of_bits together with the bit_offset enables the extraction of bit fields of arbitrary length and position, facilitating bit-level data manipulation.

Implementations

impl HeaderMetadataSpec

fn assert_mask<T: MetadataValue>(&self, mask: Option<T>)

We only allow mask for u8/u16/u32/u64/usize. If a mask is used with a spec that does not allow it, this method will panic.

We allow using mask for certain operations. The reason for mask is that for header metadata, we may have overlapping metadata specs. For example, a forwarding pointer is pointer-size, but its last 2 bits could be used as forwarding bits. In that case, all accesses to the forwarding pointer spec should be used with a mask to make sure that we exclude the forwarding bits.

fn assert_spec<T: MetadataValue>(&self)

Assert if this is a valid spec.

fn byte_offset(&self) -> isize

fn meta_addr(&self, header: Address) -> Address

fn get_shift_and_mask_for_bits(&self) -> (isize, u8)

Get the bit shift (the bit distance from the lowest bit to the bits location defined in the spec), and the mask (used to extract value for the bits defined in the spec).

fn get_bits_from_u8(&self, raw_byte: u8) -> u8

Extract bits from a raw byte, and put it to the lowest bits.

fn set_bits_to_u8(&self, raw_byte: u8, set_val: u8) -> u8

Set bits to a raw byte. set_val has the valid value in its lowest bits.

fn truncate_bits_in_u8(&self, val: u8) -> u8

Truncate a value based on the spec.

pub unsafe fn load<T: MetadataValue>( &self, header: Address, optional_mask: Option<T>, ) -> T

This function provides a default implementation for the load_metadata method from the ObjectModel trait.

Safety

This is a non-atomic load, thus not thread-safe.

pub fn load_atomic<T: MetadataValue>( &self, header: Address, optional_mask: Option<T>, ordering: Ordering, ) -> T

This function provides a default implementation for the load_metadata_atomic method from the ObjectModel trait.

fn load_inner<T: MetadataValue>( &self, header: Address, optional_mask: Option<T>, atomic_ordering: Option<Ordering>, ) -> T

pub unsafe fn store<T: MetadataValue>( &self, header: Address, val: T, optional_mask: Option<T>, )

This function provides a default implementation for the store_metadata method from the ObjectModel trait.

Note: this function does compare-and-swap in a busy loop. So, unlike compare_exchange_metadata, this operation will always success.

Safety

This is a non-atomic store, thus not thread-safe.

pub fn store_atomic<T: MetadataValue>( &self, header: Address, val: T, optional_mask: Option<T>, ordering: Ordering, )

This function provides a default implementation for the store_metadata_atomic method from the ObjectModel trait.

Note: this function does compare-and-swap in a busy loop. So, unlike compare_exchange_metadata, this operation will always success.

fn store_inner<T: MetadataValue>( &self, header: Address, val: T, optional_mask: Option<T>, atomic_ordering: Option<Ordering>, )

pub fn compare_exchange<T: MetadataValue>( &self, header: Address, old_metadata: T, new_metadata: T, optional_mask: Option<T>, success_order: Ordering, failure_order: Ordering, ) -> Result<T, T>

This function provides a default implementation for the compare_exchange_metadata method from the ObjectModel trait.

Note: this function only does fetch and exclusive store once, without any busy waiting in a loop.

fn fetch_ops_on_bits<F: Fn(u8) -> u8>( &self, header: Address, set_order: Ordering, fetch_order: Ordering, update: F, ) -> u8

Inner method for fetch_add/sub on bits. For fetch_and/or, we don’t necessarily need this method. We could directly do fetch_and/or on the u8.

pub fn fetch_add<T: MetadataValue>( &self, header: Address, val: T, order: Ordering, ) -> T

This function provides a default implementation for the fetch_add method from the ObjectModel trait.

pub fn fetch_sub<T: MetadataValue>( &self, header: Address, val: T, order: Ordering, ) -> T

This function provides a default implementation for the fetch_sub method from the ObjectModel trait.

pub fn fetch_and<T: MetadataValue>( &self, header: Address, val: T, order: Ordering, ) -> T

This function provides a default implementation for the fetch_and method from the ObjectModel trait.

pub fn fetch_or<T: MetadataValue>( &self, header: Address, val: T, order: Ordering, ) -> T

This function provides a default implementation for the fetch_or method from the ObjectModel trait.

pub fn fetch_update<T: MetadataValue, F: FnMut(T) -> Option<T> + Copy>( &self, header: Address, set_order: Ordering, fetch_order: Ordering, f: F, ) -> Result<T, T>

This function provides a default implementation for the fetch_update method from the ObjectModel trait. The semantics is the same as Rust’s fetch_update on atomic types.

Trait Implementations

impl Clone for HeaderMetadataSpec

fn clone(&self) -> HeaderMetadataSpec

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for HeaderMetadataSpec

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

Formats the value using the given formatter.

impl Hash for HeaderMetadataSpec

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for HeaderMetadataSpec

fn eq(&self, other: &HeaderMetadataSpec) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl Copy for HeaderMetadataSpec

impl Eq for HeaderMetadataSpec

impl StructuralPartialEq for HeaderMetadataSpec