From 3d1017b0938a90ffb4517bf7ffaceddf10185537 Mon Sep 17 00:00:00 2001 From: sergerad Date: Thu, 5 Sep 2024 20:32:15 +1200 Subject: [PATCH] Update explanatory comments --- core/src/utils/sync/racy_lock.rs | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/core/src/utils/sync/racy_lock.rs b/core/src/utils/sync/racy_lock.rs index 3a61e93b4..16386c307 100644 --- a/core/src/utils/sync/racy_lock.rs +++ b/core/src/utils/sync/racy_lock.rs @@ -36,10 +36,11 @@ where } /// Forces the evaluation of the locked value and returns a reference to - /// the result. This is equivalent to the `Deref` impl, but is explicit. + /// the result. This is equivalent to the [`Self::deref`]. /// - /// This method will not block the calling thread if another initialization - /// routine is currently running. + /// There is no blocking involved in this operation. Instead, concurrent + /// threads will race to set the underlying pointer. Memory allocated by + /// losing threads will be dropped immediately after they fail to set the pointer. pub fn force(this: &RacyLock) -> &T { let mut ptr = this.inner.load(Ordering::Acquire); @@ -92,10 +93,9 @@ where { type Target = T; - /// Dereferences the value. + /// Either sets or retrieves the value, and dereferences it. /// - /// This method will not block the calling thread if another initialization - /// routine is currently running. + /// See [`Self::force`] for more details. #[inline] fn deref(&self) -> &T { RacyLock::force(self) @@ -106,6 +106,10 @@ impl Drop for RacyLock where F: Fn() -> T, { + /// Drops the underlying pointer. + /// + /// This operation is safe because the underlying pointer is owned by the lock. + /// It is not possible for the pointer to be shared between multiple locks. fn drop(&mut self) { let ptr = *self.inner.get_mut(); if !ptr.is_null() {