From a9e099c2151221f66571ab0001b77fe639c149ee Mon Sep 17 00:00:00 2001 From: Joshua Salzedo Date: Wed, 24 Mar 2021 12:36:17 -0700 Subject: [PATCH] Document embassy::util::Forever --- embassy/src/util/forever.rs | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/embassy/src/util/forever.rs b/embassy/src/util/forever.rs index ac23a3ce3..efa96f30e 100644 --- a/embassy/src/util/forever.rs +++ b/embassy/src/util/forever.rs @@ -3,6 +3,25 @@ use core::mem::MaybeUninit; use atomic_polyfill::{AtomicBool, Ordering}; +/// Type with static lifetime that may be written to once at runtime. +/// +/// This may be used to initialize static objects at runtime, typically in the init routine. +/// This is useful for objects such as Embassy's RTC, which cannot be initialized in a const +/// context. +/// +/// Note: IF a global mutable variable is desired, use a CriticalSectionMutex or ThreadModeMutex instead. +/// +/// ``` +/// use embassy::util::Forever; +/// // Using an integer for the sake of keeping this example self-contained, +/// // see https://github.com/embassy-rs/embassy/wiki/Getting-Started for a more "proper" example. +/// static SOME_INT: Forever =Forever::new(); +/// +/// // put returns a mutable pointer to the object stored in the forever, which may then be passed +/// // around. +/// let mut x = SOME_INT.put(42); +/// assert_eq!(*x, 42); +/// ``` pub struct Forever { used: AtomicBool, t: UnsafeCell>, @@ -19,6 +38,11 @@ impl Forever { } } + /// Gives this `Forever` a value. + /// + /// Panics if this `Forever` already has a value. + /// + /// Returns a mutable reference to the stored value. pub fn put(&'static self, val: T) -> &'static mut T { if self .used