Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

docs

  • Loading branch information...
commit 1b65662a0bf2abff123a10affdcc72d566d534ff 1 parent 28558be
@logicalparadox logicalparadox authored
Showing with 232 additions and 19 deletions.
  1. +152 −5 README.md
  2. +80 −14 lib/queue.js
View
157 README.md
@@ -1,22 +1,169 @@
-# breeze-queue
+# breeze-queue [![Build Status](https://secure.travis-ci.org/qualiancy/breeze-queue.png?branch=master)](https://travis-ci.org/qualiancy/breeze-queue)
> Throttled parallel function invocation.
-### Installation
+## Installation
-#### Node.js
+### Node.js
`breeze-queue` is available on [npm](http://npmjs.org).
$ npm install breeze-queue
-#### Component
+### Component
`breeze-queue` is available as a [component](https://github.com/component/component).
$ component install qualiancy/breeze-queue
-#### License
+## Usage
+
+### Queue (iterator, concurrency)
+
+* **@param** _{Function}_ iterator
+* **@param** _{Number}_ concurrency (defaults to 10)
+* **@return** _{Object}_ queue api
+
+The queue mechanism allows for a any number of
+data objects to be processed by an iterator
+when they become available. The queue will processes
+items in parellel, up to a given concurrently value,
+then will wait until an item has finished until
+beginning to process the next. The items queued
+can have a callback executed when it has completed
+its iterator.
+
+In addition, a queue may also have
+functions attached to listen for specific events.
+On such event is an error. Should any item in the queue
+fail to process and provide an error to it's `next`
+callback, no further items will be processed.
+
+```js
+var Queue = require('breeze-queue');
+
+var queue = Queue(function (obj, next) {
+ setTimeout(next, 10);
+}, 5);
+```
+
+
+### .length
+
+* **@return** _{Number}_ count of queued items
+
+Property indicating the number of items current
+in the queue. An item is removed from this list
+prior to being processed.
+
+
+### .push (items[, callback[, autostart]])
+
+* **@param** _{Array}_ item or items to be added to the queue
+* **@param** _{Function}_ callback for completion of each item
+* **@param** _{Boolean}_ autostart process (defaults to false)
+
+You can push an item or an array of items into
+the queue for processing. The callback will be
+called for the completion of each item if the queue
+has not entered into an error state. A `autostart`
+boolean my also be provided if you wish to start
+processing the queue with this push of items. If
+no pushes provide the autostart, then the queue
+must be started manually with `.process()`.
+
+Note that if the queue has already been started but
+has been drained of items, it will not start again
+with another push unless the `autostart` toggle is present.
+
+```js
+// single item
+queue.push({ hello: 'universe' });
+
+// multiple items
+queue.push([
+ { hello: 'world' }
+ , { hello: 'universe' }
+]);
+
+// notify callback
+queue.push({ hello: 'universe' }, notify);
+
+// autostart
+queue.push({ hello: 'universe' }, true);
+
+// notify + autostart
+queue.push({ hello: 'univeerse' }, notify, true);
+```
+
+
+### .process ()
+
+
+Begin the queue processing cycle. Has no impact if
+the queue is already processing.
+
+```js
+queue.process();
+```
+
+
+### .onerror
+
+* **@cb** {Error} object that was passed as error during iteration
+
+Setting this to a function will provide a listener
+should an error occur. It will not be executed otherwise.
+
+```js
+queue.onerror = function (err) {
+ console.error(err.message);
+};
+```
+
+
+### .saturated
+
+
+This listener will be executed when the number of
+queued items exceeds the current concurrency value.
+This will be executed directly after the push of
+said items.
+
+```js
+queue.saturated = function () {
+ console.log('the queue is saturated');
+};
+```
+
+
+### .empty
+
+
+This listener will be executed when the queue is empty.
+In other words, prior to the last item in the queue
+being processed.
+
+```js
+queue.empty = function () {
+ console.log('the queue is on the last item');
+};
+```
+
+
+### .drain
+
+
+This listener will be executed when all queued
+items have been executed through the iterator.
+
+```js
+queue.drain = function () {
+ console.log('the queue has processed all tiems');
+};
+```
+
+## License
(The MIT License)
View
94 lib/queue.js
@@ -3,7 +3,7 @@ var nextTick = require('breeze-nexttick');
var noop = function () {};
/**
- * ### queue (iterator, concurrency)
+ * ### Queue (iterator, concurrency)
*
* The queue mechanism allows for a any number of
* data objects to be processed by an iterator
@@ -12,15 +12,25 @@ var noop = function () {};
* then will wait until an item has finished until
* beginning to process the next. The items queued
* can have a callback executed when it has completed
- * its iterator. In addition, a queue may also have
+ * its iterator.
+ *
+ * In addition, a queue may also have
* functions attached to listen for specific events.
* On such event is an error. Should any item in the queue
- * fail to process and provide an error to it's `done`
+ * fail to process and provide an error to it's `next`
* callback, no further items will be processed.
*
+ * ```js
+ * var Queue = require('breeze-queue');
+ *
+ * var queue = Queue(function (obj, next) {
+ * setTimeout(next, 10);
+ * }, 5);
+ * ```
+ *
* @param {Function} iterator
* @param {Number} concurrency (defaults to 10)
- * @returns {Object} queue
+ * @return {Object} queue api
* @name queue
* @api public
*/
@@ -50,13 +60,13 @@ function Queue (iterator, concurrency) {
}
/**
- * #### .length
+ * ### .length
*
* Property indicating the number of items current
* in the queue. An item is removed from this list
* prior to being processed.
*
- * @returns {Number} count of queued items
+ * @return {Number} count of queued items
* @api public
*/
@@ -67,7 +77,7 @@ Object.defineProperty(Queue.prototype, 'length',
});
/**
- * #### .push (items[, callback[, autostart]])
+ * ### .push (items[, callback[, autostart]])
*
* You can push an item or an array of items into
* the queue for processing. The callback will be
@@ -82,6 +92,26 @@ Object.defineProperty(Queue.prototype, 'length',
* has been drained of items, it will not start again
* with another push unless the `autostart` toggle is present.
*
+ * ```js
+ * // single item
+ * queue.push({ hello: 'universe' });
+ *
+ * // multiple items
+ * queue.push([
+ * { hello: 'world' }
+ * , { hello: 'universe' }
+ * ]);
+ *
+ * // notify callback
+ * queue.push({ hello: 'universe' }, notify);
+ *
+ * // autostart
+ * queue.push({ hello: 'universe' }, true);
+ *
+ * // notify + autostart
+ * queue.push({ hello: 'univeerse' }, notify, true);
+ * ```
+ *
* @param {Array} item or items to be added to the queue
* @param {Function} callback for completion of each item
* @param {Boolean} autostart process (defaults to false)
@@ -93,20 +123,29 @@ Queue.prototype.push = function (items, cb, start) {
if ('boolean' === typeof cb) start = cb, cb = noop;
if (!Array.isArray(items)) items = [ items ];
cb = cb || noop;
+
var cc = this._concurrency
, sat = this.saturated;
+
for (var i = 0, l = items.length; i < l; i ++) {
var task = items[i];
this._tasks.push({ task: task , cb: cb });
if (sat && this._tasks.length === cc) sat();
if (start) nextTick(this.process.bind(this));
}
+
+ return this;
};
/**
- * #### .process ()
+ * ### .process ()
+ *
+ * Begin the queue processing cycle. Has no impact if
+ * the queue is already processing.
*
- * Begin the queue processing cycle.
+ * ```js
+ * queue.process();
+ * ```
*
* @name process
* @api public
@@ -116,6 +155,7 @@ Queue.prototype.process = function () {
var self = this
, cc = this._concurrency
, iterator = this._iterator
+
if (this.workers < cc && this.length && !this._err) {
var task = this._tasks.shift();
if (this.empty && !this.length) this.empty();
@@ -132,14 +172,22 @@ Queue.prototype.process = function () {
});
this.process();
}
+
+ return this;
};
/**
- * #### .onerror
+ * ### .onerror
*
* Setting this to a function will provide a listener
* should an error occur. It will not be executed otherwise.
*
+ * ```js
+ * queue.onerror = function (err) {
+ * console.error(err.message);
+ * };
+ * ```
+ *
* @default null
* @expected {Function} on error callback
* @cb {Error} object that was passed as error during iteration
@@ -149,12 +197,18 @@ Queue.prototype.process = function () {
Queue.prototype.onerror = null;
/**
- * #### .saturated
+ * ### .saturated
*
* This listener will be executed when the number of
* queued items exceeds the current concurrency value.
* This will be executed directly after the push of
- * said items
+ * said items.
+ *
+ * ```js
+ * queue.saturated = function () {
+ * console.log('the queue is saturated');
+ * };
+ * ```
*
* @default null
* @expected {Function}
@@ -164,12 +218,18 @@ Queue.prototype.onerror = null;
Queue.prototype.saturated = null;
/**
- * #### .empty
+ * ### .empty
*
* This listener will be executed when the queue is empty.
* In other words, prior to the last item in the queue
* being processed.
*
+ * ```js
+ * queue.empty = function () {
+ * console.log('the queue is on the last item');
+ * };
+ * ```
+ *
* @default null
* @expected {Function}
* @api public
@@ -178,11 +238,17 @@ Queue.prototype.saturated = null;
Queue.prototype.empty = null;
/**
- * #### .drain
+ * ### .drain
*
* This listener will be executed when all queued
* items have been executed through the iterator.
*
+ * ```js
+ * queue.drain = function () {
+ * console.log('the queue has processed all tiems');
+ * };
+ * ```
+ *
* @default null
* @expected {Function}
* @api public
Please sign in to comment.
Something went wrong with that request. Please try again.