Trait NonNullPtr

pub unsafe trait NonNullPtr: 'static {
    type Target;
    type Ref<'a>
       where Self: 'a;

    const ALIGN_BITS: u32;

    // Required methods
    fn into_raw(self) -> NonNull<Self::Target>;
    unsafe fn from_raw(ptr: NonNull<Self::Target>) -> Self;
    unsafe fn raw_as_ref<'a>(raw: NonNull<Self::Target>) -> Self::Ref<'a>;
    fn ref_as_raw(ptr_ref: Self::Ref<'_>) -> NonNull<Self::Target>;
}

A trait that abstracts non-null pointers.

All common smart pointer types such as Box<T>, Arc<T>, and Weak<T> implement this trait as they can be converted to and from the raw pointer type of *const T.

Safety

This trait must be implemented correctly (according to the doc comments for each method). Types like Rcu rely on this assumption to safely use the raw pointers.

Required Associated Constants

const ALIGN_BITS: u32

The power of two of the pointer alignment.

Required Associated Types

type Target

The target type that this pointer refers to.

type Ref<'a> where Self: 'a

A type that behaves just like a shared reference to the NonNullPtr.

Required Methods

fn into_raw(self) -> NonNull<Self::Target>

Converts to a raw pointer.

Each call to into_raw must be paired with a call to from_raw in order to avoid memory leakage.

The lower Self::ALIGN_BITS of the raw pointer is guaranteed to be zero. In other words, the pointer is guaranteed to be aligned to 1 << Self::ALIGN_BITS.

unsafe fn from_raw(ptr: NonNull<Self::Target>) -> Self

Converts back from a raw pointer.

Safety

1. The raw pointer must have been previously returned by a call to into_raw.
2. The raw pointer must not be used after calling from_raw.

Note that the second point is a hard requirement: Even if the resulting value has not (yet) been dropped, the pointer cannot be used because it may break Rust aliasing rules (e.g., Box<T> requires the pointer to be unique and thus never aliased).

unsafe fn raw_as_ref<'a>(raw: NonNull<Self::Target>) -> Self::Ref<'a>

Obtains a shared reference to the original pointer.

Safety

The original pointer must outlive the lifetime parameter 'a, and during 'a no mutable references to the pointer will exist.

fn ref_as_raw(ptr_ref: Self::Ref<'_>) -> NonNull<Self::Target>

Converts a shared reference to a raw pointer.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T: 'static> NonNullPtr for Weak<T>

const ALIGN_BITS: u32 = 0u32

type Target = T

type Ref<'a> = WeakRef<'a, T> where Self: 'a

fn into_raw(self) -> NonNull<Self::Target>

unsafe fn from_raw(ptr: NonNull<Self::Target>) -> Self

unsafe fn raw_as_ref<'a>(raw: NonNull<Self::Target>) -> Self::Ref<'a>

fn ref_as_raw(ptr_ref: Self::Ref<'_>) -> NonNull<Self::Target>

Implementors

impl<L: NonNullPtr, R: NonNullPtr> NonNullPtr for Either<L, R>

const ALIGN_BITS: u32

type Target = PhantomData<Either<L, R>>

type Ref<'a> = Either<<L as NonNullPtr>::Ref<'a>, <R as NonNullPtr>::Ref<'a>> where Self: 'a

impl<M: AnyFrameMeta + ?Sized> NonNullPtr for Frame<M>

const ALIGN_BITS: u32 = 3u32

type Target = PhantomData<Frame<M>>

type Ref<'a> = FrameRef<'a, M> where Self: 'a

impl<T: 'static> NonNullPtr for Arc<T>

const ALIGN_BITS: u32

type Target = T

type Ref<'a> = ArcRef<'a, T> where Self: 'a

impl<T: 'static> NonNullPtr for Box<T>

const ALIGN_BITS: u32

type Target = T

type Ref<'a> = BoxRef<'a, T> where Self: 'a