q4q v1.0.2

Q4Q - A promise based q

Installation

npm install q4q

Basic Usage

var Queue = require('q4q');

// two jobs will be run simulataneously
var queue = new Queue(2);

queue.get().then(function(value){
	console.log('job 1 started with value, ', value);
}).put(Math.PI);

queue.get().then(function(value){
	console.log('job 2 has started with value, ', value);
}).put(Math.random());

// The following two jobs will be run synchronously
// when the items currently in the queue are drained
// and will hold up the queue from starting any jobs
// untill the promise(s) are resolved

queue.then(function(results){
	// results is array of objects that represents how the
	// jobs were completed.
	// {type: 'rejection', value: 'rejection value'}
	// or {type: 'resolution', value: 'resolution value'}
	// are examples of such objects.

	console.log('all the jobs have completed!', results);
	return Math.random(); // will be passed to the next then() callback
});

queue.then(function (value){
	// value from p
	console.log(value, 'is the value recieved.');
});

NOTE:

This is a bit of an explanation about what I mean when I refer to jobs and tasks. A job is compromised of a bunch of tasks.

// a regular job
queue
	.get()
	.then(...) // this is a task
	.then(...) // another task
	.put()

// this is also a job. but it's an in-between job.
queue
	.then(...) // in-between task
	.then(...) // another in-between task

API Documentation

Constructor(concurrency)

Creates a queue.

• concurrency : a numerical value representing the maximum number of jobs that can be run simulataneously within the queue. If omitted, it defaults to 1.

This option can be later modified by the limit() instance method. Dont forget the new keyword if you don't want to mess up your global scope.

limit(new_concurrency)

Gets or sets the concurrency.

• new_concurrency: the new value for concurrency.

You can leave out the arguments if you just want to get the current concurrency.

get(template_name)

gets the queue ready for a new job.

All calls to .then() after .get() and till .put() will be piled up and that will be considered a single job.

• template_name: the name of the template function(that was defined with .template()) to pass the queue through.

put(value)

starts a job by calling the job callback with the given value.

then(onComplete, onError, onProgress)

Adds a task to a job. If it's the first task that is being added to a regular job, the first onProgress will be called with the value from put(). And then the remaining tasks will be called with the resolution value from the current task.

If get() wasn't called before calling then(), the queue will be in a suspended state until the in-between-tasks are completed. Any jobs added during the suspension will be queued for later.

var queue = new Queue(4);

// all four of these will run simultaneously
queue.get().then(...).put({});
queue.get().then(...).put({});
queue.get().then(...).put({});
queue.get().then(...).put({});

// this is the in-between job will be run when all the four completes.(ie, when the queue drains)
queue.then(...);

// the following job will be delayed till the above job is completed.
queue.get().then(...).put(20);

During in-between jobs, the first task will recieve a result array. The second onComplete will recieve the value from the first job. and so on. (It's a promise chain.)

fail(onError)

Other Aliases: catch

A shorthand for then(undefined, onError).

progress(onProgress)

A shorthand for then(undefined, onProgress)

delay(ms)

A utility function to delay the execution of the next job/task by the provided number of milliseconds and will retain the value passed.

Equivalent to:

var Q = require('q');

queue.then(function(value){
	return Q.delay(ms).thenResolve(value);
});

template(name, cb)

Creates a "template worker" with the provided name.

The worker will be called with the queue instance as the first arguments. The worker can then add tasks to it.

var Queue = require('q4q');
var queue = new Queue();
var fs = require('fs');
var Q = require('q');
var readFile = Q.denodeify(fs.readFile)

queue.template('readFile', function(q){
	q.then(function(fd){
		return readFile(fd, 'utf8');
	});
});

queue.get('readFile').then(function(contents){
	console.log('contents: ', contents);
}).put('/etc/hosts');

Pass the name of the worker to get() to pass the queue through a worker.