Struct scratchpad::Scratchpad [−][src]
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,
[src]
impl<BufferT, TrackingT> Scratchpad<BufferT, TrackingT> where
BufferT: Buffer,
TrackingT: Tracking,
pub fn new(buffer: BufferT, tracking: TrackingT) -> Self
[src]
pub fn new(buffer: BufferT, tracking: TrackingT) -> Self
Creates a new scratchpad instance.
Note that using large static arrays for allocation storage or marker
tracking can cause the program to run out of stack space while calling
this function. It is recommended to either use borrowed slices or
boxed slices if this occurs, or alternatively use the unsafe
static_new_in_place()
function to create the Scratchpad
.
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,
[src]
impl<BufferT, TrackingT> Scratchpad<BufferT, TrackingT> where
BufferT: StaticBuffer,
TrackingT: Tracking + StaticBuffer,
pub fn static_new() -> Self
[src]
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 using large static arrays for allocation storage or marker
tracking can cause the program to run out of stack space while calling
this function. It is recommended to either use borrowed slices or
boxed slices if this occurs, or alternatively use the unsafe
static_new_in_place()
function to create the Scratchpad
.
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();
pub unsafe fn static_new_in_place(dst: *mut Self)
[src]
pub unsafe fn static_new_in_place(dst: *mut Self)
Initializes a new instance in uninitialized memory for scratchpad types backed entirely by static arrays.
This is provided to allow for creation of scratchpads backed by large
static arrays while guaranteeing that both arrays and the created
Scratchpad
are never accidentally stored on the stack, avoiding
possible stack overflow.
Safety
This function is unsafe because it operates on a raw pointer.
It does not drop any existing contents of dst
before writing, nor
does it check for whether dst
is a valid pointer.
dst
must be properly aligned for storage of an instance of
Scratchpad
.
After returning, the contents of dst
should be dropped when no
longer in use before the memory pointed to by dst
is freed. If dst
points to memory that belongs to an actual Scratchpad
instance, the
drop implementation will likely be called automatically when the
variable is destroyed.
Examples
use scratchpad::{CacheAligned, Scratchpad}; // Scratchpad that can hold up to 1 MB of data and up to 16 allocation // markers. type LargeScratchpad = Scratchpad< array_type_for_bytes!(CacheAligned, 1024 * 1024), array_type_for_markers!(usize, 16), >; unsafe { // The `Vec` here represents any region of memory in which a // `Scratchpad` needs to be initialized at runtime, whether // allocated from the heap or elsewhere. let mut memory = Vec::with_capacity(1); memory.set_len(1); LargeScratchpad::static_new_in_place(&mut memory[0]); let scratchpad = &memory[0]; let marker = scratchpad.mark_front().unwrap(); let allocation = marker.allocate(12).unwrap(); assert_eq!(*allocation, 12); }
impl<BufferT, TrackingT> Scratchpad<BufferT, TrackingT> where
BufferT: Buffer,
TrackingT: Tracking,
[src]
impl<BufferT, TrackingT> Scratchpad<BufferT, TrackingT> where
BufferT: Buffer,
TrackingT: Tracking,
pub fn mark_front<'scratchpad>(
&'scratchpad self
) -> Result<MarkerFront<'scratchpad, BufferT, TrackingT>, Error<()>>
[src]
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<()>>
[src]
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,
[src]
impl<BufferT, TrackingT> Debug for Scratchpad<BufferT, TrackingT> where
BufferT: Buffer,
TrackingT: Tracking,
Auto Trait Implementations
impl<BufferT, TrackingT> Send for Scratchpad<BufferT, TrackingT> where
BufferT: Send,
TrackingT: Send,
impl<BufferT, TrackingT> Send for Scratchpad<BufferT, TrackingT> where
BufferT: Send,
TrackingT: Send,
impl<BufferT, TrackingT> !Sync for Scratchpad<BufferT, TrackingT>
impl<BufferT, TrackingT> !Sync for Scratchpad<BufferT, TrackingT>