queue

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

Asynchronous function queue with adjustable concurrency.

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.