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 unwrap
ping 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]);
}