pub struct BiLock<T> { /* private fields */ }
Expand description
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§
source§impl<T> BiLock<T>
impl<T> BiLock<T>
sourcepub fn new(t: T) -> (BiLock<T>, BiLock<T>)
pub fn new(t: T) -> (BiLock<T>, BiLock<T>)
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
.
sourcepub fn poll_lock(&self, cx: &mut Context<'_>) -> Poll<BiLockGuard<'_, T>>
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.
sourcepub fn lock(&self) -> BiLockAcquire<'_, T> ⓘ
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.