Macro fragile::stack_token

macro_rules! stack_token {
    ($name:ident) => { ... };
}

Crates a token on the stack with a certain name for semi-sticky.

The argument to the macro is the target name of a local variable which holds a reference to a stack token. Because this is the only way to create such a token, it acts as a proof to Sticky or SemiSticky that can be used to constrain the lifetime of the return values to the stack frame.

This is necessary as otherwise a Sticky placed in a Box and leaked with Box::leak (which creates a static lifetime) would otherwise create a reference with 'static lifetime. This is incorrect as the actual lifetime is constrained to the lifetime of the thread. For more information see issue 26.

let sticky = fragile::Sticky::new(true);

// this places a token on the stack.
fragile::stack_token!(my_token);

// the token needs to be passed to `get` and others.
let _ = sticky.get(my_token);