Choosing between manual setTimeout and grunt.util.spawn.timeout for Grunt task cancellation

The short answer

Neither mechanism alone guarantees cleanup of both spawned children and inline JavaScript work, and Grunt offers no built-in unified abort. The reliable approach is a cooperative cancellation pattern: a shared cancel flag set by your external signal, explicit child.kill() for every spawned process, and periodic flag checks in your JavaScript work. The two timeout mechanisms become inputs to that pattern rather than alternatives to it.

Why each mechanism falls short

These two limitations are complementary, which is why choosing between them is a false dilemma:

• grunt.util.spawn's options.timeout kills the spawned child when the deadline passes, but it governs only that child. Pure-JavaScript loops and synchronous code in the task keep running untouched.
• A manual setTimeout can call the task's done(false) callback to mark the task failed, but it terminates nothing. Spawned children keep running as orphans, and—critically—a synchronous CPU-bound loop blocks the event loop, so the timer callback cannot even fire until the loop yields.

This last point follows from JavaScript's run-to-completion model: no timer or signal can preempt synchronous code. Any cancellation of inline JS must be cooperative.

A combined cancellation pattern

Layer a small helper over both mechanisms so the task has one abort surface:

// cancel.js — shared per-task cancellation state
var children = [];
var cancelled = false;

module.exports = {
  register: function (child) { children.push(child); },
  cancel: function () {
    cancelled = true;
    children.forEach(function (c) { c.kill('SIGTERM'); });
  },
  isCancelled: function () { return cancelled; }
};

In the task, register every spawned child, chunk long-running JS so the flag is polled between chunks, and only call done() after children have exited:

grunt.registerTask('mixed', function () {
  var done = this.async();
  var cancel = require('./cancel');

  process.once('SIGUSR1', cancel.cancel); // external signal

  var child = grunt.util.spawn({ cmd: 'some-worker', args: [] }, function () {});
  cancel.register(child);
  child.on('exit', function () {
    if (cancel.isCancelled()) return done(false);
  });

  // Chunked JS work instead of one long synchronous loop
  var i = 0;
  (function step() {
    if (cancel.isCancelled()) return; // exit path handled on child exit
    if (i >= 1000) return done(true);
    doWorkChunk(i++);
    setImmediate(step); // yield so the flag check actually runs
  })();
});

Practical cautions

• Wait for exit events. Calling done() before spawned children report exit/close lets Grunt finish while orphans linger.
• Grandchildren survive SIGTERM. If your child spawns its own processes, kill the process group (spawn detached and signal the negative PID) or use a tree-kill approach.
• Move truly CPU-bound JS into a child. If the work can't be chunked, run it in a spawned process or worker so it becomes killable rather than cooperative.
• Version check. The options.timeout behavior of grunt.util.spawn is version-sensitive; confirm it against the Grunt release pinned in your project before relying on it.

Verify it

Trigger your cancel signal mid-run on a task that spawns a sleep-like child plus a chunked loop, then check the process listing: no child should remain and the task should end promptly. As a control, run once with only options.timeout and observe the inline JS continuing after the child dies—that demonstrates why the combined pattern is necessary.