Struct futures_util::lock::BiLock

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

A type of futures-powered synchronization primitive which is a mutex between two possible owners.

This primitive is not as generic as a full-blown mutex but is sufficient for many use cases where there are only two possible owners of a resource. The implementation of BiLock can be more optimized for just the two possible owners.

Note that it’s possible to use this lock through a poll-style interface with the poll_lock method but you can also use it as a future with the lock method that consumes a BiLock and returns a future that will resolve when it’s locked.

A BiLock is typically used for “split” operations where data which serves two purposes wants to be split into two to be worked with separately. For example a TCP stream could be both a reader and a writer or a framing layer could be both a stream and a sink for messages. A BiLock enables splitting these two and then using each independently in a futures-powered fashion.

This type is only available when the bilock feature of this library is activated.

Implementations

impl<T> BiLock<T>

pub fn new(t: T) -> (Self, Self)

Creates a new BiLock protecting the provided data.

Two handles to the lock are returned, and these are the only two handles that will ever be available to the lock. These can then be sent to separate tasks to be managed there.

The data behind the bilock is considered to be pinned, which allows Pin references to locked data. However, this means that the locked value will only be available through Pin<&mut T> (not &mut T) unless T is Unpin. Similarly, reuniting the lock and extracting the inner value is only possible when T is Unpin.

pub fn poll_lock(&self, cx: &mut Context<'_>) -> Poll<BiLockGuard<'_, T>>

Attempt to acquire this lock, returning Pending if it can’t be acquired.

This function will acquire the lock in a nonblocking fashion, returning immediately if the lock is already held. If the lock is successfully acquired then Poll::Ready is returned with a value that represents the locked value (and can be used to access the protected data). The lock is unlocked when the returned BiLockGuard is dropped.

If the lock is already held then this function will return Poll::Pending. In this case the current task will also be scheduled to receive a notification when the lock would otherwise become available.

Panics

This function will panic if called outside the context of a future’s task.

pub fn lock(&self) -> BiLockAcquire<'_, T>

Perform a “blocking lock” of this lock, consuming this lock handle and returning a future to the acquired lock.

This function consumes the BiLock<T> and returns a sentinel future, BiLockAcquire<T>. The returned future will resolve to BiLockAcquired<T> which represents a locked lock similarly to BiLockGuard<T>.

Note that the returned future will never resolve to an error.

pub fn is_pair_of(&self, other: &Self) -> bool

Returns true only if the other BiLock<T> originated from the same call to BiLock::new.

pub fn reunite(self, other: Self) -> Result<T, ReuniteError<T>>

where T: Unpin,

Attempts to put the two “halves” of a BiLock<T> back together and recover the original value. Succeeds only if the two BiLock<T>s originated from the same call to BiLock::new.

Trait Implementations

impl<T: Debug> Debug for BiLock<T>

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

Formats the value using the given formatter.