Support for queueing grunt task with using cluster.


Support for queueing grunt task with using cluster.
Ranked queue is also supported.

Install with npm:

npm install grunt-q

An exsample for creating task run server.

var q = require('grunt-q')(4);
require('http').createServer(function(reqres) {
req.on('readable', function(){
  var p = JSON.parse(;
  switch(p['request-type'])) {
  case 'queuing':
    q.enqueue(p['grunt-task-params']).on('end', function(task_idtask) {
      res.send('Task is in-queue as #' + task_id);
  case 'stat':
  case 'cancel':
    q.dequeue(p['grunt-task-id']), res.send('Task is canceled');
    res.send('No such operation');


= gruntQ([options])

options ( Number | Array | Object ) {q:1} optional
Options for creating queues.
If a Number or an Array is given, it treats as value of q

  • q (Number|Object|Array): statuses of queue(s) creating
    4 Create four queues with from rank 0 (lowest) to rank 3 (high)
    { maxQueue: 8 } Create a queue with rank 0, max queue count 8.
    [{}, { maxQueue: 4 }] A queue with rank 0, unlimited queue count and a queue with rank 1, max queue count 4 will be created.

  • maxWorker (Number|Boolean): max worker count for execute tasks. it is limited by the number of cpus. 2 two workers will be created if the number of cpus >= 2.
    true, null or undefined require('os').cpus() workers will be created.
    false not using child_process to execute task.

A grunt-q is an instance of EventEmitter.

type ready
Emits when queue(s) are ready.

q.on('ready', function(){ ... } );

type progress
Emits when progress to next task.

q.on('progress', function(task_id, task){ ... } );

type error
Emits when some error occurs.

q.on('error', function(err, [task]){ ... } );

Other events are bridged from grunt-runner as type data.
type data Emits when some error occurs.

q.on('data', function(type, args){ ... } );

See readme for more information about other events.


q.enqueue([pkg_file_path,] task_configuration [, options][, callback]);

Note that you can .enqueue() without waiting event ready.
Before ready, tasks are waiting ready automatically.

###Arguments pkg_file_path ( String ) package.json optional
Specify the task package file. It's optional because it's not required that you take a time for writing package.json.

q.enqueue('package-for-task1.json', {(some configuration)});
/* contents of package-for-task1.json:
  { "name": "task1", "taskList": ["subtask1", "subtask2"] }

or, you can write this alternatively

    pkg: {name: 'task1', taskList: ['subtask1', 'subtask2']}
  , (some configuration)



The return value value is 'pending', 'processing' or 'finished'. If you set true to the raw, you can get Task object and use the functions. (e.g. .status(), .rank() )


Check the progress of task_id.
The return value is an object { state: (task state), progress: (task progress) }
task state:= not-in-queue | error | pending | processing | finished | memory trash
task progress:=

  • not-in-queue value = undefined
  • error value = Error
  • pending value = 0
  • processing value = { finished: Array finished task names, taskList: Array task names }
  • finished value = 100
  • memory-trash value = undefined
    This case occurs when lost worker. Rare case but no way to save the task, now.

You can get data eventDrive/callback

q.progress(task_id).on('error', function(err){ ... }).on('end', function(status_value){ ... });


q.progress(task_id, function(err, status_value){ ... });



You can remove the status of a Task, release from taskmap, and saving memory use.
After that, you cannot .confirm() for the task any more, if you do that, an error will be thrown.