Crate recycle_box

A pointer type for heap-allocated objects which heap storage can be re-used.

The box can be consumed to drop the current object and re-use the allocated space to store another object, which type may be different. New memory will only be allocated if the new object does not fit within the currently allocated space.

Coercion from Sized to !Sized boxed objects is supported, including on Rust stable.

Last but not least: Pinned boxes can be recycled too, which is useful when repeatedly allocating Futures.

Examples

Store different objects, re-using if possible the previously allocated storage:

use recycle_box::RecycleBox;

// Store an object.
let box1 = RecycleBox::new(123u64);

// Store a smaller object.
let box2 = RecycleBox::recycle(box1, 456u16); // Does not allocate

// Store a larger object.
let box3 = RecycleBox::recycle(box2, [123u32; 8]); // New memory is allocated

// Move out and replace the previous object.
let (array3, box4) = RecycleBox::replace(box3, 789u32); // Does not allocate

// Drop the current object but preserve the allocated memory for further re-use.
// Note that `vacate()` is just an explicit shorthand for `recycle(())`.
let box5 = RecycleBox::vacate(box4);

Re-use the same box for different objects sharing the same trait:

use std::future::{self, Future};
use recycle_box::{RecycleBox, coerce_box};

let mut my_box: RecycleBox<dyn Future<Output = i32>> =
    coerce_box!(RecycleBox::new(future::ready(42)));
my_box = coerce_box!(RecycleBox::new(future::pending()));

Recycle a pinned box.

use std::pin::Pin;
use recycle_box::RecycleBox;

let pinned_box: Pin<_> = RecycleBox::new(42).into();
let new_box = RecycleBox::recycle_pinned(pinned_box, "Forty two");

Macros

coerce_box

Macro coercing a RecycleBox<T> into a RecycleBox<U>, provided that T can be coerced to U.

Structs

RecycleBox

A pointer type for heap-allocated objects which heap storage can be re-used.