Necessary Pigeonholing Mechanism
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



    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.


    npm i grunt-q

    Downloadslast 7 days







    last publish


    • avatar