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

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.


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.


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]);