Struct left_right::ReadHandle

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

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

impl<T> ReadHandle<T>

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

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

impl<T> ReadHandle<T>

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.

pub fn was_dropped(&self) -> bool

Returns true if the WriteHandle has been dropped.

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

impl<T> Clone for ReadHandle<T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for ReadHandle<T>

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

Formats the value using the given formatter.

impl<T> Drop for ReadHandle<T>

fn drop(&mut self)

Executes the destructor for this type.

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