scratchpad
A Rust library providing a stack-like memory allocator with double-ended allocation support.
Scratchpad
provides a method for quick and safe dynamic allocations of
arbitrary types without relying on the global heap (e.g. using Box
or
Vec
). Allocations are made from a fixed-size region of memory in a
stack-like fashion using two separate stacks (one for each end of the
allocation buffer) to allow different types of allocations with independent
lifecycles to be made from each end.
Such allocators are commonly used in game development, but are also useful in general for short-lived allocations or groups of allocations that share a common lifetime. While not quite as flexible as heap allocations, allocations from a stack allocator are usually much faster and are isolated from the rest of the heap, reducing memory fragmentation.
Features include:
- User-defined backing storage of data (static arrays, boxed slices, or mutable slice references).
- Allocation of any data type from any scratchpad instance.
- Ability to combine allocations that are adjacent in memory or add to the most recently created allocation.
- Double-ended allocation support (allocations from the "front" are separate from the "back", but share the same memory pool).
- Use of lifetimes to prevent dangling references to allocated data.
- Low runtime overhead.
- Support for
no_std
usage.
Usage
Add this to your Cargo.toml
:
[]
= "1.1"
and this to your crate root:
extern crate scratchpad;
Rust Version Support
The minimum supported Rust version is 1.25 due to use of NonNull<T>
and the
repr(align)
attribute.
no_std
Support
scratchpad
doesn't require the Rust standard library, although it makes use
of it by default (via the std
crate feature) to provide support for use of
Box
and Vec
in various places. For no_std
support, the std
feature
must be disabled in your Cargo.toml
:
[]
= { = "1.1", = false }
Box
and Vec
support is still available for no_std
builds when using a
nightly toolchain by enabling the unstable
crate feature.
Unstable Features
The unstable
crate feature provides some additional functionality when using
a nightly toolchain:
- Support for
Box
andVec
types as mentioned with thestd
feature, regardless of whether thestd
feature is enabled (ifstd
is disabled, this will use thealloc
library directly). - Declaration of the function
Scratchpad::new()
asconst
. ByteData
trait implementations foru128
/i128
for Rust versions prior to 1.26 (u128
/i128
support is enabled by default with both stable and unstable toolchains if the detected Rust version is 1.26 or greater).
Simply add the unstable
feature to your Cargo.toml
dependency:
[]
= { = "1.1", = ["unstable"] }