Skip to content

ListQueue

Jump to bottom
Eugene Lazutkin edited this page Feb 25, 2026 · 6 revisions

Description

ListQueue is a list-based queue of microtasks that extends the MicroTaskQueue class. It provides concrete implementations for managing tasks using a list data structure, allowing for efficient task scheduling, execution, pausing, and resuming.

Usually ListQueue is used as a base class for other classes that implement specific task processing logic.

Key features

  • List-Based Task Management: Uses a list data structure to store and manage microtasks.
  • Queue Control: Provides methods to pause, resume, and clear the queue.
  • Extensible Design: Designed to be extended by subclasses for specialized queue implementations.

Technical specifications

ListQueue is available as a named and default export.

const queue = new ListQueue(paused);

Constructor parameters

  • paused: A boolean indicating whether the queue should start in a paused state.

Instance properties

  • paused: A boolean indicating whether the queue is currently paused (inherited from MicroTaskQueue).
  • stopQueue: A function or null that is used to stop the queue when paused. It's set by the startQueue method. This property is used internally by pause() and resume().

Instance getters

  • isEmpty: A boolean indicating whether the queue is empty (overrides the getter from MicroTaskQueue).

Instance methods

  • pause(): Pauses the queue, preventing tasks from being executed. If the queue is running, it calls the stopQueue function to halt execution. Returns the queue instance.
  • resume(): Resumes the queue, allowing tasks to be executed again. If the queue is not empty, it calls the startQueue method to begin execution. Returns the queue instance.
  • enqueue(fn): Adds a new task to the queue, wrapping the provided function in a MicroTask instance and adding it to the list. If the queue is not paused and not already running, it starts the queue. Returns the task instance.
  • dequeue(task): Removes a specified task from the queue by removing it from the list. If the queue becomes empty and is not paused, it stops the queue. Returns the queue instance.
    • task.cancel() is called when the task is removed from the queue.
  • schedule(fn): Similar to enqueue(), but returns a task instance with a non-null promise property that resolves when the task is executed.
    • When the task is executed, the promise is resolved with the return value of fn(), or rejected with the error thrown by fn(), if any.
  • clear(): Clears all tasks from the queue by clearing the list. If the queue was not paused, it pauses it before clearing and resumes it afterward. Returns the queue instance.
    • task.cancel() is called for all tasks in the queue.
  • startQueue(): A method meant to be overridden by subclasses to implement queue execution logic. Returns a function that stops the queue or null.

fn is a function that will be executed when the task is scheduled. It will be called with queue-specific arguments, and its return value will be ignored by enqueue(), but it can be used by schedule() to resolve the task's promise.

task is an instance of the MicroTask class. It is created by the enqueue() method when a new task is added to the queue.

Usage instructions

To use the ListQueue class, import it into your project and create an instance:

import ListQueue from 'time-queues/ListQueue.js';

const queue = new ListQueue();

queue.enqueue(() => console.log('Task 1 executed'));
queue.enqueue(() => console.log('Task 2 executed'));

queue.pause(); // Pause the queue
queue.resume(); // Resume the queue
queue.clear(); // Clear all tasks

Note that ListQueue is designed to be a base class for other list-based queues. The startQueue() method should be overridden in subclasses to implement specific queue execution logic.

Troubleshooting

  • Queue Not Starting: Ensure that the startQueue() method is properly implemented in your subclass if you're extending ListQueue.
  • Tasks Not Executing: Check if the queue is paused. If it is, call resume() to start task execution.
  • Unexpected Queue Behavior: Verify that the stopQueue function is properly cleaning up resources when the queue is paused or cleared.

See Also

Clone this wiki locally