170 lines
4.7 KiB
Markdown
170 lines
4.7 KiB
Markdown
```
|
|
____ __ _____ __ _____
|
|
/ __ `/ / / / _ \/ / / / _ \
|
|
/ /_/ / /_/ / __/ /_/ / __/
|
|
\__, /\__,_/\___/\__,_/\___/
|
|
/_/
|
|
```
|
|
Asynchronous function queue with adjustable concurrency.
|
|
|
|
[](http://www.npmjs.org/queue)
|
|
[](https://travis-ci.org/jessetane/queue)
|
|
[](https://coveralls.io/r/jessetane/queue)
|
|
|
|
## Why
|
|
[Async](https://github.com/caolan/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`
|
|
``` javascript
|
|
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`
|
|
|
|
## 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).
|
|
#### `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.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](http://npmjs.org/queue). Abbreviated changelog below:
|
|
* [3.1.x](https://github.com/jessetane/queue/archive/3.0.6.tar.gz)
|
|
* Add .npmignore
|
|
* [3.0.x](https://github.com/jessetane/queue/archive/3.0.6.tar.gz)
|
|
* Change the default concurrency to `Infinity`
|
|
* Allow `q.start()` to accept an optional callback executed on `q.emit('end')`
|
|
* [2.x](https://github.com/jessetane/queue/archive/2.2.0.tar.gz)
|
|
* Major api changes / not backwards compatible with 1.x
|
|
* [1.x](https://github.com/jessetane/queue/archive/1.0.2.tar.gz)
|
|
* 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 [WTFPL](http://www.wtfpl.net/txt/copying).
|
|
|
|
No Warranty. The Software is provided "as is" without warranty of any kind, either express or implied, including without limitation any implied warranties of condition, uninterrupted use, merchantability, fitness for a particular purpose, or non-infringement.
|