Struct stabby::alloc::AllocPtr

source ·

#[repr(C)]pub struct AllocPtr<T, Alloc> {
    pub ptr: NonNull<T>,
    pub marker: PhantomData<Alloc>,
}

Expand description

A non-null pointer guaranteed to be preceded by a valid AllocPrefix unless the pointer is dangling.

This means that unless T is a ZST, the pointer is guaranteed to be aligned to the maximum of T’s alignment and the alignment of the prefix, which itself is ptr-size aligned.

Fields§

§ptr: NonNull<T>

The pointer to the data.

§marker: PhantomData<Alloc>

Remember the allocator’s type.

Implementations§

source §

impl<T, Alloc> AllocPtr<T, Alloc>

source

pub const fn has_optimal_layout() -> bool

Returns true if the layout for AllocPtr is smaller or equal to that Rust would have generated for it.

source §

impl<T, Alloc> AllocPtr<T, Alloc>

source

pub const fn dangling() -> AllocPtr<T, Alloc>

Constructs a dangling pointer.

source

pub const fn cast(self) -> AllocPtr<U, Alloc>

Casts an allocated pointer.

source

pub const fn prefix_skip() -> usize

The offset between self.ptr and the prefix.

source

pub const unsafe fn prefix(&self) -> &AllocPrefix<Alloc>

A reference to the prefix for this allocation.

§Safety

self must not be dangling, and have been properly allocated, using Self::alloc or Self::realloc for example.

source

pub unsafe fn prefix_mut(&mut self) -> &mut AllocPrefix<Alloc>

A mutable reference to the prefix for this allocation.

§Safety

self must not be dangling, and have been properly allocated, using Self::alloc or Self::realloc for example. Since this type is Copy, the &mut self is not a sufficient guarantee of uniqueness.

source §

impl<T, Alloc> AllocPtr<T, Alloc>
where Alloc: IAlloc,

source

pub fn alloc(alloc: &mut Alloc) -> Option<AllocPtr<T, Alloc>>

Allocates a pointer to a single element of T, prefixed by an AllocPrefix

source

pub fn alloc_array( alloc: &mut Alloc, capacity: usize ) -> Option<AllocPtr<T, Alloc>>

Allocates a pointer to an array of capacity T, prefixed by an AllocPrefix

source

pub unsafe fn realloc( self, alloc: &mut Alloc, capacity: usize ) -> Option<AllocPtr<T, Alloc>>

Reallocates a pointer to an array of capacity T, prefixed by an AllocPrefix.

In case of failure of the allocator, this will return None and self will not have been freed.

§Safety

self must not be dangling

source

pub unsafe fn free(self, alloc: &mut Alloc)

Reallocates a pointer to an array of capacity T, prefixed by an AllocPrefix

§Safety

self must not be dangling, and is freed after this returns.

Methods from Deref<Target = NonNull<T>>§

1.25.0 · source

pub unsafe fn as_ref<'a>(&self) -> &'a T

Returns a shared reference to the value. If the value may be uninitialized, as_uninit_ref must be used instead.

For the mutable counterpart see as_mut.

§Safety

When calling this method, you have to ensure that all of the following is true:

The pointer must be properly aligned.
It must be “dereferenceable” in the sense defined in the module documentation.
The pointer must point to an initialized instance of T.
You must enforce Rust’s aliasing rules, since the returned lifetime 'a is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. In particular, while this reference exists, the memory the pointer points to must not get mutated (except inside UnsafeCell).

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

§Examples

use std::ptr::NonNull;

let mut x = 0u32;
let ptr = NonNull::new(&mut x as *mut _).expect("ptr is null!");

let ref_x = unsafe { ptr.as_ref() };
println!("{ref_x}");

1.25.0 · source

pub unsafe fn as_mut<'a>(&mut self) -> &'a mut T

Returns a unique reference to the value. If the value may be uninitialized, as_uninit_mut must be used instead.

For the shared counterpart see as_ref.

§Safety

When calling this method, you have to ensure that all of the following is true:

The pointer must be properly aligned.
It must be “dereferenceable” in the sense defined in the module documentation.
The pointer must point to an initialized instance of T.
You must enforce Rust’s aliasing rules, since the returned lifetime 'a is arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. In particular, while this reference exists, the memory the pointer points to must not get accessed (read or written) through any other pointer.

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

§Examples

use std::ptr::NonNull;

let mut x = 0u32;
let mut ptr = NonNull::new(&mut x).expect("null pointer");

let x_ref = unsafe { ptr.as_mut() };
assert_eq!(*x_ref, 0);
*x_ref += 2;
assert_eq!(*x_ref, 2);