diff --git a/src/stdsync.rs b/src/stdsync.rs index 41c1806..14c72f4 100644 --- a/src/stdsync.rs +++ b/src/stdsync.rs @@ -93,6 +93,7 @@ where } impl TracingMutex { + /// Create a new tracing mutex with the provided value. pub fn new(t: T) -> Self { Self { inner: Mutex::new(t), @@ -100,6 +101,12 @@ impl TracingMutex { } } + /// Wrapper for [`std::sync::Mutex::lock`]. + /// + /// # Panics + /// + /// This method participates in lock dependency tracking. If acquiring this lock introduces a + /// dependency cycle, this method will panic. #[track_caller] pub fn lock(&self) -> LockResult> { let mutex = self.id.get_borrowed(); @@ -113,6 +120,12 @@ impl TracingMutex { map_lockresult(result, mapper) } + /// Wrapper for [`std::sync::Mutex::try_lock`]. + /// + /// # Panics + /// + /// This method participates in lock dependency tracking. If acquiring this lock introduces a + /// dependency cycle, this method will panic. #[track_caller] pub fn try_lock(&self) -> TryLockResult> { let mutex = self.id.get_borrowed(); @@ -126,14 +139,19 @@ impl TracingMutex { map_trylockresult(result, mapper) } + /// Wrapper for [`std::sync::Mutex::is_poisoned`]. pub fn is_poisoned(&self) -> bool { self.inner.is_poisoned() } + /// Return a mutable reference to the underlying data. + /// + /// This method does not block as the locking is handled compile-time by the type system. pub fn get_mut(&mut self) -> LockResult<&mut T> { self.inner.get_mut() } + /// Unwrap the mutex and return its inner value. pub fn into_inner(self) -> LockResult { self.inner.into_inner() } @@ -194,6 +212,12 @@ impl TracingRwLock { } } + /// Wrapper for [`std::sync::RwLock::read`]. + /// + /// # Panics + /// + /// This method participates in lock dependency tracking. If acquiring this lock introduces a + /// dependency cycle, this method will panic. #[track_caller] pub fn read(&self) -> LockResult> { let mutex = self.id.get_borrowed(); @@ -202,6 +226,12 @@ impl TracingRwLock { map_lockresult(result, |inner| TracingRwLockGuard { inner, mutex }) } + /// Wrapper for [`std::sync::RwLock::write`]. + /// + /// # Panics + /// + /// This method participates in lock dependency tracking. If acquiring this lock introduces a + /// dependency cycle, this method will panic. #[track_caller] pub fn write(&self) -> LockResult> { let mutex = self.id.get_borrowed(); @@ -210,6 +240,12 @@ impl TracingRwLock { map_lockresult(result, |inner| TracingRwLockGuard { inner, mutex }) } + /// Wrapper for [`std::sync::RwLock::try_read`]. + /// + /// # Panics + /// + /// This method participates in lock dependency tracking. If acquiring this lock introduces a + /// dependency cycle, this method will panic. #[track_caller] pub fn try_read(&self) -> TryLockResult> { let mutex = self.id.get_borrowed(); @@ -218,6 +254,12 @@ impl TracingRwLock { map_trylockresult(result, |inner| TracingRwLockGuard { inner, mutex }) } + /// Wrapper for [`std::sync::RwLock::try_write`]. + /// + /// # Panics + /// + /// This method participates in lock dependency tracking. If acquiring this lock introduces a + /// dependency cycle, this method will panic. #[track_caller] pub fn try_write(&self) -> TryLockResult> { let mutex = self.id.get_borrowed(); @@ -226,10 +268,14 @@ impl TracingRwLock { map_trylockresult(result, |inner| TracingRwLockGuard { inner, mutex }) } + /// Return a mutable reference to the underlying data. + /// + /// This method does not block as the locking is handled compile-time by the type system. pub fn get_mut(&mut self) -> LockResult<&mut T> { self.inner.get_mut() } + /// Unwrap the mutex and return its inner value. pub fn into_inner(self) -> LockResult { self.inner.into_inner() }