From 462fc2d9aab8f0cba680caec344e4c388e9901b1 Mon Sep 17 00:00:00 2001 From: Mica White Date: Mon, 11 Mar 2024 16:33:26 -0400 Subject: Documentation --- src/rwlock/write_lock.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'src/rwlock/write_lock.rs') diff --git a/src/rwlock/write_lock.rs b/src/rwlock/write_lock.rs index dd204f5..0275a70 100644 --- a/src/rwlock/write_lock.rs +++ b/src/rwlock/write_lock.rs @@ -25,6 +25,16 @@ impl<'a, T: ?Sized, R> AsRef> for WriteLock<'a, T, R> { } impl<'a, T: ?Sized, R> WriteLock<'a, T, R> { + /// Creates a new `WriteLock` which accesses the given [`RwLock`] + /// + /// # Examples + /// + /// ``` + /// use happylock::{rwlock::WriteLock, RwLock}; + /// + /// let lock = RwLock::new(5); + /// let write_lock = WriteLock::new(&lock); + /// ``` #[must_use] pub const fn new(rwlock: &'a RwLock) -> Self { Self(rwlock) @@ -32,6 +42,8 @@ impl<'a, T: ?Sized, R> WriteLock<'a, T, R> { } impl<'a, T: ?Sized, R: RawRwLock> WriteLock<'a, T, R> { + /// Locks the underlying [`RwLock`] with exclusive write access, blocking + /// the current until it can be acquired. pub fn lock<'s, 'key: 's, Key: Keyable + 'key>( &'s self, key: Key, @@ -39,10 +51,13 @@ impl<'a, T: ?Sized, R: RawRwLock> WriteLock<'a, T, R> { self.0.write(key) } + /// Creates an exclusive lock without a key. Locking this without exclusive + /// access to the key is undefined behavior. pub(crate) unsafe fn lock_no_key(&self) -> RwLockWriteRef<'_, T, R> { self.0.write_no_key() } + /// Attempts to lock the underlying [`RwLock`] with exclusive write access. pub fn try_lock<'s, 'key: 's, Key: Keyable + 'key>( &'s self, key: Key, @@ -50,10 +65,14 @@ impl<'a, T: ?Sized, R: RawRwLock> WriteLock<'a, T, R> { self.0.try_write(key) } + /// Attempts to create an exclusive lock without a key. Locking this + /// without exclusive access to the key is undefined behavior. pub(crate) unsafe fn try_lock_no_key(&self) -> Option> { self.0.try_write_no_key() } + /// Immediately drops the guard, and consequently releases the exclusive + /// lock. pub fn unlock<'key, Key: Keyable + 'key>(guard: RwLockWriteGuard<'_, 'key, T, Key, R>) -> Key { RwLock::unlock_write(guard) } -- cgit v1.2.3