Struct pages::PageRef

#[repr(transparent)]
pub struct PageRef<H, T> { /* fields omitted */ }

A mutable pointer to a dynamically-sized heap-backed data page comprising a user-chosen header and data array packed into a single allocation. The internal representation is a NonNull.

Example

use pages::Page;
use core::mem::MaybeUninit;
// A really crappy replacement for Box<Option<usize>>
struct Maybe(Page::<bool, usize>);
impl Maybe {
    fn new() -> Self { Maybe(Page::new(false, 1)) }
    fn put(&mut self, value: usize) {
        *self.0.header_mut() = true; // occupied
        unsafe { self.0.data().write(MaybeUninit::new(value)) };
    }
    fn get(&mut self) -> Option<usize> {
        if !(*self.0.header()) { return None; }
        *self.0.header_mut() = false; // free
        Some(unsafe { self.0.data().read().assume_init() })
    }
}

let mut maybe = Maybe::new();
assert_eq!(maybe.get(), None);
maybe.put(42);
assert_eq!(maybe.get(), Some(42));

Notes

Data is exposed as a MaybeUninit pointer for maximum flexibility. Unfortunately this means we’re unable to automatically drop the data for you in our destructor. You could cause a memory leak if you don’t.

Implementations

impl<H, T> PageRef<H, T>

pub fn new(header: H, items: u32) -> Self

Creates a new PageRef on the heap with the provided header and capacity for items items.

Notes

Will panic if items is 0 or the header plus padding is extremely large (u32::MAX - 8 bytes)

pub unsafe fn capacity(self) -> u32

The capacity of this page’s data array.

Safety

You must synchronise all reads and writes.

pub unsafe fn header(&self) -> &H

Access to this page’s header by reference.

Safety

You must synchronise all reads and writes.

pub unsafe fn header_mut(&mut self) -> &mut H

Access to this page’s header by mut reference.

Safety

You must synchronise all reads and writes.

pub unsafe fn data(self) -> *mut MaybeUninit<T>

Access to the start of the data array for this page as a mut pointer.

Safety

You must synchronise all reads and writes.

pub unsafe fn layout(self) -> PageLayout<H, T>

Returns this page’s layout information as a PageLayout.

Safety

You must synchronise all reads and writes.

pub unsafe fn drop(page: Self)

Drops the page pointed to by the provided PageRef

Safety

You must no longer access this page via other PageRefs.

pub unsafe fn from_uninit(
    raw_ptr: *mut u8,
    header: H,
    layout: PageLayout<H, T>
) -> Self

Creates a new PageRef from a pointer to uninitialised memory, a header and a PageLayout.

Safety

The pointer must have been allocated according to the provided PageLayout.

Trait Implementations

impl<H, T> Clone for PageRef<H, T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<H, T> Debug for PageRef<H, T>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<H, T> PartialEq<PageRef<H, T>> for PageRef<H, T>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<H, T> Copy for PageRef<H, T>

impl<H, T> Eq for PageRef<H, T>