Macro singleton

macro_rules! singleton {
    ($name:ident: $ty:ty = $expr:expr) => { ... };
    (: $ty:ty = $expr:expr) => { ... };
}

Macro to create a mutable reference to a statically allocated value

This macro returns a value with type Option<&'static mut $ty>. Some($expr) will be returned the first time the macro is executed; further calls will return None. To avoid unwrapping a None variant the caller must ensure that the macro is called from a function that’s executed at most once in the whole lifetime of the program.

Notes

This macro is unsound on multi core systems.

For debuggability, you can set an explicit name for a singleton. This name only shows up the the debugger and is not referencable from other code. See example below.

Example

use cortex_m::singleton;

fn main() {
    // OK if `main` is executed only once
    let x: &'static mut bool = singleton!(: bool = false).unwrap();

    let y = alias();
    // BAD this second call to `alias` will definitively `panic!`
    let y_alias = alias();
}

fn alias() -> &'static mut bool {
    singleton!(: bool = false).unwrap()
}

fn singleton_with_name() {
    // A name only for debugging purposes
    singleton!(FOO_BUFFER: [u8; 1024] = [0u8; 1024]);
}