Struct TagPtr

source

pub struct TagPtr<T, const N: usize> { /* private fields */ }

Expand description

A raw, unsafe pointer type like *mut T which can use up to N of its lower bits to store additional information (the tag).

This type has the same in-memory representation as a *mut T. See the crate level documentation for restrictions on the value of N.

Implementations§

source §

impl<T, const N: usize> TagPtr<T, N>

source

pub const TAG_BITS: usize = N

The number of available tag bits for this type.

source

pub const TAG_MASK: usize = _

The bitmask for the lower bits available for storing the tag value.

source

pub const POINTER_MASK: usize = _

The bitmask for the (higher) bits for storing the pointer itself.

source

pub const fn null() -> Self

Creates a new null pointer.

§Examples

use core::ptr;

type TagPtr = tagptr::TagPtr<i32, 2>;

let ptr = TagPtr::null();
assert_eq!(ptr.decompose(), (ptr::null_mut(), 0));

source

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

Creates a new unmarked pointer.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let reference = &mut 1;
let ptr = TagPtr::new(reference);
assert_eq!(ptr.decompose(), (reference as *mut _, 0));

source

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

Creates a new pointer from the numeric (integer) representation of a potentially marked pointer.

§Examples

use core::ptr;

type TagPtr = tagptr::TagPtr<i32, 2>;

let ptr = TagPtr::from_usize(0b11);
assert_eq!(ptr.decompose(), (ptr::null_mut(), 0b11));

source

pub const fn into_raw(self) -> *mut T

Returns the internal representation of the pointer as is, i.e. any potential tag value is not stripped.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let ptr = TagPtr::from_usize(0b11);
assert_eq!(ptr.into_raw(), 0b11 as *mut _);

source

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

Casts to a pointer of another type.

source

pub fn into_usize(self) -> usize

Returns the numeric (integer) representation of the pointer with its tag value.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let ptr = TagPtr::from_usize(0b11);
assert_eq!(ptr.into_usize(), 0b11);

source

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

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

The supplied ptr is assumed to be well-aligned (i.e. has no tag bits set) and calling this function may lead to unexpected results when this is not the case.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let raw = &1 as *const i32 as *mut i32;
let ptr = TagPtr::compose(raw, 0b11);
assert_eq!(ptr.decompose(), (raw, 0b11));
// excess bits are silently truncated
let ptr = TagPtr::compose(raw, 0b101);
assert_eq!(ptr.decompose(), (raw, 0b01));

source

pub fn is_null(self) -> bool

Returns true if the marked pointer is null.

§Examples

use core::ptr;

type TagPtr = tagptr::TagPtr<i32, 2>;

let ptr = TagPtr::compose(ptr::null_mut(), 0b11);
assert!(ptr.is_null());

source

pub fn clear_tag(self) -> Self

Clears the marked pointer’s tag value.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let reference = &mut 1;
let ptr = TagPtr::compose(reference, 0b11);

assert_eq!(ptr.clear_tag().decompose(), (reference as *mut _, 0));

source

pub fn split_tag(self) -> (Self, usize)

Splits the tag value from the marked pointer, returning both the cleared pointer and the separated tag value.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let reference = &mut 1;
let ptr = TagPtr::compose(reference, 0b11);

assert_eq!(ptr.split_tag(), (TagPtr::new(reference), 0b11));

source

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

Sets the marked pointer’s tag value to tag and overwrites any previous value.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let reference = &mut 1;
let ptr = TagPtr::compose(reference, 0b11);

assert_eq!(ptr.set_tag(0b01).decompose(), (reference as *mut _, 0b01));

source

pub fn update_tag(self, func: impl FnOnce(usize) -> usize) -> Self

Updates the marked pointer’s tag value to the result of func, which is called with the current tag value.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let reference = &mut 1;
let ptr = TagPtr::compose(reference, 0b11);

assert_eq!(ptr.update_tag(|tag| tag - 1).decompose(), (reference as *mut _, 0b10));

source

pub fn add_tag(self, value: usize) -> Self

Adds value to the current tag without regard for the previous value.

This method does not perform any checks so it may silently overflow the tag bits, result in a pointer to a different value, a null pointer or an unaligned pointer.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let reference = &mut 1;
let ptr = TagPtr::compose(reference, 0b10);

assert_eq!(ptr.add_tag(1).decompose(), (reference as *mut _, 0b11));

source

pub fn sub_tag(self, value: usize) -> Self

Subtracts value from the current tag without regard for the previous value.

This method does not perform any checks so it may silently overflow the tag bits, result in a pointer to a different value, a null pointer or an unaligned pointer.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let reference = &mut 1;
let ptr = TagPtr::compose(reference, 0b10);

assert_eq!(ptr.sub_tag(1).decompose(), (reference as *mut _, 0b01));

source

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

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

source

pub fn decompose_ptr(self) -> *mut T

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

source

pub fn decompose_tag(self) -> usize

Decomposes the marked pointer, returning only the separated tag value.

source

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

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

§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.

When calling this method, you have to ensure that either the pointer is null or all of the following is true:

it is properly aligned
it must point to an initialized instance of T; in particular, the pointer must be “de-referencable” in the sense defined here.

This applies even if the result of this method is unused! (The part about being initialized is not yet fully decided, but until it is the only safe approach is to ensure that they are indeed initialized.)

Additionally, the lifetime 'a returned is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. You must enforce Rust’s aliasing rules. In particular, for the duration of this lifetime, the memory this pointer points to must not get accessed (read or written) through any other pointer.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let reference = &1;
let ptr = TagPtr::compose(reference as *const _ as *mut _, 0b11);

unsafe {
    assert_eq!(ptr.as_ref(), Some(&1));
}

source

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

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

§Safety

As with as_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.

When calling this method, you have to ensure that either the pointer is null or all of the following is true:

it is properly aligned
it must point to an initialized instance of T; in particular, the pointer must be “de-referencable” in the sense defined here.

This applies even if the result of this method is unused! (The part about being initialized is not yet fully decided, but until it is the only safe approach is to ensure that they are indeed initialized.)

Additionally, the lifetime 'a returned is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. You must enforce Rust’s aliasing rules. In particular, for the duration of this lifetime, the memory this pointer points to must not get accessed (read or written) through any other pointer.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let mut val = 1;
let ptr = TagPtr::compose(&mut val, 0b11);

unsafe {
    assert_eq!(ptr.as_mut(), Some(&mut 1));
}

source

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

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

§Safety

The same safety caveats as with as_ref apply.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let reference = &1;
let ptr = TagPtr::compose(reference as *const _ as *mut _, 0b11);

unsafe {
    assert_eq!(ptr.decompose_ref(), (Some(&1), 0b11));
}

source

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.

§Safety

The same safety caveats as with as_mut apply.

§Examples

type TagPtr = tagptr::TagPtr<i32, 2>;

let mut val = 1;
let ptr = TagPtr::compose(&mut val, 0b11);

unsafe {
    assert_eq!(ptr.decompose_mut(), (Some(&mut 1), 0b11));
}