process: add process.gracefulExit()

doc/api/process.markdown

@@ -784,6 +784,52 @@ if (process.getuid) {
 }
 ```
 
+## process.gracefulExit(code[, timeout][, callback])
+
+* `code` {Integer} The exit code
+* `timeout` {Integer} The number of milliseconds to wait until forcing
+  the process to immediately exit. Default = `0`
+* `callback` {Function}
+
+Gracefully ends the process with the specified code. By default, if the
+callback function is not specified, the actual `process.exit(code)` will
+be scheduled to run on the next full tick of the event loop (using
+`setImmediate()`). This allows existing items in the queue to be completed
+before the call to `process.exit()`.
+
+If a `callback` is provided, it will be passed the exit `code` and an `exit`
+function that the callback should call to invoke `process.exit()` when
+ready. This `exit` function can be called with a different exit code to
+override the `code` passed in when calling `process.gracefulExit()`.
+
+Exits with code `1` on the next tick of the event loop:
+
+```js
+process.gracefulExit(1);
+```
+
+Exits with code '0' on `process.nextTick()`:
+
+```js
+process.gracefulExit(1, (code, exit) => {
+  console.log('exiting gracefully');
+  process.nextTick(() => exit(0));
+});
+```
+
+If the `timeout` argument is not an integer value greater than `0`, the process 
+will *not* exit unless the `exit` callback is not invoked. If `timeout` is
+an integer value greater than `0`, a timer will be scheduled to forcefully and 
+immediately exit the process after the given number of milliseconds.
+
+Immediately exit if the graceful exit is not completed within 10 seconds:
+
+```js
+process.gracefulExit(0, 10000, (code, exit) => {
+  // Wait, do nothing. don't call exit.
+});
+```
+
 ## process.hrtime()
 
 Returns the current high-resolution real time in a `[seconds, nanoseconds]`

lib/internal/process.js

@@ -70,6 +70,32 @@ function setupConfig(_source) {
 
 function setupKillAndExit() {
 
+  process.gracefulExit = function(code, timeout, cb) {
+    if (process._exiting || process._exitingGracefully)
+      return;
+    process._exitingGracefully = true;
+
+    function exit(newcode) {
+      if (typeof newcode === 'number')
+        code = newcode;
+      process.exit(code);
+    }
+
+    if (typeof timeout === 'function') {
+      cb = timeout;
+      timeout = 0;
+    }
+    timeout >>= 0;
+
+    if (timeout > 0)
+      setTimeout(exit, timeout);
+
+    cb = cb || ((code, done) => {
+      setImmediate(() => exit(code));
+    });
+    cb(code, exit);
+  };
+
   process.exit = function(code) {
     if (code || code === 0)
       process.exitCode = code;

test/parallel/test-process-gracefulexit-timeout.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+
+var c = 0;
+
+process.on('exit', (code) => {
+  assert.equal(c, 100);
+  assert.equal(code, 0);
+});
+
+process.gracefulExit(0, 1000, common.mustCall((code, exit) => {
+  c = 100;
+  setTimeout(() => {
+    c = 200;
+  }, 2000);
+}));

test/parallel/test-process-gracefulexit.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+
+var c = 0;
+var m = false;
+
+process.on('exit', (code) => {
+  assert.equal(c, 3);
+  assert(m);
+  assert.equal(code, 0);
+});
+
+process.gracefulExit(1, common.mustCall((code, exit) => {
+  assert.equal(code, 1);
+  assert.equal(c, 0);
+  c++; // 1
+  process.nextTick(common.mustCall(() => {
+    assert.equal(c, 1);
+    c++; // 2
+    setImmediate(common.mustCall(() => {
+      assert.equal(c, 2);
+      c++; // 3
+      exit(0);
+    }));
+  }));
+}));
+
+m = true;