Struct WriteHandle

pub struct WriteHandle<T, O>
where
    T: Absorb<O>,
{ /* private fields */ }

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

All operations on the underlying data should be enqueued as operations of type O using append. The effect of this operations are only exposed to readers once publish is called.

Reading through a WriteHandle

WriteHandle allows access to a ReadHandle through Deref<Target = ReadHandle>. Note that since the reads go through a ReadHandle, those reads are subject to the same visibility restrictions as reads that do not go through the WriteHandle: they only see the effects of operations prior to the last call to publish.

Implementations

impl<T, O> WriteHandle<T, O>

where T: Absorb<O>,

pub fn publish(&mut self) -> &mut Self

Publish all operations append to the log to reads.

This method needs to wait for all readers to move to the “other” copy of the data so that it can replay the operational log onto the stale copy the readers used to use. This can take some time, especially if readers are executing slow operations, or if there are many of them.

pub fn flush(&mut self)

Publish as necessary to ensure that all operations are visible to readers.

WriteHandle::publish will always wait for old readers to depart and swap the maps. This method will only do so if there are pending operations.

pub fn has_pending_operations(&self) -> bool

Returns true if there are operations in the operational log that have not yet been exposed to readers.

pub fn append(&mut self, op: O) -> &mut Self

Append the given operation to the operational log.

Its effects will not be exposed to readers until you call publish.

pub fn raw_write_handle(&mut self) -> NonNull<T>

Returns a raw pointer to the write copy of the data (the one readers are not accessing).

Note that it is only safe to mutate through this pointer if you know that there are no readers still present in this copy. This is not normally something you know; even after calling publish, readers may still be in the write copy for some time. In general, the only time you know this is okay is before the first call to publish (since no readers ever entered the write copy).

pub fn take(self) -> Taken<T, O>

Returns the backing data structure.

Makes sure that all the pending operations are applied and waits till all the read handles have departed. Then it uses Absorb::drop_first to drop one of the copies of the data and returns the other copy as a Taken smart pointer.

Methods from Deref<Target = 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.

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, O> Debug for WriteHandle<T, O>

where T: Absorb<O> + Debug, O: Debug,

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

Formats the value using the given formatter.

impl<T, O> Deref for WriteHandle<T, O>

where T: Absorb<O>,

type Target = ReadHandle<T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, O> Drop for WriteHandle<T, O>

where T: Absorb<O>,

fn drop(&mut self)

Executes the destructor for this type.

impl<T, O> Extend<O> for WriteHandle<T, O>

where T: Absorb<O>,

fn extend<I>(&mut self, ops: I)

where I: IntoIterator<Item = O>,

Add multiple operations to the operational log.

Their effects will not be exposed to readers until you call publish

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T, O> Send for WriteHandle<T, O>

where T: Absorb<O> + Send, O: Send, ReadHandle<T>: Send,