Struct JoinQueue 

pub struct JoinQueue<T>(/* private fields */);

Available on crate feature rt only.

A FIFO queue for of tasks spawned on a Tokio runtime.

A JoinQueue can be used to await the completion of the tasks in FIFO order. That is, if tasks are spawned in the order A, B, C, then awaiting the next completed task will always return A first, then B, then C, regardless of the order in which the tasks actually complete.

All of the tasks must have the same return type T.

When the JoinQueue is dropped, all tasks in the JoinQueue are immediately aborted.

Implementations

impl<T> JoinQueue<T>

pub const fn new() -> Self

Create a new empty JoinQueue.

pub fn with_capacity(capacity: usize) -> Self

Creates an empty JoinQueue with space for at least capacity tasks.

pub fn len(&self) -> usize

Returns the number of tasks currently in the JoinQueue.

This includes both tasks that are currently running and tasks that have completed but not yet been removed from the queue because outputting of them waits for FIFO order.

pub fn is_empty(&self) -> bool

Returns whether the JoinQueue is empty.

pub fn spawn<F>(&mut self, task: F) -> AbortHandle

where F: Future<Output = T> + Send + 'static, T: Send + 'static,

Spawn the provided task on the JoinQueue, returning an AbortHandle that can be used to remotely cancel the task.

The provided future will start running in the background immediately when this method is called, even if you don’t await anything on this JoinQueue.

Panics

This method panics if called outside of a Tokio runtime.

pub fn spawn_on<F>(&mut self, task: F, handle: &Handle) -> AbortHandle

where F: Future<Output = T> + Send + 'static, T: Send + 'static,

Spawn the provided task on the provided runtime and store it in this JoinQueue returning an AbortHandle that can be used to remotely cancel the task.

The provided future will start running in the background immediately when this method is called, even if you don’t await anything on this JoinQueue.

pub fn spawn_local<F>(&mut self, task: F) -> AbortHandle

where F: Future<Output = T> + 'static, T: 'static,

Spawn the provided task on the current LocalSet or LocalRuntime and store it in this JoinQueue, returning an AbortHandle that can be used to remotely cancel the task.

The provided future will start running in the background immediately when this method is called, even if you don’t await anything on this JoinQueue.

Panics

This method panics if it is called outside of a LocalSet or LocalRuntime.

pub fn spawn_blocking<F>(&mut self, f: F) -> AbortHandle

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Spawn the blocking code on the blocking threadpool and store it in this JoinQueue, returning an AbortHandle that can be used to remotely cancel the task.

Panics

This method panics if called outside of a Tokio runtime.

pub fn spawn_blocking_on<F>(&mut self, f: F, handle: &Handle) -> AbortHandle

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Spawn the blocking code on the blocking threadpool of the provided runtime and store it in this JoinQueue, returning an AbortHandle that can be used to remotely cancel the task.

pub async fn join_next(&mut self) -> Option<Result<T, JoinError>>

Waits until the next task in FIFO order completes and returns its output.

Returns None if the queue is empty.

Cancel Safety

This method is cancel safe. If join_next is used as the event in a tokio::select! statement and some other branch completes first, it is guaranteed that no tasks were removed from this JoinQueue.

pub async fn join_next_with_id(&mut self) -> Option<Result<(Id, T), JoinError>>

Waits until the next task in FIFO order completes and returns its output, along with the task ID of the completed task.

Returns None if the queue is empty.

When this method returns an error, then the id of the task that failed can be accessed using the JoinError::id method.

Cancel Safety

This method is cancel safe. If join_next_with_id is used as the event in a tokio::select! statement and some other branch completes first, it is guaranteed that no tasks were removed from this JoinQueue.

pub fn try_join_next(&mut self) -> Option<Result<T, JoinError>>

Tries to join the next task in FIFO order if it has completed.

Returns None if the queue is empty or if the next task is not yet ready.

