mercurial-scm/hg: comparison rust/pyo3-sharedref/src/lib.rs

equal deleted inserted replaced

-:d85514a88706
+:d1e304025b90
 ///     }
 ///
 ///     fn add(slf: &Bound<'_, Self>, i: i32) -> PyResult<()> {
 ///         let rust_set = &slf.borrow().rust_set;
 ///         let shared_ref = unsafe { rust_set.borrow_with_owner(slf) };
-///         let mut set_ref = shared_ref.borrow_mut();
+///         let mut set_ref = shared_ref.write();
 ///         set_ref.insert(i);
 ///         Ok(())
 ///     }
 /// }
 ///
 state: &'py PySharedState,
 data: &'py RwLock<T>, // TODO perhaps this needs Pin
 }
 impl<'py, T: ?Sized> PySharedRef<'py, T> {
-/// Immutably borrows the wrapped value.
+/// Take the lock on the wrapped value for read-only operations.
 ///
 /// # Panics
 ///
-/// Panics if the value is currently mutably borrowed.
+/// Panics if the lock is currently held for write operations.
-pub fn borrow(&self) -> RwLockReadGuard<'py, T> {
+pub fn read(&self) -> RwLockReadGuard<'py, T> {
-self.try_borrow().expect("already mutably borrowed")
+self.try_read().expect("already mutably borrowed")
 }
 /// Immutably borrows the wrapped value, returning an error if the value
 /// is currently mutably borrowed.
-pub fn try_borrow(&self) -> TryLockResult<RwLockReadGuard<'py, T>> {
+pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<'py, T>> {
 // state isn't involved since
-// - data.try_borrow() would fail if self is mutably borrowed,
+// - data.try_read() would fail if self is mutably borrowed,
-// - and data.try_borrow_mut() would fail while self is borrowed.
+// - and data.try_write() would fail while self is borrowed.
 self.data.try_read()
 }
-/// Mutably borrows the wrapped value.
+/// Take the lock on the wrapped value for write operations.
 ///
 /// Any existing leaked references will be invalidated.
 ///
 /// # Panics
 ///
-/// Panics if the value is currently borrowed.
+/// Panics if the lock is currently held.
-pub fn borrow_mut(&self) -> RwLockWriteGuard<'py, T> {
+pub fn write(&self) -> RwLockWriteGuard<'py, T> {
-self.try_borrow_mut().expect("already borrowed")
+self.try_write().expect("already borrowed")
 }
 /// Mutably borrows the wrapped value, returning an error if the value
 /// is currently borrowed.
-pub fn try_borrow_mut(&self) -> TryLockResult<RwLockWriteGuard<'py, T>> {
+pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<'py, T>> {
 // the value may be immutably borrowed through UnsafePyLeaked
 if self.state.current_borrow_count(self.py()) > 0 {
 // propagate borrow-by-leaked state to data to get BorrowMutError
 let _dummy = self.data.read();
 let _unused = self.data.try_write()?;
 pub fn try_leak_immutable(
 &self,
 ) -> Result<UnsafePyLeaked<&'static T>, TryLeakError> {
 // make sure self.data isn't mutably borrowed; otherwise the
 // generation number wouldn't be trusted.
-let data_ref = self.try_borrow()?;
+let data_ref = self.try_read()?;
 // keep reference to the owner so the data and state are alive,
-// but the data pointer can be invalidated by borrow_mut().
+// but the data pointer can be invalidated by write().
 // the state wouldn't since it is immutable.
 let state_ptr: *const PySharedState = self.state;
 let data_ptr: *const T = &*data_ref;
 Ok(UnsafePyLeaked::<&'static T> {
 owner: self.owner.clone().unbind(),
 /// `PySharedState` is owned by `PySharedRefCell`, and is shared across its
 /// derived references. The consistency of these references are guaranteed
 /// as follows:
 ///
 /// - The immutability of `PycCass` object fields. Any mutation of
-///   [`PySharedRefCell`] is allowed only through its `borrow_mut()`.
+///   [`PySharedRefCell`] is allowed only through its `write()`.
 /// - The `py: Python<'_>` token, which makes sure that any data access is
 ///   synchronized by the GIL.
 /// - The underlying `RefCell`, which prevents `PySharedRefCell` value from
 ///   being directly borrowed or leaked while it is mutably borrowed.
 /// - The `borrow_count`, which is the number of references borrowed from
 ///   `UnsafePyLeaked`. Just like `RefCell`, mutation is prohibited while
 ///   `UnsafePyLeaked` is borrowed.
-/// - The `generation` counter, which increments on `borrow_mut()`.
+/// - The `generation` counter, which increments on `write()`. `UnsafePyLeaked`
-///   `UnsafePyLeaked` reference is valid only if the `current_generation()`
+///   reference is valid only if the `current_generation()` equals to the
-///   equals to the `generation` at the time of `leak_immutable()`.
+///   `generation` at the time of `leak_immutable()`.
 #[derive(Debug)]
 struct PySharedState {
 // The counter variable could be Cell<usize> since any operation on
 // PySharedState is synchronized by the GIL, but being "atomic" makes
 // PySharedState inherently Sync. The ordering requirement doesn't

changeset 52609	d1e304025b90
parent 52608	d85514a88706
child 52610	c25d345f5aa5