left_right

Struct ReadHandle

Source
pub struct ReadHandle<T> { /* private fields */ }
Expand description

A read handle to a left-right guarded data structure.

To use a handle, first call enter to acquire a ReadGuard. This is similar to acquiring a Mutex, except that no exclusive lock is taken. All reads of the underlying data structure can then happen through the ReadGuard (which implements Deref<Target = T>).

Reads through a ReadHandle only see the changes up until the last time WriteHandle::publish was called. That is, even if a writer performs a number of modifications to the underlying data, those changes are not visible to reads until the writer calls publish.

ReadHandle is not Sync, which means that you cannot share a ReadHandle across many threads. This is because the coordination necessary to do so would significantly hamper the scalability of reads. If you had many reads go through one ReadHandle, they would need to coordinate among themselves for every read, which would lead to core contention and poor multi-core performance. By having ReadHandle not be Sync, you are forced to keep a ReadHandle per reader, which guarantees that you do not accidentally ruin your performance.

You can create a new, independent ReadHandle either by cloning an existing handle or by using a ReadHandleFactory. Note, however, that creating a new handle through either of these mechanisms does take a lock, and may therefore become a bottleneck if you do it frequently.

Implementations§

Source§

impl<T> ReadHandle<T>

Source

pub fn factory(&self) -> ReadHandleFactory<T>

Create a ReadHandleFactory which is Send & Sync and can be shared across threads to create additional ReadHandle instances.

Source§

impl<T> ReadHandle<T>

Source

pub fn enter(&self) -> Option<ReadGuard<'_, T>>

Take out a guarded live reference to the read copy of the T.

While the guard lives, the WriteHandle cannot proceed with a call to WriteHandle::publish, so no queued operations will become visible to any reader.

If the WriteHandle has been dropped, this function returns None.

Source

pub fn was_dropped(&self) -> bool

Returns true if the WriteHandle has been dropped.

Source

pub fn raw_handle(&self) -> Option<NonNull<T>>

Returns a raw pointer to the read copy of the data.

Note that it is only safe to read through this pointer if you know that the writer will not start writing into it. This is most likely only the case if you are calling this method from inside a method that holds &mut WriteHandle.

Casting this pointer to &mut is never safe.

Trait Implementations§

Source§

impl<T> Clone for ReadHandle<T>

Source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<T> Debug for ReadHandle<T>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl<T> Drop for ReadHandle<T>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

impl<T> Send for ReadHandle<T>
where T: Sync,

Auto Trait Implementations§

§

impl<T> !Freeze for ReadHandle<T>

§

impl<T> !RefUnwindSafe for ReadHandle<T>

§

impl<T> !Sync for ReadHandle<T>

§

impl<T> Unpin for ReadHandle<T>

§

impl<T> UnwindSafe for ReadHandle<T>
where T: RefUnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.