Struct User

Source

pub struct User<'a, T> {
    ptr: T,
    address_space: Option<&'a AddressSpace>,
}

Available on crate feature full only.

Expand description

A pointer to a potentially invalid address, tied to a specific address space

While the pointer may safely point to an invalid or unaligned address, in the case that it points to a valid address and is read from, then it is unsound for the address to not hold a valid bit-pattern for the type T.

For example, it is always sound to create a User<*const u8> regardless of the address it points to, and always safe to call read() on it, but it would be unsound to create a User<*const bool>if it’s not guaranteed that the pointed value is either 1 or 0.

Additionally, to make the API require less unsafe for common cases, User<*mut T> is always safe to construct, with the additional requirement that it becomes write-only.

Fields§

§ptr: T§address_space: Option<&'a AddressSpace>

Implementations§

Source §

impl<'a, T: ?Sized> User<'a, *const T>

Source

pub(crate) unsafe fn new(ptr: *const T, address_space: &'a AddressSpace) -> Self
where T: Sized,

Creates a new User<*const T> with the provided address tied to the provided address space

§Safety

addr, if valid, must point to a valid bit pattern for T in the current address space. This means that in almost all cases, it is unsound to create a User<*const T> where T has a niche.

For all types with no invalid bit-patterns (i.e. all numeric types) it is sound to create a User<*const T>.

Source

pub const fn is_null(&self) -> bool

Returns true if the pointer has either a null address or address space

Source

pub const unsafe fn offset(self, count: isize) -> Self
where T: Sized,

Adds a signed offset to a pointer.

count is in units of T; e.g., a count of 3 represents a pointer offset of 3 * size_of::<T>() bytes.

§Safety

See safety requirements for [<*const T>::offset()]

Source

pub const unsafe fn byte_offset(self, count: isize) -> Self

Adds a signed offset in bytes to a pointer.

§Safety

See safety requirements for [<*const T>::byte_offset()]

Source

pub const unsafe fn add(self, count: usize) -> Self
where T: Sized,

Adds an offset to a pointer.

count is in units of T; e.g., a count of 3 represents a pointer offset of 3 * size_of::<T>() bytes.

§Safety

See safety requirements for [<*const T>::add()]

Source

pub const unsafe fn byte_add(self, count: usize) -> Self

Adds an offset in bytes to a pointer.

§Safety

See safety requirements for [<*const T>::byte_add()]

Source

pub const unsafe fn sub(self, count: usize) -> Self
where T: Sized,

Subtracts an offset from a pointer.

count is in units of T; e.g., a count of 3 represents a pointer offset of 3 * size_of::<T>() bytes.

§Safety

See safety requirements for [<*const T>::sub()]

Source

pub const unsafe fn byte_sub(self, count: usize) -> Self

Subtracts an offset in bytes from a pointer.

§Safety

See safety requirements for [<*const T>::byte_sub()]

Source

pub fn read_other_address_space(self) -> Result<T, PointerError>
where T: Sized + Copy,

Source

pub const unsafe fn cast(self) -> User<'a, *const U>

Casts a pointer to another type

§Safety

If self has a valid address, then it must point to a valid bit pattern for U in the current address space. This means that in almost all cases, it is unsound to cast to a User<*const U> where U has a niche.

For all types with no invalid bit-patterns (i.e. all numeric types) it is sound to cast to a User<*const U>.

Source

pub const fn cast_mut(self) -> User<'a, *mut T>

Casts to a writable pointer

Source

pub(crate) fn new(ptr: *mut T, address_space: &'a AddressSpace) -> Self
where T: Sized,

Creates a new User<*mut T> with the provided address tied to the provided address space

Source

pub const fn is_null(&self) -> bool

Returns true if the pointer has either a null address or address space

Source

pub const unsafe fn offset(self, count: isize) -> Self
where T: Sized,

Adds a signed offset to a pointer.

count is in units of T; e.g., a count of 3 represents a pointer offset of 3 * size_of::<T>() bytes.

§Safety

See safety requirements for [<*mut T>::offset()]

Source

pub const unsafe fn byte_offset(self, count: isize) -> Self

Adds a signed offset in bytes to a pointer.

§Safety

See safety requirements for [<*mut T>::byte_offset()]

Source

pub const unsafe fn add(self, count: usize) -> Self
where T: Sized,

Adds an offset to a pointer.

count is in units of T; e.g., a count of 3 represents a pointer offset of 3 * size_of::<T>() bytes.

§Safety

See safety requirements for [<*mut T>::add()]

Source

pub const unsafe fn byte_add(self, count: usize) -> Self

Adds an offset in bytes to a pointer.

§Safety

See safety requirements for [<*mut T>::byte_add()]

Source

pub const unsafe fn sub(self, count: usize) -> Self
where T: Sized,

Subtracts an offset from a pointer.

count is in units of T; e.g., a count of 3 represents a pointer offset of 3 * size_of::<T>() bytes.

§Safety

See safety requirements for [<*mut T>::sub()]

Source

pub const unsafe fn byte_sub(self, count: usize) -> Self

Subtracts an offset in bytes from a pointer.

§Safety

See safety requirements for [<*mut T>::byte_sub()]

Source

pub fn write_other_address_space(self, value: T) -> Result<(), PointerError>
where T: Sized,

Source

pub unsafe fn copy_from_other_address_space( self, start: *const T, count: usize, ) -> Result<(), PointerError>
where T: Sized,

Source

pub const fn cast(self) -> User<'a, *mut U>

Casts a pointer to another type

Source

pub const unsafe fn cast_const(self) -> User<'a, *const T>

Casts to a readable pointer

§Safety

addr, if valid, must point to a valid bit pattern for T in the current address space. This means that in almost all cases, it is unsound to cast to a User<*const T> where T has a niche.

For all types with no invalid bit-patterns (i.e. all numeric types) it is sound to cast to a User<*const T>.

Source