Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface IAsyncQueue<T>

Asynchronous FIFO queue with a Promise-driven dequeue operation.

All element values are allowed, especially falsy ones, e.g. false, 0, undefined, null, [], {} are all valid elements which can be queued and dequeued.

The {@link AsyncIterable} interface iterates the queue's (future) contents ad infinitum. Users are advised to signal the end by manual insertion of a special value (a so-called poison pill):

const queue = new AsyncQueue<string|null>();
file.on('data', (data) => queue.queue(data));
file.on('close', () => queue.queue(null));

for await (const data of queue) {
  if (data === null) {
    break;
  }
  // Otherwise, process data
}

Type parameters

  • T

Hierarchy

  • AsyncIterable<T>
    • IAsyncQueue

Implemented by

Index

Methods

Methods

[Symbol.asyncIterator]

  • [Symbol.asyncIterator](): AsyncIterator<T, any, undefined>

  • Returns AsyncIterator<T, any, undefined>

dequeue

  • dequeue(): Promise<T>

  • Dequeue an element, waiting for data to be available if necessary.

    Returns Promise<T>

    A promise which is fulfilled when an element (as queued by queue()) becomes available. If multiple dequeus() are issued sequentially, it is implementation-defined whether they are fulfilled in the same order or not. However, the data is still retrieved in FIFO fashion, meaning the first fulfilled promise gets the first element, the second fulfilled the second one and so forth.

poll

  • poll(): T

  • Dequeue an element if available or throw an exception otherwise.

    throws

    A NoElementError exception if the queue is empty at the time of the call.

    Returns T

    The first element of the queue.

queue

  • queue(data: T): void

queueAll

  • queueAll(iterable: Iterable<T>): void

  • Queue all elements of an iterable, e.g. an array or a generator function.

    example

    queue.queueAll(['myArray', 'of', 'strings'])

    example

    If one has a generator function f: function *f(): Iterable<string> { ... } then you can call queue.queueAll(f()).

    Parameters

    • iterable: Iterable<T>

    Returns void

queueAllAsync

  • queueAllAsync(iterable: AsyncIterable<T>): Promise<void>

  • Queue all elements of an asynchronous iterable, e.g. an asynchronous generator functions.

    example

    Using an asynchronous generator function:

    async function *f(): AsyncIterable<string> {
  yield* ['Array', 'of', 'strings'];
}

const previousSize = queue.size();
queue.queueAllAsync(f());
// ^ We do not await the queueing!
// Therefore: queue.size() === previousSize here!
// This is indeed guaranteed by JS' execution model. There is
// no way queueAllAsync could have queried an element from f()
// asynchronously using a promise before this code gives up
// the "CPU power" by await or yield.

await queue.dequeue(); // 'Array'
await queue.dequeue(); // 'of'
await queue.dequeue(); // 'strings'

// queue.size() === 0 and queue.dequeue() would block
// ad infinitum

await queue.queueAllAsync(f());
// We now await the queueing!
// Therefore: queue.size() === 3 here!
    example

    AsyncQueue instances are also asynchronous iterables, meaning that you can stack multiple queues together:

    const backgroundQueue: IAsyncQueue<string> = new AsyncQueue();
const foregroundQueue: IAsyncQueue<string> = new AsyncQueue();

setTimeout(() => backgroundQueue.queue('Hello World!'), 100);

foregroundQueue.queueAllAsync(backgroundQueue);
const retrievedString = await foregroundQueue.dequeue();

// retrievedString === 'Hello World!'

    Parameters

    • iterable: AsyncIterable<T>

    Returns Promise<void>

size

  • size(): number

  • Return the current size at the moment of the call.

    Even though code like

    if (queue.size() >= 1) {
  const element = queue.poll();
}

    is technically not wrong (due to JS' execution model), users are advised to avoid this pattern. Instead, users are encouraged to

    • in cases where waiting for a promise is impossible, to use poll and catch the exception,
    • or to use dequeue with JS' await or queue.dequeue().then(...).

    Returns number

Generated using TypeDoc