xtensa_lx/
macros.rs

1/// Macro to create a mutable reference to a statically allocated value
2///
3/// This macro returns a value with type `Option<&'static mut $ty>`.
4/// `Some($expr)` will be returned the first time the macro is executed; further
5/// calls will return `None`. To avoid `unwrap`ping a `None` variant the caller
6/// must ensure that the macro is called from a function that's executed at most
7/// once in the whole lifetime of the program.
8///
9/// # Example
10///
11/// ``` no_run
12/// use xtensa_lx::singleton;
13///
14/// fn main() {
15///     // OK if `main` is executed only once
16///     let x: &'static mut bool = singleton!(: bool = false).unwrap();
17///
18///     let y = alias();
19///     // BAD this second call to `alias` will definitively `panic!`
20///     let y_alias = alias();
21/// }
22///
23/// fn alias() -> &'static mut bool {
24///     singleton!(: bool = false).unwrap()
25/// }
26/// ```
27#[macro_export]
28macro_rules! singleton {
29    ($(#[$meta:meta])* $name:ident: $ty:ty = $expr:expr) => {
30        $crate::_export::critical_section::with(|_| {
31            // this is a tuple of a MaybeUninit and a bool because using an Option here is
32            // problematic:  Due to niche-optimization, an Option could end up producing a non-zero
33            // initializer value which would move the entire static from `.bss` into `.data`...
34            $(#[$meta])*
35            static mut $name: (::core::mem::MaybeUninit<$ty>, bool) =
36                (::core::mem::MaybeUninit::uninit(), false);
37
38            #[allow(unsafe_code)]
39            let used = unsafe { $name.1 };
40            if used {
41                None
42            } else {
43                let expr = $expr;
44
45                #[allow(unsafe_code)]
46                unsafe {
47                    $name.1 = true;
48                    Some($name.0.write(expr))
49                }
50            }
51        })
52    };
53    ($(#[$meta:meta])* : $ty:ty = $expr:expr) => {
54        $crate::singleton!($(#[$meta])* VAR: $ty = $expr)
55    };
56}
xtensa_lx/macros.rs

xtensa_lx/
macros.rs
