pub struct Push<'a, T> { /* private fields */ }Expand description
Queue endpoint for pushing data. Access to a Push only gives you the
right to push data and enquire about push-related properties.
See the module docs for more details.
Implementations§
source§impl<'q, T> Push<'q, T>
impl<'q, T> Push<'q, T>
sourcepub fn can_push(&self) -> bool
pub fn can_push(&self) -> bool
Checks if there is room to push at least one item. Because the Push
endpoint has exclusive control over data movement into the queue, if
this returns true, the condition will remain true until a push or
try_push happens through self, or self is dropped.
If this returns false, of course, room may appear at any time if the
other end of the queue is popped.
sourcepub fn try_reserve(&mut self) -> Option<Permit<'q, T>>
pub fn try_reserve(&mut self) -> Option<Permit<'q, T>>
Checks if there is room to push at least one item, and if so, returns a
Permit that entitles its holder to that queue slot.
If the queue is full, returns None.
This operation is slightly less useful than Push::reserve because
try_push is slightly simpler to use, and doesn’t risk data loss.
(Whereas reserve is specifically designed to fix a class of data loss
bugs.)
sourcepub async fn reserve<'s>(&'s mut self) -> Permit<'s, T>
pub async fn reserve<'s>(&'s mut self) -> Permit<'s, T>
Produces a future that resolves when there is enough space in the queue
to push one element. It resolves into a Permit, which entitles the
holder to pushing an element without needing to check or await. This
is a deliberate design choice – it means you can cancel the future
without losing the element you were trying to push.
The returned Permit borrows self exclusively. This means you must
use the Permit, or drop it, before you can request another. This
prevents a deadlock, where you wait for a second permit that will never
emerge.
The future produced by reserve also borrows self exclusively. This
means you can’t simultaneously have two futures waiting for permits from
the same Push. This wouldn’t necessarily be a bad thing, but we need
to maintain the exclusive borrow in order to pass it through to the
Permit.
Cancellation
Cancel Safety: Strict.
This does basically nothing if cancelled (it is intrinsically cancel-safe).
sourcepub fn try_push(&mut self, value: T) -> Result<(), T>
pub fn try_push(&mut self, value: T) -> Result<(), T>
Attempts to stuff value into the queue.
If there is space, ownership of value moves into the queue and this
returns Ok(()).
If there is not space, this returns Err(value) – that is, ownership
of value is handed back to you.
sourcepub async fn push(&mut self, value: T)
👎Deprecated: please use Push::reserve to avoid cancellation bugs
pub async fn push(&mut self, value: T)
Produces a future that resolves when value has been pushed into the
queue, and not before. This implies that at least one free slot must
open in the queue – either by never having been filled, or by being
freed up by a pop – for the future to resolve.
Note that the future maintains an exclusive borrow over self until
that happens – so just as there can only be one Push endpoint for a
queue at any given time, there can only be one outstanding push future
for that endpoint. This means we don’t have to define the order of
competing pushes, moving concerns about fairness to compile time.
Cancellation
Cancel Safety: Weak.
The future returned by push takes ownership of value immediately. If
the future is dropped before value makes it into the queue, value is
dropped along with it. While this behavior is well-defined and
predictable (thus my “weak cancel-safe” label) it is probably not what
you want, and so this operation is currently deprecated. Please use
Push::reserve instead.