rok::bare::ptr

Ptr

pub struct Ptr<T>

A non-null, mutable pointer to one T (C T*).

• pub const fn dangling() -> Ptr<T>

  Well aligned, never dereferenceable.

• pub fn null() -> Ptr<T> | none

  Always none (a Ptr is never null).

• pub const fn addr(self) -> usize

  The address (provenance is lost).

• pub const fn with_addr(self, addr: usize) -> Ptr<T>

• pub const fn map_addr(self, f: fn(usize) -> usize) -> Ptr<T>

• pub fn offset(self, count: isize) -> Ptr<T>

  count elements further (count * size_of::<T>() bytes).

• pub const fn add(self, count: usize) -> Ptr<T>

• pub const fn sub(self, count: usize) -> Ptr<T>

• pub fn byte_offset(self, count: isize) -> Ptr<T>

  count bytes further.

• pub const fn distance(self, origin: Ptr<T>) -> isize

  self.addr() - origin.addr() in elements.

• pub const fn is_aligned(self) -> bool

• pub const fn align_offset(self, align: usize) -> usize

  Elements to add so the address is a multiple of align, or usize::MAX when no element count gets there.

• pub const fn cast<U>(self) -> Ptr<U>

  The same address as a pointer to U (alignment is the caller's).

• pub const fn as_const(self) -> ConstPtr<T>

• pub const fn as_many(self) -> ManyPtr<T>

• pub unsafe fn read(self) -> T

  The T it points at. UB unless it points at a live, initialized T.

• pub unsafe fn write(self, value: T)

  Store value where it points. UB unless that is writable T memory.

• pub unsafe fn read_volatile(self) -> T

• pub unsafe fn write_volatile(self, value: T)

ConstPtr

pub struct ConstPtr<T>

A non-null pointer to one T that is only read (C const T*).

• pub const fn dangling() -> ConstPtr<T>

• pub const fn addr(self) -> usize

• pub const fn with_addr(self, addr: usize) -> ConstPtr<T>

• pub fn offset(self, count: isize) -> ConstPtr<T>

• pub const fn add(self, count: usize) -> ConstPtr<T>

• pub fn sub(self, count: usize) -> ConstPtr<T>

• pub fn cast<U>(self) -> ConstPtr<U>

• pub fn as_many(self) -> ManyPtr<T>

• pub unsafe fn read(self) -> T

• pub unsafe fn read_volatile(self) -> T

ManyPtr

pub struct ManyPtr<T>

A pointer to a run of Ts of unknown length (C T* array).

• pub const fn addr(self) -> usize

• pub fn with_addr(self, addr: usize) -> ManyPtr<T>

• pub fn offset(self, count: isize) -> ManyPtr<T>

• pub fn add(self, count: usize) -> ManyPtr<T>

• pub const fn as_one(self) -> Ptr<T>

  The first element as a single-element pointer.

• pub fn as_const(self) -> ConstPtr<T>

• pub unsafe fn read(self, idx: usize) -> T

  Element idx (no bounds: the caller knows the length).

• pub unsafe fn write(self, idx: usize, value: T)

• pub unsafe fn slice(self, len: usize) -> Slice<T>

  The len Ts from here as a Slice<T>; they must stay valid while the view is used, and the GC neither traces nor moves them (elements holding GC references are UB here).

CPtr

pub struct CPtr<T>

A C-compatible nullable pointer (T* that may be NULL).

• pub const fn null() -> CPtr<T>

• pub fn from_ptr(p: Ptr<T>) -> CPtr<T>

• pub const fn from_const(p: ConstPtr<T>) -> CPtr<T>

• pub const fn from_addr(addr: usize) -> CPtr<T>

• pub const fn is_null(self) -> bool

• pub const fn addr(self) -> usize

• pub const fn as_ptr(self) -> Ptr<T> | none

  none when null.

• pub fn as_const(self) -> ConstPtr<T> | none

size_of

pub fn size_of<T>() -> usize

Size of T in bytes (also rok::bare::mem::size_of).

align_of

pub fn align_of<T>() -> usize

Alignment of T in bytes.

ptr_cast

pub const fn ptr_cast<U

The same address as a pointer to U (spec 1.2.2: ptr_cast::<U>(p); alignment is the caller's problem).

align_cast

pub const fn align_cast<T>(p: Ptr<u8>) -> Ptr<T> | none

p as a Ptr<T> when its address suits T's alignment (1.2.3).

align_cast_unchecked

pub const fn align_cast_unchecked<T>(p: Ptr<u8>) -> Ptr<T>

p as a Ptr<T> with no alignment check, not even in debug builds (1.2.3).

const_cast

pub const fn const_cast<T>(p: ConstPtr<T>) -> Ptr<T>

Drop the const (1.2.4): writing through the result is the caller's responsibility.

expose_provenance

pub const fn expose_provenance<T>(p: Ptr<T>) -> usize

The address of p, marked as escaping (1.1.2 strict provenance).

addr_of

pub fn addr_of<T>(place: T) -> Ptr<T>

A pointer to place itself (a local, or a field / array element of one), valid while that local is in scope: the local lives in memory and, holding GC references, stays a GC root (whose referents never move) until its scope ends.

many_addr_of

pub fn many_addr_of<T>(place: T) -> ManyPtr<T>

addr_of as the start of a run of Ts (many_addr_of(buf[0])).

unsafe

pub const unsafe fn from_exposed_provenance<T>(addr: usize) -> Ptr<T>

A pointer at addr, assumed to carry an exposed provenance.