node package manager


Support for queueing grunt task with using cluster.


Version Build status

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


Install with npm:

npm install grunt-q

Example code

An exsample for creating task run server.

var q = require('grunt-q')(4);
require('http').createServer(function(req, res) {
req.on('readable', function(){
  var p = JSON.parse(;
  case 'queuing':
    q.enqueue(p['grunt-task-params']).on('end', function(task_id, task) {
      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');

API - creating queues


= 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.

API - enqueue a task


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.


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)

API - confirm task state



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() )

API - confirm task progress


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){ ... });

API - dequeue and remove task



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.