This function simply drops the contents of the SetOnce, given a mutable reference - since that proves we have exclusive access to the SetOnce. Additionally, update the invariants for SetOnce to make it clear as to why this is safe.
Signed-off-by: Lyude Paul <[email protected]> --- rust/kernel/sync/set_once.rs | 60 +++++++++++++++++++++++++++++++----- 1 file changed, 52 insertions(+), 8 deletions(-) diff --git a/rust/kernel/sync/set_once.rs b/rust/kernel/sync/set_once.rs index 139cef05e935f..d6e4fc2695673 100644 --- a/rust/kernel/sync/set_once.rs +++ b/rust/kernel/sync/set_once.rs @@ -15,7 +15,7 @@ /// /// # Invariants /// -/// - `init` may only increase in value. +/// - `init` may only increase in value, unless modified through a mutable reference. /// - `init` may only assume values in the range `0..=2`. /// - `init == 0` if and only if `value` is uninitialized. /// - `init == 1` if and only if there is exactly one thread with exclusive @@ -110,17 +110,61 @@ pub fn copy(&self) -> Option<T> { self.as_ref().copied() } + + /// # Safety + /// + /// If this function returns `true`, `self` must be freed or `init` must be reset to `0`. + unsafe fn drop_val(&mut self) -> bool { + if *self.init.get_mut() != 2 { + return false; + } + + let value = self.value.get_mut(); + // SAFETY: Via our type invariants, `init` == 2 means `value` is initialized. + unsafe { value.assume_init_drop() }; + + true + } + + /// Unset the [`SetOnce`]. + /// + /// After this function is called, the [`SetOnce`] is empty and uninitialized. This function is + /// mainly intended for usage in destructors. + /// + /// Returns `true` if `self` was previously initialized. + /// + /// # Example + /// + /// ``` + /// # use kernel::sync::SetOnce; + /// let mut value = SetOnce::new(); + /// assert_eq!(value.populate(67), true); + /// + /// assert_eq!(value.reset(), true); + /// assert!(value.as_ref().is_none()); + /// assert_eq!(value.reset(), false); + /// + /// assert_eq!(value.populate(69), true); + /// ``` + pub fn reset(&mut self) -> bool { + // SAFETY: We write `0` to init below if this returns true. + let dropped = unsafe { self.drop_val() }; + if dropped { + // INVARIANT: + // - We set `init` back to 0 through a mutable reference. + // - We dropped `value` above. + *self.init.get_mut() = 0; + } + + dropped + } } impl<T> Drop for SetOnce<T> { + #[inline(always)] fn drop(&mut self) { - if *self.init.get_mut() == 2 { - let value = self.value.get_mut(); - // SAFETY: By the type invariants of `Self`, `self.init == 2` means that `self.value` - // contains a valid value. We have exclusive access, as we hold a `mut` reference to - // `self`. - unsafe { value.assume_init_drop() }; - } + // SAFETY: We are dropping this value. + unsafe { self.drop_val() }; } } -- 2.54.0
