Struct tagptr::TagPtr[−][src]

#[repr(transparent)]
pub struct TagPtr<T, const N: usize> { /* fields omitted */ }
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

The number of available tag bits for this type.

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

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

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));

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));

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));

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 _);

Casts to a pointer of another type.

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);

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));

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());

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));

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));

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));

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));

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));

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));

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

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

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

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));
}

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));
}

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));
}

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));
}

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

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

This method tests for !=.

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

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

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

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

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

Formats the value using the given formatter.

The type returned in the event of a conversion error.

Performs the conversion.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.