Skip to main content

off_stack

Macro off_stack 

Source
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.