pub fn try_join_next_with_id(&mut self) -> Option<Result<(Id, T), JoinError>>

Tries to join the next task in FIFO order if it has completed and return its output, along with its task ID.

Returns None if the queue is empty or if the next task is not yet ready.

When this method returns an error, then the id of the task that failed can be accessed using the JoinError::id method.

pub async fn shutdown(&mut self)

Aborts all tasks and waits for them to finish shutting down.

Calling this method is equivalent to calling abort_all and then calling join_next in a loop until it returns None.

This method ignores any panics in the tasks shutting down. When this call returns, the JoinQueue will be empty.

pub async fn join_all(self) -> Vec<T>

Awaits the completion of all tasks in this JoinQueue, returning a vector of their results.

The results will be stored in the order they were spawned, not the order they completed. This is a convenience method that is equivalent to calling join_next in a loop. If any tasks on the JoinQueue fail with an JoinError, then this call to join_all will panic and all remaining tasks on the JoinQueue are cancelled. To handle errors in any other way, manually call join_next in a loop.

Cancel Safety

This method is not cancel safe as it calls join_next in a loop. If you need cancel safety, manually call join_next in a loop with Vec accumulator.

pub fn abort_all(&mut self)

Aborts all tasks on this JoinQueue.

This does not remove the tasks from the JoinQueue. To wait for the tasks to complete cancellation, you should call join_next in a loop until the JoinQueue is empty.

pub fn detach_all(&mut self)

Removes all tasks from this JoinQueue without aborting them.

The tasks removed by this call will continue to run in the background even if the JoinQueue is dropped.

pub fn poll_join_next( &mut self, cx: &mut Context<'_>, ) -> Poll<Option<Result<T, JoinError>>>

Polls for the next task in JoinQueue to complete.

If this returns Poll::Ready(Some(_)), then the task that completed is removed from the queue.

When the method returns Poll::Pending, the Waker in the provided Context is scheduled to receive a wakeup when a task in the JoinQueue completes. Note that on multiple calls to poll_join_next, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup.

Returns

This function returns:

• Poll::Pending if the JoinQueue is not empty but there is no task whose output is available right now.
• Poll::Ready(Some(Ok(value))) if the next task in this JoinQueue has completed. The value is the return value that task.
• Poll::Ready(Some(Err(err))) if the next task in this JoinQueue has panicked or been aborted. The err is the JoinError from the panicked/aborted task.
• Poll::Ready(None) if the JoinQueue is empty.

pub fn poll_join_next_with_id( &mut self, cx: &mut Context<'_>, ) -> Poll<Option<Result<(Id, T), JoinError>>>

Polls for the next task in JoinQueue to complete.

If this returns Poll::Ready(Some(_)), then the task that completed is removed from the queue.

When the method returns Poll::Pending, the Waker in the provided Context is scheduled to receive a wakeup when a task in the JoinQueue completes. Note that on multiple calls to poll_join_next, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup.

Returns

This function returns:

• Poll::Pending if the JoinQueue is not empty but there is no task whose output is available right now.
• Poll::Ready(Some(Ok((id, value)))) if the next task in this JoinQueue has completed. The value is the return value that task, and id is its task ID.
• Poll::Ready(Some(Err(err))) if the next task in this JoinQueue has panicked or been aborted. The err is the JoinError from the panicked/aborted task.
• Poll::Ready(None) if the JoinQueue is empty.

Trait Implementations

impl<T: Debug> Debug for JoinQueue<T>

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

Formats the value using the given formatter.

impl<T> Default for JoinQueue<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T, F> FromIterator<F> for JoinQueue<T>

where F: Future<Output = T> + Send + 'static, T: Send + 'static,

Collect an iterator of futures into a JoinQueue.

This is equivalent to calling JoinQueue::spawn on each element of the iterator.

fn from_iter<I: IntoIterator<Item = F>>(iter: I) -> Self

Creates a value from an iterator.