node package manager

queue

   ____  __  _____  __  _____
  / __ `/ / / / _ \/ / / / _ \
 / /_/ / /_/ /  __/ /_/ /  __/
 \__, /\__,_/\___/\__,_/\___/
   /_/

Asynchronous function queue with adjustable concurrency.

npm tests coverage

Why

Async is a big library offering various approaches to dealing with asynchrony; queue is a small library offering a single, flexible abstraction.

How

This module exports a class Queue that implements most of the Array API. Pass async functions (ones that accept a callback) to an instance's additive array methods. Processing begins when you call q.start().

Install

npm install queue

Test

npm test npm run test-browser

Example

npm run example

var queue = require('queue');
 
var q = queue();
var results = [];
 
// add jobs using the Array API 
 
q.push(function(cb) {
  results.push('two');
  cb();
});
 
q.push(
  function(cb) {
    results.push('four');
    cb();
  },
  function(cb) {
    results.push('five');
    cb();
  }
);
 
q.unshift(function(cb) {
  results.push('one');
  cb();
});
 
q.splice(2, 0, function(cb) {
  results.push('three');
  cb();
});
 
// use the timeout feature to deal with jobs that 
// take too long or forget to execute a callback 
 
q.timeout = 100;
 
q.on('timeout', function(next, job) {
  console.log('job timed out:', job.toString().replace(/\n/g, ''));
  next();
});
 
q.push(function(cb) {
  setTimeout(function() {
    console.log('slow job finished');
    cb();
  }, 200);
});
 
q.push(function(cb) {
  console.log('forgot to execute callback');
});
 
// get notified when jobs complete 
 
q.on('success', function(result, job) {
  console.log('job finished processing:', job.toString().replace(/\n/g, ''));
});
 
// begin processing, get notified on end / failure 
 
q.start(function(err) {
  console.log('all done:', results);
});

Require

var queue = require('queue')

Constructor

var q = queue([opts])

Where opts may contain inital values for:

  • q.concurrency
  • q.timeout
  • q.autostart

Instance methods

q.start([cb])

cb, if passed, will be called when the queue empties or when an error occurs.

q.stop()

Stops the queue. can be resumed with q.start().

q.end([err])

Stop and empty the queue immediately.

Instance methods mixed in from Array

Mozilla has docs on how these methods work here. Note that slice does not copy the queue. #### q.push(element1, ..., elementN) #### q.unshift(element1, ..., elementN) #### q.splice(index , howMany[, element1[, ...[, elementN]]]) #### q.pop() #### q.shift() #### q.slice(begin[, end]) #### q.reverse() #### q.indexOf(searchElement[, fromIndex]) #### q.lastIndexOf(searchElement[, fromIndex])

Properties

q.concurrency

Max number of jobs the queue should process concurrently, defaults to Infinity.

q.timeout

Milliseconds to wait for a job to execute its callback.

q.autostart

Ensures the queue is always running if jobs are available. Useful in situations where you are using a queue only for concurrency control.

q.length

Jobs pending + jobs to process (readonly).

Events

q.emit('success', result, job)

After a job executes its callback.

q.emit('error', err, job)

After a job passes an error to its callback.

q.emit('timeout', continue, job)

After q.timeout milliseconds have elapsed and a job has not executed its callback.

q.emit('end'[, err])

After all jobs have been processed

Releases

The latest stable release is published to npm. Abbreviated changelog below:

  • 4.2
  • Unref timers on end
  • 4.1
  • Add autostart feature
  • 4.0
  • Change license to MIT
  • 3.1.x
  • Add .npmignore
  • 3.0.x
  • Change the default concurrency to Infinity
  • Allow q.start() to accept an optional callback executed on q.emit('end')
  • 2.x
  • Major api changes / not backwards compatible with 1.x
  • 1.x
  • Early prototype

License

Copyright © 2014 Jesse Tane jesse.tane@gmail.com

This work is free. You can redistribute it and/or modify it under the terms of the MIT License. See LICENSE for full details.