Queue

Queue

A class representing a queue.

Tasks added to the queue are processed in parallel (up to the concurrency limit). If all slots of the queue are occupied, the task is queued until one becomes available. When a slot is freed, the pending task with higher priority is executed. If multiple pending tasks have the same priority the first that was scheduled is executed.

Once a task is completed, its corresponding promise is terminated accordingly.

Constructor

# new Queue(concurrency)

Constructs a queue with the given concurrency

Parameters:
Name Type Description
concurrency number

The concurrency of the queue, must be an integer greater than 0 or Number.POSITIVE_INFINITY.
Source:
Example 
import { Queue, asyncRoot, sleep } from 'modern-async'

asyncRoot(async () => {
  const queue = new Queue(3) // create a queue with concurrency 3

  const array = Array.from(Array(100).keys()) // an array of 100 numbers from 0 to 99

  const promises = []
  for (const i of array) {
    promises.push(queue.exec(async () => {
      console.log(`Starting task ${i}`)
      await sleep(Math.random() * 10) // waits a random amount of time between 0ms and 10ms
      console.log(`Ending task ${i}`)
      return i;
    }))
  }
  const results = await Promise.all(promises)
  // all the scheduled tasks will perform with a maximum concurrency of 3 and log when they start and stop

  console.log(results) // will display an array with the result of the execution of each separate task
})

Members

# concurrency :number

(Read-only) The concurrency of the queue.

Type:
  • number
Source:

# pending :number

(Read-only) The number of pending tasks.

Type:
  • number
Source:

# running :number

(Read-only) The current number of tasks that are processing.

Type:
  • number
Source:

Methods

# cancelAllPending() → {number}

Cancels all pending tasks. Their corresponding promises will be rejected with a CancelledError. This method will not alter tasks that are already running.

Source:
Returns:

The number of pending tasks that were effectively cancelled.

Type
number

# (async) exec(fct, priority) → {Promise}

Puts a task at the end of the queue. When the task is executed and completes the returned promise will be terminated accordingly.

Parameters:
Name Type Default Description
fct function

An asynchronous functions representing the task. It will be executed when the queue has available slots and its result will be propagated to the promise returned by exec().
priority number 0

(Optional) The priority of the task. The higher the priority is, the sooner the task will be executed regarding the priority of other pending tasks. Defaults to 0.
Source:
Returns:

A promise that will be resolved or rejected once the task has completed. Its state will be the same than the promise returned by the call to fct.

Type
Promise

# execCancellable(fct, priority) → {Array}

Puts a task at the end of the queue. When the task is executed and completes the returned promise will be terminated accordingly.

This function returns both a promise and a cancel function. The cancel function allows to cancel the pending task, but only if it wasn't started yet. Calling the cancel function on a task that it already running has no effect. When a task is cancelled its corresponding promise will be rejected with a CancelledError.

Parameters:
Name Type Default Description
fct function

An asynchronous functions representing the task. It will be executed when the queue has available slots and its result will be propagated to the promise returned by exec().
priority number 0

(Optional) The priority of the task. The higher the priority is, the sooner the task will be executed regarding the priority of other pending tasks. Defaults to 0.
Source:
Returns:

A tuple with two parameters:

  • promise: A promise that will be resolved or rejected once the task has completed. Its state will be the same than the promise returned by the call to fct.
  • cancel: A cancel function. When called it will cancel the task if it is still pending. It has no effect is the task has already started or already terminated. When a task is cancelled its corresponding promise will be rejected with a CancelledError. If will return true if the task was effectively pending and was cancelled, false in any other case.
Type
Array