memapi 0.5.10

A minimal, no_std-friendly memory allocation interface for raw buffers, with some error handling.
Documentation

memapi

crates.io docs.rs

A minimal, no_std-friendly memory allocation interface for managing raw buffers, suitable for use in collections.

Features

  • Error reporting via AllocError
  • no_std compatible
  • Optional nightly support via allocator_api feature
  • Zero-cost wrapper over the global allocator
  • Fall-back implementation for stable Rust
  • Allocation, deallocation, grow/shrink, and realloc operations
  • Extension methods via alloc_ext feature

Installation

Add to your Cargo.toml:

[dependencies]
memapi = "0.5.10"

To enable the nightly allocator API integration:

[dependencies.memapi]
version = "0.5.10"
features = ["nightly"]

To enable the alloc extension methods:

[dependencies.memapi]
version = "0.5.10"
features = ["alloc_ext"]

API

Trait: Alloc

Defines the minimal allocation interface. Methods include:

  • alloc(layout) -> Result<NonNull<u8>, AllocError> Attempts to allocate a block fitting the given Layout. Errors: AllocError::AllocFailed(layout) if allocation fails.

  • alloc_zeroed(layout) -> Result<NonNull<u8>, AllocError> Allocates zero-initialized memory. Errors: AllocError::AllocFailed(layout) if allocation fails.

  • alloc_filled(layout, u8) -> Result<NonNull<u8>, AllocError> Allocates memory filled with the specified byte. Errors: AllocError::AllocFailed(layout) if allocation fails.

  • alloc_patterned(layout, F) -> Result<NonNull<u8>, AllocError> Allocates memory and fills each byte via pattern(i). Errors: AllocError::AllocFailed(layout) if allocation fails.

  • Convenience helpers:

    • alloc_count<T>(count) -> Result<NonNull<T>, AllocError> Errors: AllocError::LayoutError if size too large, or AllocError::AllocFailed(layout).
    • alloc_count_zeroed<T>(count)
    • alloc_count_filled<T>(count, u8)
    • alloc_count_patterned<T, F>(count, pattern)

  • dealloc(ptr, layout) Safety: Must match a prior alloc call.

  • drop_and_dealloc<T: ?Sized>(ptr) Drops the value then deallocates. Safety: ptr must be valid for reads and writes, aligned, and allocated by this allocator.

  • grow / grow_zeroed / grow_filled / grow_patterned Expands a block, optionally initializing new bytes. Errors: AllocError::GrowSmallerNewLayout if new < old, or AllocError::AllocFailed(layout).

  • shrink Contracts a block. Errors: AllocError::ShrinkBiggerNewLayout if new > old, or AllocError::AllocFailed(layout).

  • realloc / realloc_zeroed / realloc_filled / realloc_patterned Reallocate, growing or shrinking in one step. Errors: See grow/shrink variants.

Trait: AllocExt (feature = alloc_ext)

Extension methods built on top of Alloc for common allocation patterns:

  • alloc_write<T>(data: T) -> Result<NonNull<T>, AllocError> Allocates and writes a single T. Errors: AllocError::AllocFailed on allocation failure.
  • alloc_clone_to<T: Clone>(&T) -> Result<NonNull<T>, AllocError> Allocates and clones a T into newly allocated space. Errors: AllocError::AllocFailed on allocation failure.
  • alloc_clone_slice_to<T: Clone>(&[T]) -> Result<NonNull<[T]>, AllocError> Allocates and clones each element of a slice. Errors: AllocError::AllocFailed on allocation failure.
  • alloc_slice_with<T, F: Fn(usize) -> T>(usize, F) -> Result<NonNull<[T]>, AllocError> Allocates a slice and fills each element with the result of F(elem_idx).
  • Errors: AllocError::AllocFailed on allocation failure or AllocError::LayoutError if the length is too large.
  • dealloc_slice<T>(NonNull<[T]>) Deallocates a previously allocated slice. Safety: Must match one of the clone/write methods.
  • drop_and_dealloc_slice<T>(NonNull<[T]>) Drops slice contents then deallocates. Safety: Must match one of the clone/write methods.
  • alloc_copy_ref_to<T: ?Sized + UnsizedCopy>(&T) -> Result<NonNull<T>, AllocError> Safe wrapper to allocate and copy unsized data by reference. Errors: AllocError::AllocFailed.
  • alloc_copy_ptr_to<T: ?Sized + UnsizedCopy>(*const T) -> Result<NonNull<T>, AllocError> Safe wrapper to allocate and copy unsized data by pointer. Errors: AllocError::AllocFailed.
  • alloc_copy_ref_to_unchecked<T: ?Sized>(&T) -> Result<NonNull<T>, AllocError> Unsafe version without layout checks. Safety: Caller ensures validity and metadata.
  • alloc_copy_ptr_to_unchecked<T: ?Sized + UnsizedCopy>(*const T) -> Result<NonNull<T>, AllocError> Unsafe version copying unsized data by pointer. Safety: Caller ensures validity.

Trait: SizedProps

Defines compile-time constants for all Sized types:

  • const SZ: usize The byte-size of Self (equivalent to size_of::<Self>()).

  • const ALIGN: usize The alignment requirement of Self (equivalent to align_of::<Self>()).

  • const LAYOUT: Layout A Layout constructed from SZ and ALIGN via from_size_align_unchecked.

  • const IS_ZST: bool true if SZ == 0, i.e. Self is zero-sized.

  • const MAX_SLICE_LEN: usize The maximum safe length for a [Self] slice without overflowing (for SZ == 0, this is usize::MAX; otherwise (isize::MAX as usize) / SZ).

Trait: PtrProps<T: ?Sized>

Gives pointer‐types a way to query the layout of the pointee:

  • unsafe fn size(&self) -> usize Returns the byte-size of the value behind the pointer.

  • unsafe fn align(&self) -> usize Returns the alignment requirement of the value behind the pointer.

  • unsafe fn layout(&self) -> Layout Builds a Layout for the pointee from size(self) and align(self).

  • unsafe fn is_zst(&self) -> bool Returns true if the value is zero-sized.

  • unsafe fn max_slice_len(&self) -> usize Max safe slice length for copies of the pointee (for SZ == 0, this is usize::MAX; otherwise (isize::MAX as usize) / SZ).

No-Std Support

This crate is written to work without the Rust standard library. Simply depend on memapi in your #![no_std] project; it will pull in alloc from the core Rust distribution.

Documentation

License

Licensed under Apache-2.0 OR MIT. See LICENSE-APACHE and LICENSE-MIT for details.