| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License.. |
| |
| use crate::cell::UnsafeCell; |
| use crate::fmt; |
| use crate::ops::{Deref, DerefMut}; |
| use crate::sync::{poison, LockResult, TryLockError, TryLockResult}; |
| use crate::sys_common::rwlock as sys; |
| |
| use sgx_libc as libc; |
| |
| pub use crate::sys_common::rwlock::SgxThreadRwLock; |
| |
| |
| /// A reader-writer lock |
| /// |
| /// This type of lock allows a number of readers or at most one writer at any |
| /// point in time. The write portion of this lock typically allows modification |
| /// of the underlying data (exclusive access) and the read portion of this lock |
| /// typically allows for read-only access (shared access). |
| /// |
| /// In comparison, a [`Mutex`] does not distinguish between readers or writers |
| /// that acquire the lock, therefore blocking any threads waiting for the lock to |
| /// become available. An `RwLock` will allow any number of readers to acquire the |
| /// lock as long as a writer is not holding the lock. |
| /// |
| /// The priority policy of the lock is dependent on the underlying operating |
| /// system's implementation, and this type does not guarantee that any |
| /// particular policy will be used. In particular, a writer which is waiting to |
| /// acquire the lock in `write` might or might not block concurrent calls to |
| /// `read`, e.g.: |
| /// |
| /// <details><summary>Potential deadlock example</summary> |
| /// |
| /// ```text |
| /// // Thread 1 | // Thread 2 |
| /// let _rg = lock.read(); | |
| /// | // will block |
| /// | let _wg = lock.write(); |
| /// // may deadlock | |
| /// let _rg = lock.read(); | |
| /// ``` |
| /// </details> |
| /// |
| /// The type parameter `T` represents the data that this lock protects. It is |
| /// required that `T` satisfies [`Send`] to be shared across threads and |
| /// [`Sync`] to allow concurrent access through readers. The RAII guards |
| /// returned from the locking methods implement [`Deref`] (and [`DerefMut`] |
| /// for the `write` methods) to allow access to the content of the lock. |
| /// |
| /// # Poisoning |
| /// |
| /// An `RwLock`, like [`SgxMutex`], will become poisoned on a panic. Note, however, |
| /// that an `RwLock` may only be poisoned if a panic occurs while it is locked |
| /// exclusively (write mode). If a panic occurs in any reader, then the lock |
| /// will not be poisoned. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::sync::SgxRwLock as RwLock; |
| /// |
| /// let lock = RwLock::new(5); |
| /// |
| /// // many reader locks can be held at once |
| /// { |
| /// let r1 = lock.read().unwrap(); |
| /// let r2 = lock.read().unwrap(); |
| /// assert_eq!(*r1, 5); |
| /// assert_eq!(*r2, 5); |
| /// } // read locks are dropped at this point |
| /// |
| /// // only one write lock may be held, however |
| /// { |
| /// let mut w = lock.write().unwrap(); |
| /// *w += 1; |
| /// assert_eq!(*w, 6); |
| /// } // write lock is dropped here |
| /// ``` |
| /// |
| /// [`SgxMutex`]: super::SgxMutex |
| pub struct SgxRwLock<T: ?Sized> { |
| inner: sys::SgxMovableThreadRwLock, |
| poison: poison::Flag, |
| data: UnsafeCell<T>, |
| } |
| |
| unsafe impl<T: ?Sized + Send> Send for SgxRwLock<T> {} |
| unsafe impl<T: ?Sized + Send + Sync> Sync for SgxRwLock<T> {} |
| |
| /// RAII structure used to release the shared read access of a lock when |
| /// dropped. |
| /// |
| /// This structure is created by the [`read`] and [`try_read`] methods on |
| /// [`RwLock`]. |
| /// |
| /// [`read`]: RwLock::read |
| /// [`try_read`]: RwLock::try_read |
| pub struct SgxRwLockReadGuard<'a, T: ?Sized + 'a> { |
| lock: &'a SgxRwLock<T>, |
| } |
| |
| impl<T: ?Sized> !Send for SgxRwLockReadGuard<'_, T> {} |
| unsafe impl<T: ?Sized + Sync> Sync for SgxRwLockReadGuard<'_, T> {} |
| |
| /// RAII structure used to release the exclusive write access of a lock when |
| /// dropped. |
| /// |
| /// This structure is created by the [`write`] and [`try_write`] methods |
| /// on [`RwLock`]. |
| /// |
| /// [`write`]: RwLock::write |
| /// [`try_write`]: RwLock::try_write |
| pub struct SgxRwLockWriteGuard<'a, T: ?Sized + 'a> { |
| lock: &'a SgxRwLock<T>, |
| poison: poison::Guard, |
| } |
| |
| impl<T: ?Sized> !Send for SgxRwLockWriteGuard<'_, T> {} |
| unsafe impl<T: ?Sized + Sync> Sync for SgxRwLockWriteGuard<'_, T> {} |
| |
| impl<T> SgxRwLock<T> { |
| /// Creates a new instance of an `RwLock<T>` which is unlocked. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::sync::SgxRwLock as RwLock; |
| /// |
| /// let lock = RwLock::new(5); |
| /// ``` |
| pub fn new(t: T) -> SgxRwLock<T> { |
| SgxRwLock { |
| inner: sys::SgxMovableThreadRwLock::new(), |
| poison: poison::Flag::new(), |
| data: UnsafeCell::new(t), |
| } |
| } |
| } |
| |
| impl<T: ?Sized> SgxRwLock<T> { |
| /// Locks this rwlock with shared read access, blocking the current thread |
| /// until it can be acquired. |
| /// |
| /// The calling thread will be blocked until there are no more writers which |
| /// hold the lock. There may be other readers currently inside the lock when |
| /// this method returns. This method does not provide any guarantees with |
| /// respect to the ordering of whether contentious readers or writers will |
| /// acquire the lock first. |
| /// |
| /// Returns an RAII guard which will release this thread's shared access |
| /// once it is dropped. |
| /// |
| /// # Errors |
| /// |
| /// This function will return an error if the RwLock is poisoned. An RwLock |
| /// is poisoned whenever a writer panics while holding an exclusive lock. |
| /// The failure will occur immediately after the lock has been acquired. |
| /// |
| /// # Panics |
| /// |
| /// This function might panic when called if the lock is already held by the current thread. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::sync::{Arc, SgxRwLock as RwLock}; |
| /// use std::thread; |
| /// |
| /// let lock = Arc::new(RwLock::new(1)); |
| /// let c_lock = Arc::clone(&lock); |
| /// |
| /// let n = lock.read().unwrap(); |
| /// assert_eq!(*n, 1); |
| /// |
| /// thread::spawn(move || { |
| /// let r = c_lock.read(); |
| /// assert!(r.is_ok()); |
| /// }).join().unwrap(); |
| /// ``` |
| #[inline] |
| pub fn read(&self) -> LockResult<SgxRwLockReadGuard<'_, T>> { |
| unsafe { |
| let ret = self.inner.read(); |
| match ret { |
| Err(libc::EAGAIN) => panic!("rwlock maximum reader count exceeded"), |
| Err(libc::EDEADLK) => panic!("rwlock read lock would result in deadlock"), |
| _ => SgxRwLockReadGuard::new(self), |
| } |
| } |
| } |
| |
| /// Attempts to acquire this rwlock with shared read access. |
| /// |
| /// If the access could not be granted at this time, then `Err` is returned. |
| /// Otherwise, an RAII guard is returned which will release the shared access |
| /// when it is dropped. |
| /// |
| /// This function does not block. |
| /// |
| /// This function does not provide any guarantees with respect to the ordering |
| /// of whether contentious readers or writers will acquire the lock first. |
| /// |
| /// # Errors |
| /// |
| /// This function will return the [`Poisoned`] error if the RwLock is poisoned. |
| /// An RwLock is poisoned whenever a writer panics while holding an exclusive |
| /// lock. `Poisoned` will only be returned if the lock would have otherwise been |
| /// acquired. |
| /// |
| /// This function will return the [`WouldBlock`] error if the RwLock could not |
| /// be acquired because it was already locked exclusively. |
| /// |
| /// [`Poisoned`]: TryLockError::Poisoned |
| /// [`WouldBlock`]: TryLockError::WouldBlock |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::sync::SgxRwLock as RwLock; |
| /// |
| /// let lock = RwLock::new(1); |
| /// |
| /// match lock.try_read() { |
| /// Ok(n) => assert_eq!(*n, 1), |
| /// Err(_) => unreachable!(), |
| /// }; |
| /// ``` |
| #[inline] |
| pub fn try_read(&self) -> TryLockResult<SgxRwLockReadGuard<'_, T>> { |
| unsafe { |
| match self.inner.try_read() { |
| Ok(_) => Ok(SgxRwLockReadGuard::new(self)?), |
| Err(_) => Err(TryLockError::WouldBlock), |
| } |
| } |
| } |
| |
| /// Locks this rwlock with exclusive write access, blocking the current |
| /// thread until it can be acquired. |
| /// |
| /// This function will not return while other writers or other readers |
| /// currently have access to the lock. |
| /// |
| /// Returns an RAII guard which will drop the write access of this rwlock |
| /// when dropped. |
| /// |
| /// # Errors |
| /// |
| /// This function will return an error if the RwLock is poisoned. An RwLock |
| /// is poisoned whenever a writer panics while holding an exclusive lock. |
| /// An error will be returned when the lock is acquired. |
| /// |
| /// # Panics |
| /// |
| /// This function might panic when called if the lock is already held by the current thread. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::sync::SgxRwLock as RwLock; |
| /// |
| /// let lock = RwLock::new(1); |
| /// |
| /// let mut n = lock.write().unwrap(); |
| /// *n = 2; |
| /// |
| /// assert!(lock.try_read().is_err()); |
| /// ``` |
| #[inline] |
| pub fn write(&self) -> LockResult<SgxRwLockWriteGuard<'_, T>> { |
| unsafe { |
| match self.inner.write() { |
| Err(libc::EAGAIN) => panic!("rwlock maximum writer count exceeded"), |
| Err(libc::EDEADLK) => panic!("rwlock write lock would result in deadlock"), |
| _ => SgxRwLockWriteGuard::new(self), |
| } |
| } |
| } |
| |
| /// Attempts to lock this rwlock with exclusive write access. |
| /// |
| /// If the lock could not be acquired at this time, then `Err` is returned. |
| /// Otherwise, an RAII guard is returned which will release the lock when |
| /// it is dropped. |
| /// |
| /// This function does not block. |
| /// |
| /// This function does not provide any guarantees with respect to the ordering |
| /// of whether contentious readers or writers will acquire the lock first. |
| /// |
| /// # Errors |
| /// |
| /// This function will return the [`Poisoned`] error if the RwLock is |
| /// poisoned. An RwLock is poisoned whenever a writer panics while holding |
| /// an exclusive lock. `Poisoned` will only be returned if the lock would have |
| /// otherwise been acquired. |
| /// |
| /// This function will return the [`WouldBlock`] error if the RwLock could not |
| /// be acquired because it was already locked exclusively. |
| /// |
| /// [`Poisoned`]: TryLockError::Poisoned |
| /// [`WouldBlock`]: TryLockError::WouldBlock |
| /// |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::sync::SgxRwLock as RwLock; |
| /// |
| /// let lock = RwLock::new(1); |
| /// |
| /// let n = lock.read().unwrap(); |
| /// assert_eq!(*n, 1); |
| /// |
| /// assert!(lock.try_write().is_err()); |
| /// ``` |
| #[inline] |
| pub fn try_write(&self) -> TryLockResult<SgxRwLockWriteGuard<'_, T>> { |
| unsafe { |
| match self.inner.try_write() { |
| Ok(_) => Ok(SgxRwLockWriteGuard::new(self)?), |
| Err(_) => Err(TryLockError::WouldBlock), |
| } |
| } |
| } |
| |
| /// Determines whether the lock is poisoned. |
| /// |
| /// If another thread is active, the lock can still become poisoned at any |
| /// time. You should not trust a `false` value for program correctness |
| /// without additional synchronization. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::sync::{Arc, SgxRwLock as RwLock}; |
| /// use std::thread; |
| /// |
| /// let lock = Arc::new(RwLock::new(0)); |
| /// let c_lock = Arc::clone(&lock); |
| /// |
| /// let _ = thread::spawn(move || { |
| /// let _lock = c_lock.write().unwrap(); |
| /// panic!(); // the lock gets poisoned |
| /// }).join(); |
| /// assert_eq!(lock.is_poisoned(), true); |
| /// ``` |
| #[inline] |
| pub fn is_poisoned(&self) -> bool { |
| self.poison.get() |
| } |
| |
| /// Consumes this `RwLock`, returning the underlying data. |
| /// |
| /// # Errors |
| /// |
| /// This function will return an error if the RwLock is poisoned. An RwLock |
| /// is poisoned whenever a writer panics while holding an exclusive lock. An |
| /// error will only be returned if the lock would have otherwise been |
| /// acquired. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::sync::SgxRwLock as RwLock; |
| /// |
| /// let lock = RwLock::new(String::new()); |
| /// { |
| /// let mut s = lock.write().unwrap(); |
| /// *s = "modified".to_owned(); |
| /// } |
| /// assert_eq!(lock.into_inner().unwrap(), "modified"); |
| /// ``` |
| pub fn into_inner(self) -> LockResult<T> |
| where |
| T: Sized, |
| { |
| let data = self.data.into_inner(); |
| poison::map_result(self.poison.borrow(), |_| data) |
| } |
| |
| /// Returns a mutable reference to the underlying data. |
| /// |
| /// Since this call borrows the `RwLock` mutably, no actual locking needs to |
| /// take place -- the mutable borrow statically guarantees no locks exist. |
| /// |
| /// # Errors |
| /// |
| /// This function will return an error if the RwLock is poisoned. An RwLock |
| /// is poisoned whenever a writer panics while holding an exclusive lock. An |
| /// error will only be returned if the lock would have otherwise been |
| /// acquired. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::sync::SgxRwLock as RwLock; |
| /// |
| /// let mut lock = RwLock::new(0); |
| /// *lock.get_mut().unwrap() = 10; |
| /// assert_eq!(*lock.read().unwrap(), 10); |
| /// ``` |
| pub fn get_mut(&mut self) -> LockResult<&mut T> { |
| let data = self.data.get_mut(); |
| poison::map_result(self.poison.borrow(), |_| data) |
| } |
| } |
| |
| impl<T: ?Sized + fmt::Debug> fmt::Debug for SgxRwLock<T> { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| let mut d = f.debug_struct("SgxRwLock"); |
| match self.try_read() { |
| Ok(guard) => { |
| d.field("data", &&*guard); |
| } |
| Err(TryLockError::Poisoned(err)) => { |
| d.field("data", &&**err.get_ref()); |
| } |
| Err(TryLockError::WouldBlock) => { |
| struct LockedPlaceholder; |
| impl fmt::Debug for LockedPlaceholder { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| f.write_str("<locked>") |
| } |
| } |
| d.field("data", &LockedPlaceholder); |
| } |
| } |
| d.field("poisoned", &self.poison.get()); |
| d.finish_non_exhaustive() |
| } |
| } |
| |
| impl<T: Default> Default for SgxRwLock<T> { |
| /// Creates a new `SgxRwLock<T>`, with the `Default` value for T. |
| fn default() -> SgxRwLock<T> { |
| SgxRwLock::new(Default::default()) |
| } |
| } |
| |
| impl<T> From<T> for SgxRwLock<T> { |
| /// Creates a new instance of an `SgxRwLock<T>` which is unlocked. |
| /// This is equivalent to [`SgxRwLock::new`]. |
| fn from(t: T) -> Self { |
| SgxRwLock::new(t) |
| } |
| } |
| |
| impl<'rwlock, T: ?Sized> SgxRwLockReadGuard<'rwlock, T> { |
| |
| unsafe fn new(lock: &'rwlock SgxRwLock<T>) -> LockResult<SgxRwLockReadGuard<'rwlock, T>> { |
| poison::map_result(lock.poison.borrow(), |_| SgxRwLockReadGuard { lock }) |
| } |
| } |
| |
| impl<'rwlock, T: ?Sized> SgxRwLockWriteGuard<'rwlock, T> { |
| unsafe fn new(lock: &'rwlock SgxRwLock<T>) -> LockResult<SgxRwLockWriteGuard<'rwlock, T>> { |
| poison::map_result(lock.poison.borrow(), |guard| SgxRwLockWriteGuard { lock, poison: guard }) |
| } |
| } |
| |
| impl<T: fmt::Debug> fmt::Debug for SgxRwLockReadGuard<'_, T> { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| (**self).fmt(f) |
| } |
| } |
| |
| impl<T: ?Sized + fmt::Display> fmt::Display for SgxRwLockReadGuard<'_, T> { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| (**self).fmt(f) |
| } |
| } |
| |
| impl<T: fmt::Debug> fmt::Debug for SgxRwLockWriteGuard<'_, T> { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| (**self).fmt(f) |
| } |
| } |
| |
| impl<T: ?Sized + fmt::Display> fmt::Display for SgxRwLockWriteGuard<'_, T> { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| (**self).fmt(f) |
| } |
| } |
| |
| impl<T: ?Sized> Deref for SgxRwLockReadGuard<'_, T> { |
| type Target = T; |
| |
| fn deref(&self) -> &T { |
| unsafe { &*self.lock.data.get() } |
| } |
| } |
| |
| impl<T: ?Sized> Deref for SgxRwLockWriteGuard<'_, T> { |
| type Target = T; |
| |
| fn deref(&self) -> &T { |
| unsafe { &*self.lock.data.get() } |
| } |
| } |
| |
| impl<T: ?Sized> DerefMut for SgxRwLockWriteGuard<'_, T> { |
| fn deref_mut(&mut self) -> &mut T { |
| unsafe { &mut *self.lock.data.get() } |
| } |
| } |
| |
| impl<T: ?Sized> Drop for SgxRwLockReadGuard<'_, T> { |
| fn drop(&mut self) { |
| let result = unsafe { |
| self.lock.inner.read_unlock() |
| }; |
| debug_assert_eq!(result, Ok(()), "Error when unlocking an SgxRwLock: {}", result.unwrap_err()); |
| } |
| } |
| |
| impl<T: ?Sized> Drop for SgxRwLockWriteGuard<'_, T> { |
| fn drop(&mut self) { |
| self.lock.poison.done(&self.poison); |
| let result = unsafe { |
| self.lock.inner.write_unlock() |
| }; |
| debug_assert_eq!(result, Ok(()), "Error when unlocking an SgxRwLock: {}", result.unwrap_err()); |
| } |
| } |