Struct Teaspoon

Source

pub struct Teaspoon<'a, S: Sizing> { /* private fields */ }

Expand description

The Teaspoon allocator.

The allocator comes in 3 variants that set different memory overheads and limits. The S parameter specifies the variant, which may be:

Sizing4KiB: allows allocating objects up to 4 KiB
Sizing128KiB: allows allocating objects up to 128 KiB
Sizing16MiB: allows allocating objects up to 16 MiB

See the module-level documentation for more information about overheads and sizing limits.

Teaspoon can be constructed from either a pointer (unsafe) or a slice, and may be accessed using either the GlobalAlloc or [Allocator] traits. See the module-level documentation for details and examples.

Implementations§

Source §

impl<'a, S: Sizing> Teaspoon<'a, S>

Source

pub fn from_slice(slice: &'a mut [u8]) -> Self

Constructs a Teaspoon memory allocator from a slice.

§Examples

use teaspoon::Teaspoon4KiB;

let mut memory = [0u8; 1024];
let spoon = Teaspoon4KiB::from_slice(&mut memory);

Source

pub unsafe fn from_ptr(ptr: *mut [u8]) -> Self

Constructs a Teaspoon memory allocator from a slice pointer.

The pointer must be valid for both reads and writes, and must be alive for the lifetime of 'a. Note that because there’s no connection between the pointer and the lifetime 'a, you must ensure that the pointer lives long enough; you cannot rely on the compiler to check that for you.

§Panics

If ptr is a null pointer.

§Safety

ptr must be “dereferenceable”.
ptr must be alive for the lifetime of 'a.
ptr must not be an alias for another reference or pointer (in other words, ptr is a unique pointer).

An exception to those rules is if the length of ptr is 0. In that case, ptr may be a dangling non-null pointer.

§Examples

use teaspoon::Teaspoon4KiB;

let mut memory = [0u8; 1024];
let ptr = std::ptr::slice_from_raw_parts_mut(memory.as_mut_ptr(), memory.len());
let spoon = unsafe { Teaspoon4KiB::from_ptr(ptr) };

Source

pub unsafe fn from_ptr_size(ptr: *mut u8, size: usize) -> Self

Constructs a Teaspoon memory allocator from a pointer and a size.

The pointer must be valid for both reads and writes, and must be alive for the lifetime of 'a. Note that because there’s no connection between the pointer and the lifetime 'a, you must ensure that the pointer lives long enough; you cannot rely on the compiler to check that for you.

§Panics

If ptr is a null pointer.

§Safety

ptr must be “dereferenceable”.
ptr must be alive for the lifetime of 'a.
ptr must not be an alias for another reference or pointer (in other words, ptr is a unique pointer).

An exception to those rules is if the size is 0. In that case, ptr may be a dangling non-null pointer.

§Examples

use teaspoon::Teaspoon4KiB;

let mut memory = [0u8; 1024];
let spoon = unsafe { Teaspoon4KiB::from_ptr_size(memory.as_mut_ptr(), memory.len()) };

Source

pub unsafe fn from_addr_size(addr: usize, size: usize) -> Self

Constructs a Teaspoon memory allocator from an address and a size.

The memory pointed by address must be valid for both reads and writes, and must be alive for the lifetime of 'a. Note that because there’s no connection between the address and the lifetime 'a, you must ensure that the memory pointed by address lives long enough; you cannot rely on the compiler to check that for you.

§Panics

If addr is 0.

§Safety

the memory pointed by addr must be “dereferenceable”.
the memory pointed by addr must be alive for the lifetime of 'a.
the memory pointed by addr must not be an alias for another reference or address (in other words, addr is a unique address).

An exception to those rules is if the size is 0. In that case, addr may be a dangling non-null address.

§Examples

use teaspoon::Teaspoon4KiB;

let mut memory = [0u8; 1024];
let spoon = unsafe { Teaspoon4KiB::from_addr_size(memory.as_mut_ptr() as usize, memory.len()) };

Source

pub fn usage(&self) -> Usage

Returns memory usage information for this Teaspoon allocator.

The returned value contains some basic information about the memory currently used by the allocator, such as: the total memory available, the total memory used, the total memory usable, and the number of objects allocated.

See the Usage documentation for the exact meaning of each field returned.

Note that the usage computation is not cached or optimized in any way, and requires visiting all the objects currently allocated. As such, usage() is not a constant-time operation (O(1)), but it’s a linear-time operation (O(n), where n is the number of objects currently allocated). This is because the Teaspoon allocator is optimized to minimize overhead, and a faster usage() would require more overhead.

§Examples

#![feature(allocator_api)]

use std::alloc::Allocator;
use std::alloc::Layout;
use teaspoon::Teaspoon4KiB;
use teaspoon::Usage;

let mut memory = [0u8; 1024];
let spoon = Teaspoon4KiB::from(&mut memory);

assert_eq!(
    spoon.usage(),
    Usage {
        total: 1024,
        used: 0,
        free: 1020,
        objects: 0
    }
);

let _ = spoon.allocate(Layout::new::<u128>());

assert_eq!(
    spoon.usage(),
    Usage {
        total: 1024,
        used: 16,
        free: 1000,
        objects: 1
    }
);