macro_rules! off_stack {
($ty:ty, $val:expr) => { ... };
}Expand description
Returns a mutable reference to a value that is stored as a global static
variable rather than exist on the stack.
This is useful for working with large objects that don’t fit on the stack.
It is an alternative to using SingleThreaded with
RefCell; RefCell has the disadvantage of putting
an extra bool next to the value in memory, which can waste a lot of space
for heavily-aligned objects.
Panics if this function is called recursively, since this would attempt to create multiple mutable references to the same global variable.
This only works in a single-threaded environment.
Note that when off_stack is used in a function that can be called multiple
times, the caller must not assume the value is initialized with the value
specified in the macro. For example, if off_stack!(ArrayVec<u8>, ArrayVec::new_const()) is used in a function, the caller must not assume
that the value is an empty vector, since the function could have been called
before and left stale values, due to this being a wrapper around a global
variable.