Crate operation_queue 

This crate contains the queueing logic for asynchronous operations.

It also contains helpers for synchronizing operations such as error handling across futures, in the line_token module.

The operation queue

The queueing of operations is handled by the OperationQueue struct. It runs a given number of parallel runners, to which it dispatches operations on a “first come, first served” basis.

An operation is a data structure that implements the QueuedOperation trait, and is started by the queue calling its perform method. Because this method is asynchronous, thus breaking dyn compatibility, another trait that is dyn-compatible (ErasedQueuedOperation) is used by the queue. However, ErasedQueuedOperation is implemented by any type that implements QueuedOperation, so consumers usually don’t need to bother with it.

OperationQueue is runtime-agnostic, meaning it is not designed to work only with a specific asynchronous runtime. However, it still needs to spawn a task for each of its runners. This is why OperationQueue::new takes a function as its sole argument, which is given the future for a runner’s loop. For example, creating a new queue with the tokio crate could look like this:

let queue = OperationQueue::new(|fut| {
    let _ = tokio::task::spawn_local(fut);
});

The queue is started by OperationQueue::start, and stopped by OperationQueue::stop. When starting the queue, the number of runners provided as the function’s argument are created and started. A runner is a small stateful struct with an infinite asynchronous loop. Upon stopping, the queue terminates and clears all current runners. Note that, once stopped, a queue cannot be started again.

Queuing operations is done with OperationQueue::enqueue. The operation is pushed to the back of the queue, and will be performed whenenever the previous operations have also been performed and a runner becomes available.

Multithreading

In order to maintain compatibility with the current Thunderbird code-base, neither the operation queue’s runner, nor the synchronization helpers in the line_token module, can be sent between threads. This is something we plan to address in the future.

Modules

line_token

Helpers for synchronizing operations (e.g. error handling) across futures.

Structs

OperationQueue

A queue that performs asynchronous operations in order.

Enums

Error

An error returned from the queue.

Traits

ErasedQueuedOperation

A dyn-compatible version of QueuedOperation. It is implemented for all types that implement QueuedOperation.

QueuedOperation

An operation that can be added to an OperationQueue.