Struct pages::Page

#[repr(transparent)]
pub struct Page<H, T>(_);

An owned, heap-backed, dynamically-sized data page comprising a user-chosen header and data array packed into a single allocation. It is an owned object and 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> Page<H, T>

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

Creates a new Page 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 fn capacity(&self) -> u32

The capacity of this page’s data array.

pub fn header(&self) -> &H

Access to this page’s header by reference.

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

Access to this page’s header by mut reference.

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

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

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

Returns the PageLayout describing the memory layout of this Page

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

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

Safety

You must ensure:

• The pointer was allocated according to the provided PageLayout.
  • Synchronise all reads and writes to
  • Suppress the destructor of all but one of them (e.g. by wrapping in [ManuallyDrop]).
• If the pointer did not originate from the global allocator, you must suppress the destructor (e.g. by wrapping in [ManuallyDrop]).

pub unsafe fn from_ref(page_ref: PageRef<H, T>) -> Self

Creates an owned Page from a PageRef.

Example

use pages::Page;
let page = Page::<bool, usize>::new(false, 1);
let page_ref = page.to_ref();
let page = unsafe { Page::<bool, usize>::from_ref(page_ref) };

Safety

You must only have one live Page per page.

pub fn to_ref(self) -> PageRef<H, T>

Converts this Page to a PageRef, a mutable pointer structure, effectively leaking it.

Trait Implementations

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

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

Formats the value using the given formatter.

impl<H, T> Drop for Page<H, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<H: Send, T: Send> Send for Page<H, T>

impl<H: Sync, T: Sync> Sync for Page<H, T>