2023-10-03 11:14:36 +08:00
```
____ __ _____ __ _____
/ __ `/ / / / _ \/ / / / _ \
/ /_/ / /_/ / __ / /_/ / __ /
\__, /\__,_/\___/\__,_/\___/
/_/
```
Asynchronous function queue with adjustable concurrency.
[](http://www.npmjs.org/queue)
[](https://travis-ci.org/jessetane/queue)
[](https://coveralls.io/r/jessetane/queue)
This module exports a class `Queue` that implements most of the `Array` API. Pass async functions (ones that accept a callback or return a promise) to an instance's additive array methods. Processing begins when you call `q.start()` .
## Example
`npm run example`
``` javascript
var queue = require('../')
var q = queue()
var results = []
// add jobs using the familiar Array API
q.push(function (cb) {
results.push('two')
cb()
})
q.push(
function (cb) {
results.push('four')
cb()
},
function (cb) {
results.push('five')
cb()
}
)
// jobs can accept a callback or return a promise
q.push(function () {
return new Promise(function (resolve, reject) {
results.push('one')
resolve()
})
})
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) {
if (err) throw err
console.log('all done:', results)
})
```
## Install
`npm install queue`
_Note_: You may need to install the [`events` ](https://github.com/Gozala/events ) dependency if
your environment does not have it by default (eg. browser, react-native).
## Test
`npm test`
`npm run test-browser`
## API
### `var q = queue([opts])`
Constructor. `opts` may contain inital values for:
* `q.concurrency`
* `q.timeout`
* `q.autostart`
* `q.results`
## 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 ). 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.results`
An array to set job callback arguments on.
### `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:
* [5.0 ](https://github.com/jessetane/queue/archive/5.0.0.tar.gz )
* Updated TypeScript bindings (@Codex-)
* [4.4 ](https://github.com/jessetane/queue/archive/4.4.0.tar.gz )
* Add results feature
* [4.3 ](https://github.com/jessetane/queue/archive/4.3.0.tar.gz )
* Add promise support (@kwolfy)
* [4.2 ](https://github.com/jessetane/queue/archive/4.2.0.tar.gz )
* Unref timers on end
* [4.1 ](https://github.com/jessetane/queue/archive/4.1.0.tar.gz )
* Add autostart feature
* [4.0 ](https://github.com/jessetane/queue/archive/4.0.0.tar.gz )
* Change license to MIT
* [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 [MIT License ](https://opensource.org/licenses/MIT ).
See LICENSE for full details.
