Crate stack_dst

Support for storing dynamically-sized types within fixed-size allocations

• The Value type provides a fixed size (7 word in the current version) buffer in which a trait object or array can be stored, without resorting to a heap allocation.
• The Fifo and Stack types provide collection types (first-in-first-out and last-in-first-out).

Examples

An unboxed any

As a quick example - The following wraps a 64-bit integer up in an inline DST using the Any trait.

let dst = Value::<dyn Any, ::stack_dst::buffers::Ptr2>::new_stable(1234u64, |p| p as _)
    .ok().expect("Integer did not fit in allocation");
println!("dst as u64 = {:?}", dst.downcast_ref::<u64>());
println!("dst as i8 = {:?}", dst.downcast_ref::<i8>());

Stack-allocated closure!

The following snippet shows how small ('static) closures can be returned using this crate

fn make_closure(value: u64) -> Value<dyn FnMut()->String, ::stack_dst::array_buf![u64; U2]> {
    Value::new_stable(move || format!("Hello there! value={}", value), |p| p as _)
        .ok().expect("Closure doesn't fit")
}
let mut closure = make_closure(666);
assert_eq!( (&mut *closure)(), "Hello there! value=666" );

Custom allocation sizes/types

If you need larger alignment, you can use a different type for the backing array. (Note, that metadata uses at least one slot in the array)

This code panics, because i128 requires 8/16 byte alignment (usually)

let v: Value<dyn Any, ::stack_dst::buffers::U8_32> = Value::new_stable(123i128, |p| p as _).unwrap();

This works, because the backing buffer has sufficient alignment

let v: Value<dyn Any, ::stack_dst::array_buf![u128; U2]> = Value::new_stable(123i128, |p| p as _).unwrap();

Feature flags

alloc (default)

Provides the StackDstA::new_or_boxed method (if unsize feature is active too)

const_generics (default)

Uses value/constant generics to provide a slightly nicer API (e.g. ValueU)

unsize (optional)

Uses the nightly feature unsize to provide a more egonomic API (no need for the |p| p closures)

Re-exports

• pub use fifo::Fifo;
• pub use stack::Stack;
• pub use value::Value;

Modules

• buffers
  Type aliases for common buffer sizes and types
• fifo
  Implementation of the FIFO list structure
• stack
  Implementation of the LIFO stack structure
• value
  Implementation of the single-value structure Single DST stored inline

Macros

• array_buf
  Shorthand for defining a array buffer

Traits

• AlignmentValid
  Marker trait used to check alignment
• DataBuf
  Trait used to represent a data buffer, typically you’ll passs a [usize; N] array.
• Pod
  Trait that indicates that a type is valid for any bit pattern

Type Definitions

• FifoU
  A FIFO queue of DSTs using a usize aligned buffer
• StackU
  A single LIFO stack of DSTs using a usize aligned buffer
• ValueU
  A single dynamically-sized value stored in a usize aligned buffer