Uses old Rust 2015
0.1.3 |
|
---|---|
0.1.2 |
|
0.1.1 |
|
0.1.0 |
|
#20 in #aligned
287 downloads per month
Used in 8 crates
(3 directly)
9KB
127 lines
Aligned Allocations for Rust
Linux / OS X | Windows |
---|---|
This crate provides cross-platform primitives for requesting specifically
aligned allocations. It is not meant to be used as a general allocator API
like alloc::heap
, but can be used for infrequent large allocations that have a
specific alignment requirement.
For example, certain arena allocators can find the arena in which an object was allocated by masking the address bits if the arena is aligned to its size.
On Unix, this crate makes use of the posix_memalign
function. On Windows, it's
a little more complicated: We use VirtualAlloc
to reserve a chunk of address
space large enough for the allocation plus alignment (no memory is actually
allocated), then calculate an aligned address inside this reserved space, undo
the reservation with VirtualFree
(the extra bit of reserved memory for the
alignment won't get wasted), and VirtualAlloc
again, this time passing the aligned pointer and
actually allocating the memory instead of just reserving address space.
Usage
As usual, in your Cargo.toml
:
[dependencies]
aligned_alloc = "0.1"
And in your lib.rs
or bin.rs
:
extern crate aligned_alloc;
API
The API is simple, there are just two methods:
fn aligned_alloc(size: usize, align: usize) -> *mut ()
Allocates size
Bytes aligned to align
Bytes. Returns a null pointer on allocation failure.
The returned pointer must be deallocated by using aligned_free
.
Note: This function is meant to be used for infrequent large allocations (as malloc
already
guarantees suitable alignment for all native datatypes) and might be quite slow when used
heavily.
Parameters
size
: The size of the allocation in bytes.align
: The alignment of the allocation (at least the size ofusize
on the current platform). Must also be a power of two.
unsafe fn aligned_free(ptr: *mut ())
Deallocates aligned memory that was allocated with aligned_alloc
. Unsafe because calling this
with a pointer that was not allocated with aligned_alloc
(or already released) causes
undefined behavior.
Dependencies
~115KB