diff options
author | Hubert Argasinski <argasinski.hubert@gmail.com> | 2016-04-12 01:44:30 -0700 |
---|---|---|
committer | Graeme Yeates <yeatesgraeme@gmail.com> | 2016-04-12 18:46:35 -0400 |
commit | 385c0550d0822b49e2205bdfffa24106c7ef4c64 (patch) | |
tree | 62ab1510e13c6cc7bcc7e3b50237782c483642b6 /lib/queue.js | |
parent | d9675a9032ed86048620a83d3e6bc636fef370b2 (diff) | |
download | async-385c0550d0822b49e2205bdfffa24106c7ef4c64.tar.gz |
jsdoc-style documentation for `Control Flow` methods
this should be the last of the public methods requiring documentaiton
Diffstat (limited to 'lib/queue.js')
-rw-r--r-- | lib/queue.js | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/lib/queue.js b/lib/queue.js index de2ac93..683f227 100644 --- a/lib/queue.js +++ b/lib/queue.js @@ -2,6 +2,102 @@ import queue from './internal/queue'; +/** + * A queue of tasks for the worker function to complete. + * @typedef {Object} queue + * @property {Function} length - a function returning the number of items + * waiting to be processed. Invoke with (). + * @property {Function} started - a function returning whether or not any + * items have been pushed and processed by the queue. Invoke with (). + * @property {Function} running - a function returning the number of items + * currently being processed. Invoke with (). + * @property {Function} workersList - a function returning the array of items + * currently being processed. Invoke with (). + * @property {Function} idle - a function returning false if there are items + * waiting or being processed, or true if not. Invoke with (). + * @property {number} concurrency - an integer for determining how many `worker` + * functions should be run in parallel. This property can be changed after a + * `queue` is created to alter the concurrency on-the-fly. + * @property {Function} push - add a new task to the `queue`. Calls `callback` + * once the `worker` has finished processing the task. Instead of a single task, + * a `tasks` array can be submitted. The respective callback is used for every + * task in the list. Invoke with (task, [callback]), + * @property {Function} unshift - add a new task to the front of the `queue`. + * Invoke with (task, [callback]). + * @property {Function} saturated - a callback that is called when the number of + * running workers hits the `concurrency` limit, and further tasks will be + * queued. + * @property {Function} unsaturated - a callback that is called when the number + * of running workers is less than the `concurrency` & `buffer` limits, and + * further tasks will not be queued. + * @property {number} buffer - A minimum threshold buffer in order to say that + * the `queue` is `unsaturated`. + * @property {Function} empty - a callback that is called when the last item + * from the `queue` is given to a `worker`. + * @property {Function} drain - a callback that is called when the last item + * from the `queue` has returned from the `worker`. + * @property {boolean} paused - a boolean for determining whether the queue is + * in a paused state. + * @property {Function} pause - a function that pauses the processing of tasks + * until `resume()` is called. Invoke with (). + * @property {Function} resume - a function that resumes the processing of + * queued tasks when the queue is paused. Invoke with (). + * @property {Function} kill - a function that removes the `drain` callback and + * empties remaining tasks from the queue forcing it to go idle. Invoke with (). + */ + +/** + * Creates a `queue` object with the specified `concurrency`. Tasks added to the + * `queue` are processed in parallel (up to the `concurrency` limit). If all + * `worker`s are in progress, the task is queued until one becomes available. + * Once a `worker` completes a `task`, that `task`'s callback is called. + * + * @name queue + * @static + * @memberOf async + * @category Control Flow + * @param {Function} worker - An asynchronous function for processing a queued + * task, which must call its `callback(err)` argument when finished, with an + * optional `error` as an argument. If you want to handle errors from an + * individual task, pass a callback to `q.push()`. Invoked with + * (task, callback). + * @param {number} [concurrency=1] - An `integer` for determining how many + * `worker` functions should be run in parallel. If omitted, the concurrency + * defaults to `1`. If the concurrency is `0`, an error is thrown. + * @returns {queue} A queue object to manage the tasks. Callbacks can + * attached as certain properties to listen for specific events during the + * lifecycle of the queue. + * @example + * + * // create a queue object with concurrency 2 + * var q = async.queue(function(task, callback) { + * console.log('hello ' + task.name); + * callback(); + * }, 2); + * + * // assign a callback + * q.drain = function() { + * console.log('all items have been processed'); + * }; + * + * // add some items to the queue + * q.push({name: 'foo'}, function(err) { + * console.log('finished processing foo'); + * }); + * q.push({name: 'bar'}, function (err) { + * console.log('finished processing bar'); + * }); + * + * // add some items to the queue (batch-wise) + * q.push([{name: 'baz'},{name: 'bay'},{name: 'bax'}], function(err) { + * console.log('finished processing item'); + * }); + * + * // add some items to the front of the queue + * q.unshift({name: 'bar'}, function (err) { + * console.log('finished processing bar'); + * }); + */ export default function (worker, concurrency) { return queue(function (items, cb) { worker(items[0], cb); |