Struct reclaim::MarkedPtr

pub struct MarkedPtr<T, N> { /* fields omitted */ }

A raw, unsafe pointer type like *mut T in which up to N of the pointer's lower bits can be used to store additional information (the tag).

Note, that the upper bound for N is dictated by the alignment of T. A type with an alignment of 8 (e.g. a usize on 64-bit architectures) can have up to 3 mark bits. Attempts to use types with insufficient alignment will result in a compile- time error.

Methods

impl<T, N> MarkedPtr<T, N>

pub const fn new(ptr: *mut T) -> Self

Creates an unmarked pointer.

pub const fn null() -> Self

Creates a new & unmarked null pointer.

pub const fn cast<U>(self) -> MarkedPtr<U, N>

Cast to a pointer of another type.

pub const fn from_usize(val: usize) -> Self

Creates a marked pointer from the numeric representation of a potentially marked pointer.

impl<T, N: Unsigned> MarkedPtr<T, N>

pub const MARK_BITS: usize

The number of available mark bits for this type.

pub const MARK_MASK: usize

The bitmask for the lower markable bits.

pub const POINTER_MASK: usize

The bitmask for the higher pointer bits.

pub fn into_usize(self) -> usize

Returns the numeric representation of the pointer with its tag.

pub fn into_ptr(self) -> *mut T

Returns the inner pointer as is, meaning potential tags are not stripped.

pub fn compose(ptr: *mut T, tag: usize) -> Self

Composes a new marked pointer from a raw unmarked pointer and a tag value.

pub fn convert<M: Unsigned>(other: MarkedPtr<T, M>) -> Self where
    N: IsGreaterOrEqual<M, Output = True>, 

Converts a marked pointer with M potential mark bits to the same marked pointer with N potential mark bits, requires that N >= M.

pub fn clear_tag(self) -> Self

Clears the tag of self and returns the same but untagged pointer.

pub fn with_tag(self, tag: usize) -> Self

Clears the tag of self and replaces it with tag.

pub fn decompose(self) -> (*mut T, usize)

Decomposes the marked pointer, returning the separated raw pointer and its tag.

pub fn decompose_ptr(self) -> *mut T

Decomposes the marked pointer, returning only the separated raw pointer.

pub fn decompose_tag(self) -> usize

Decomposes the marked pointer, returning only the separated tag.

pub unsafe fn decompose_ref<'a>(self) -> (Option<&'a T>, usize)

Decomposes the marked pointer, returning an optional reference and the separated tag.

In case the pointer stripped of its tag is null, None is returned as part of the tuple. Otherwise, the reference is wrapped in a Some.

Safety

While this method and its mutable counterpart are useful for null-safety, it is important to note that this is still an unsafe operation because the returned value could be pointing to invalid memory.

Additionally, the lifetime 'a returned is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.

pub unsafe fn decompose_mut<'a>(self) -> (Option<&'a mut T>, usize)

Decomposes the marked pointer returning an optional mutable reference and the separated tag.

In case the pointer stripped of its tag is null, None is returned as part of the tuple. Otherwise, the mutable reference is wrapped in a Some.

Safety

As with decompose_ref, this is unsafe because it cannot verify the validity of the returned pointer, nor can it ensure that the lifetime 'a returned is indeed a valid lifetime for the contained data.

pub unsafe fn as_ref<'a>(self) -> Option<&'a T>

Decomposes the marked pointer, returning an optional reference and discarding the tag.

Safety

The same caveats as with decompose_ref apply for this method as well.

pub unsafe fn as_mut<'a>(self) -> Option<&'a mut T>

Decomposes the marked pointer, returning an optional mutable reference and discarding the tag.

Safety

The same caveats as with decompose_mut apply for this method as well.

pub fn is_null(self) -> bool

Returns true if the pointer is null (regardless of the tag).

Trait Implementations

impl<T, N: Unsigned> From<MarkedPtr<T, N>> for AtomicMarkedPtr<T, N>

fn from(ptr: MarkedPtr<T, N>) -> Self

Performs the conversion.

impl<T, N: Unsigned> From<*const T> for MarkedPtr<T, N>

fn from(ptr: *const T) -> Self

Performs the conversion.

impl<T, N: Unsigned> From<*mut T> for MarkedPtr<T, N>

fn from(ptr: *mut T) -> Self

Performs the conversion.

impl<'a, T, N: Unsigned> From<&'a T> for MarkedPtr<T, N>

fn from(reference: &'a T) -> Self

Performs the conversion.

impl<'a, T, N: Unsigned> From<&'a mut T> for MarkedPtr<T, N>

fn from(reference: &'a mut T) -> Self

Performs the conversion.

impl<T, N: Unsigned> From<NonNull<T>> for MarkedPtr<T, N>

fn from(ptr: NonNull<T>) -> Self

Performs the conversion.

impl<T, N: Unsigned> From<(*mut T, usize)> for MarkedPtr<T, N>

fn from(pair: (*mut T, usize)) -> Self

Performs the conversion.

impl<T, N: Unsigned> From<(*const T, usize)> for MarkedPtr<T, N>

fn from(pair: (*const T, usize)) -> Self

Performs the conversion.

impl<T, N> PartialEq<MarkedPtr<T, N>> for MarkedNonNull<T, N>

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

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, N> PartialEq<MarkedPtr<T, N>> for MarkedPtr<T, N>

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

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, N> PartialEq<MarkedNonNull<T, N>> for MarkedPtr<T, N>

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

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, N> Clone for MarkedPtr<T, N>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, N: Unsigned> Default for MarkedPtr<T, N>

fn default() -> Self

Returns the "default value" for a type.

impl<T, N> PartialOrd<MarkedPtr<T, N>> for MarkedNonNull<T, N>

fn partial_cmp(&self, other: &MarkedPtr<T, N>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, N> PartialOrd<MarkedPtr<T, N>> for MarkedPtr<T, N>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, N> PartialOrd<MarkedNonNull<T, N>> for MarkedPtr<T, N>

fn partial_cmp(&self, other: &MarkedNonNull<T, N>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, N> Copy for MarkedPtr<T, N>

impl<T, N: Unsigned> Debug for MarkedPtr<T, N>

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

Formats the value using the given formatter.

impl<T, N: Unsigned> TryFrom<MarkedPtr<T, N>> for MarkedNonNull<T, N>

type Error = InvalidNullError

The type returned in the event of a conversion error.

fn try_from(ptr: MarkedPtr<T, N>) -> Result<Self, Self::Error>

Performs the conversion.

impl<T, N: Unsigned> Pointer for MarkedPtr<T, N>

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

Formats the value using the given formatter.