Trait Strict

pub trait Strict: Sealed {
    type Pointee;

    // Required methods
    fn addr(self) -> usize
       where Self::Pointee: Sized;
    fn expose_addr(self) -> usize
       where Self::Pointee: Sized;
    fn with_addr(self, addr: usize) -> Self
       where Self::Pointee: Sized;
    fn map_addr(self, f: impl FnOnce(usize) -> usize) -> Self
       where Self::Pointee: Sized;
}

Required Associated Types

type Pointee

Required Methods

fn addr(self) -> usize

where Self::Pointee: Sized,

Gets the “address” portion of the pointer.

This is similar to self as usize, which semantically discards provenance and address-space information. However, unlike self as usize, casting the returned address back to a pointer yields invalid, which is undefined behavior to dereference. To properly restore the lost information and obtain a dereferencable pointer, use with_addr or map_addr.

If using those APIs is not possible because there is no way to preserve a pointer with the required provenance, use expose_addr and from_exposed_addr instead. However, note that this makes your code less portable and less amenable to tools that check for compliance with the Rust memory model.

On most platforms this will produce a value with the same bytes as the original pointer, because all the bytes are dedicated to describing the address. Platforms which need to store additional information in the pointer may perform a change of representation to produce a value containing only the address portion of the pointer. What that means is up to the platform to define.

This API and its claimed semantics are part of the Strict Provenance experiment, and as such might change in the future (including possibly weakening this so it becomes wholly equivalent to self as usize). See the module documentation for details.

fn expose_addr(self) -> usize

where Self::Pointee: Sized,

Gets the “address” portion of the pointer, and ‘exposes’ the “provenance” part for future use in from_exposed_addr.

This is equivalent to self as usize, which semantically discards provenance and address-space information. Furthermore, this (like the as cast) has the implicit side-effect of marking the provenance as ‘exposed’, so on platforms that support it you can later call from_exposed_addr to reconstitute the original pointer including its provenance. (Reconstructing address space information, if required, is your responsibility.)

Using this method means that code is not following Strict Provenance rules. Supporting from_exposed_addr complicates specification and reasoning and may not be supported by tools that help you to stay conformant with the Rust memory model, so it is recommended to use addr wherever possible.

On most platforms this will produce a value with the same bytes as the original pointer, because all the bytes are dedicated to describing the address. Platforms which need to store additional information in the pointer may not support this operation, since the ‘expose’ side-effect which is required for from_exposed_addr to work is typically not available.

This API and its claimed semantics are part of the Strict Provenance experiment, see the module documentation for details.

fn with_addr(self, addr: usize) -> Self

where Self::Pointee: Sized,

Creates a new pointer with the given address.

This performs the same operation as an addr as ptr cast, but copies the address-space and provenance of self to the new pointer. This allows us to dynamically preserve and propagate this important information in a way that is otherwise impossible with a unary cast.

This is equivalent to using wrapping_offset to offset self to the given address, and therefore has all the same capabilities and restrictions.

This API and its claimed semantics are part of the Strict Provenance experiment, see the module documentation for details.

fn map_addr(self, f: impl FnOnce(usize) -> usize) -> Self

where Self::Pointee: Sized,

Creates a new pointer by mapping self’s address to a new one.

This is a convenience for with_addr, see that method for details.

This API and its claimed semantics are part of the Strict Provenance experiment, see the module documentation for details.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl<T> Strict for *const T

type Pointee = T

fn addr(self) -> usize

where T: Sized,

fn expose_addr(self) -> usize

where T: Sized,

fn with_addr(self, addr: usize) -> Self

where T: Sized,

fn map_addr(self, f: impl FnOnce(usize) -> usize) -> Self

where T: Sized,

impl<T> Strict for *mut T

type Pointee = T

fn addr(self) -> usize

where T: Sized,

fn expose_addr(self) -> usize

where T: Sized,

fn with_addr(self, addr: usize) -> Self

where T: Sized,

fn map_addr(self, f: impl FnOnce(usize) -> usize) -> Self

where T: Sized,

Implementors