Module moveit::stackbox

Stack-based owning pointers, for emplacement on the stack.

A StackBox can be created using the stackbox! macro:

stackbox!(let mut x = 5);
*x += 1;
assert_eq!(*x, 6);

Because a StackBox truly owns its contents, it will destroy them once it goes out of scope. However, a StackBox cannot escape the scope it is created in, since its storage is destroyed once that stack frame ends. Thus, StackBoxes cannot be returned directly.

A Slot is uninitialized storage for a StackBox, which can be consumed to produce a StackBox. Slots mut be created with the slot! macro:

slot!(storage);
let mut x = StackBox::new(42, storage);
*x /= 2;
assert_eq!(*x, 21);

Slots can also be used to implement a sort of “guaranteed RVO”:

fn returns_on_the_stack(val: i32, storage: Slot<i32>) -> Option<StackBox<i32>> {
  if val == 0 {
    return None
  }
  Some(StackBox::new(val, storage))
}

slot!(storage);
let val = returns_on_the_stack(42, storage);
assert_eq!(*val.unwrap(), 42);

Because they are pointer-like but uniquely own their contents, Ctors can be emplaced on the stack using StackBox, but way of StackBox::emplace() or the emplace! macro.

Structs

Slot	An empty slot on the stack into which a value could be emplaced.
StackBox	A stack-based owning pointer.