Struct scratchpad::Scratchpad

pub struct Scratchpad<BufferT, TrackingT> where
    BufferT: Buffer,
    TrackingT: Tracking,  { /* fields omitted */ }

Stack-like dynamic memory pool with double-ended allocation support.

Scratchpad manages dynamic allocations from a fixed-size region of memory in a stack-like manner. Allocations can be made simultaneously from either the "front" or "back" of the scratchpad by setting a Marker using either mark_front() (returning a MarkerFront) or mark_back() (returning a MarkerBack). Multiple markers can be set, but only the most-recently set marker of a given type that is still active can be used to allocate objects.

Individual allocations can be made from the marker, but no memory is actually freed back into the pool until the marker is dropped, where all the memory allocated through the marker is released at once. If the marker is not the most-recently set active marker of its type, its memory will simply be flagged as unused until all markers of the same type that were created after it are also dropped, at which point the memory will be once again made available for allocations.

Scratchpad, Marker implementations, and Allocation all make use of static lifetimes to ensure that an object cannot be used after the object from which it was created is dropped (an allocation cannot outlive its marker, and a marker cannot outlive its scratchpad).

See also the crate-level documentation for more detailed information about how Scratchpad works and can be used.

Methods

impl<BufferT, TrackingT> Scratchpad<BufferT, TrackingT> where
    BufferT: Buffer,
    TrackingT: Tracking, 

pub fn new(buffer: BufferT, tracking: TrackingT) -> Self

Creates a new scratchpad instance.

Examples

use scratchpad::Scratchpad;
use std::mem::uninitialized;

// Creates a scratchpad that can hold up to 256 bytes of data and up
// to 4 allocation markers. The initial contents of each buffer are
// ignored, so we can provide uninitialized data in order to reduce
// the runtime overhead of creating a scratchpad.
let scratchpad = unsafe { Scratchpad::new(
    uninitialized::<array_type_for_bytes!(u64, 256)>(),
    uninitialized::<array_type_for_markers!(usize, 4)>(),
) };

impl<BufferT, TrackingT> Scratchpad<BufferT, TrackingT> where
    BufferT: StaticBuffer,
    TrackingT: Tracking + StaticBuffer, 

pub fn static_new() -> Self

Creates a new instance for scratchpad types backed entirely by static arrays without initializing array memory.

Since static array Buffer and Tracking types are owned by the scratchpad, and their sizes are known ahead of time to the scratchpad type, scratchpads using only static arrays for storage can be created without having to provide any parameters.

Note that this cannot be const as there is no support in Rust for creating uninitialized values in const code. Scratchpad::new() must be used with the unstable crate feature enabled if const code is required.

Examples

use scratchpad::Scratchpad;

// Creates a scratchpad that can hold up to 256 bytes of data and up
// to 4 allocation markers.
let scratchpad = Scratchpad::<
    array_type_for_bytes!(u64, 256),
    array_type_for_markers!(usize, 4),
>::static_new();

impl<BufferT, TrackingT> Scratchpad<BufferT, TrackingT> where
    BufferT: Buffer,
    TrackingT: Tracking, 

pub fn mark_front<'scratchpad>(
    &'scratchpad self
) -> Result<MarkerFront<'scratchpad, BufferT, TrackingT>, Error>

Creates a marker at the front of the allocation buffer for subsequent allocations.

Examples

use scratchpad::Scratchpad;

let scratchpad = Scratchpad::<[u64; 1], [usize; 1]>::new([0], [0]);

let marker = scratchpad.mark_front().unwrap();
// `marker` can now be used for allocations...

pub fn mark_back<'scratchpad>(
    &'scratchpad self
) -> Result<MarkerBack<'scratchpad, BufferT, TrackingT>, Error>

Creates a marker at the back of the allocation buffer for subsequent allocations.

Examples

use scratchpad::Scratchpad;

let scratchpad = Scratchpad::<[u64; 1], [usize; 1]>::new([0], [0]);

let marker = scratchpad.mark_back().unwrap();
// `marker` can now be used for allocations...

Trait Implementations

impl<BufferT, TrackingT> Debug for Scratchpad<BufferT, TrackingT> where
    BufferT: Buffer,
    TrackingT: Tracking, 

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.