process: add 'warning' event and process.emitWarning()

In several places throughout the code we write directly to stderr
to report warnings (deprecation, possible eventemitter memory leak).
The current design of simply dumping the text to stderr is less
than ideal. This PR introduces a new "process warnings" mechanism
that emits 'warning' events on the global process object. These are
invoked with a `warning` argument whose value is an Error object.

By default, these warnings will be printed to stderr. This can be
suppressed using the `--no-warnings` and `--no-deprecation` command
line flags. For warnings, the 'warning' event will still be emitted
by the process, allowing applications to handle the warnings in custom
ways. The existing `--no-deprecation` flag will continue to supress
all deprecation output generated by the core lib.

The `--trace-warnings` command line flag will tell Node.js to print
the full stack trace of warnings as part of the default handling.

The existing `--no-deprecation`, `--throw-deprecation` and
`--trace-deprecation` flags continue to work as they currently do,
but the exact output of the warning message is modified to occur
on process.nextTick().

The stack trace for the warnings and deprecations preserve and point
to the correct call site.

A new `process.emitWarning()` API is provided to permit userland
to emit warnings and deprecations using the same consistent
mechanism.

Test cases and documentation are included.

PR-URL: https://github.com/nodejs/node/pull/4782
Reviewed-By: Rod Vagg <rod@vagg.org>
Reviewed-By: Wyatt Preul <wpreul@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

4 files changed, 62 insertions, 30 deletions

diff --git a/lib/events.js b/lib/events.js
index 7103ec393f..a67de552f1 100644
--- a/lib/events.js
+++ b/lib/events.js
@@ -1,6 +1,5 @@
 'use strict';
 
-var internalUtil;
 var domain;
 
 function EventEmitter() {
@@ -246,14 +245,9 @@ EventEmitter.prototype.addListener = function addListener(type, listener) {
       m = $getMaxListeners(this);
       if (m && m > 0 && existing.length > m) {
         existing.warned = true;
-        if (!internalUtil)
-          internalUtil = require('internal/util');
-
-        internalUtil.error('warning: possible EventEmitter memory ' +
-                           'leak detected. %d %s listeners added. ' +
-                           'Use emitter.setMaxListeners() to increase limit.',
-                           existing.length, type);
-        console.trace();
+        process.emitWarning('Possible EventEmitter memory leak detected. ' +
+                            `${existing.length} ${type} listeners added. ` +
+                            'Use emitter.setMaxListeners() to increase limit');
       }
     }
   }
diff --git a/lib/internal/bootstrap_node.js b/lib/internal/bootstrap_node.js
index 0a688a1b0f..e4fd8d7dec 100644
--- a/lib/internal/bootstrap_node.js
+++ b/lib/internal/bootstrap_node.js
@@ -47,6 +47,7 @@
 
     _process.setup_hrtime();
     _process.setupConfig(NativeModule._source);
+    NativeModule.require('internal/process/warning').setup();
     NativeModule.require('internal/process/next_tick').setup();
     NativeModule.require('internal/process/stdio').setup();
     _process.setupKillAndExit();
diff --git a/lib/internal/process/warning.js b/lib/internal/process/warning.js
new file mode 100644
index 0000000000..4087eb0d28
--- /dev/null
+++ b/lib/internal/process/warning.js
@@ -0,0 +1,49 @@
+'use strict';
+
+const traceWarnings = process.traceProcessWarnings;
+const noDeprecation = process.noDeprecation;
+const traceDeprecation = process.traceDeprecation;
+const throwDeprecation = process.throwDeprecation;
+const prefix = `(${process.release.name}:${process.pid}) `;
+
+exports.setup = setupProcessWarnings;
+
+function setupProcessWarnings() {
+  if (!process.noProcessWarnings) {
+    process.on('warning', (warning) => {
+      if (!(warning instanceof Error)) return;
+      const isDeprecation = warning.name === 'DeprecationWarning';
+      if (isDeprecation && noDeprecation) return;
+      const trace = traceWarnings || (isDeprecation && traceDeprecation);
+      if (trace && warning.stack) {
+        console.error(`${prefix}${warning.stack}`);
+      } else {
+        var toString = warning.toString;
+        if (typeof toString !== 'function')
+          toString = Error.prototype.toString;
+        console.error(`${prefix}${toString.apply(warning)}`);
+      }
+    });
+  }
+
+  // process.emitWarning(error)
+  // process.emitWarning(str[, name][, ctor])
+  process.emitWarning = function(warning, name, ctor) {
+    if (typeof name === 'function') {
+      ctor = name;
+      name = 'Warning';
+    }
+    if (warning === undefined || typeof warning === 'string') {
+      warning = new Error(warning);
+      warning.name = name || 'Warning';
+      Error.captureStackTrace(warning, ctor || process.emitWarning);
+    }
+    if (!(warning instanceof Error)) {
+      throw new TypeError('\'warning\' must be an Error object or string.');
+    }
+    if (throwDeprecation && warning.name === 'DeprecationWarning')
+      throw warning;
+    else
+      process.nextTick(() => process.emit('warning', warning));
+  };
+}
diff --git a/lib/internal/util.js b/lib/internal/util.js
index a9e77c658f..56398ccf9d 100644
--- a/lib/internal/util.js
+++ b/lib/internal/util.js
@@ -2,6 +2,7 @@
 
 const binding = process.binding('util');
 const prefix = `(${process.release.name}:${process.pid}) `;
+const noDeprecation = process.noDeprecation;
 
 exports.getHiddenValue = binding.getHiddenValue;
 exports.setHiddenValue = binding.setHiddenValue;
@@ -9,13 +10,17 @@ exports.setHiddenValue = binding.setHiddenValue;
 // All the internal deprecations have to use this function only, as this will
 // prepend the prefix to the actual message.
 exports.deprecate = function(fn, msg) {
-  return exports._deprecate(fn, `${prefix}${msg}`);
+  return exports._deprecate(fn, msg);
 };
 
 // All the internal deprecations have to use this function only, as this will
 // prepend the prefix to the actual message.
-exports.printDeprecationMessage = function(msg, warned) {
-  return exports._printDeprecationMessage(`${prefix}${msg}`, warned);
+exports.printDeprecationMessage = function(msg, warned, ctor) {
+  if (warned || noDeprecation)
+    return true;
+  process.emitWarning(msg, 'DeprecationWarning',
+                      ctor || exports.printDeprecationMessage);
+  return true;
 };
 
 exports.error = function(msg) {
@@ -35,23 +40,6 @@ exports.trace = function(msg) {
   console.trace(`${prefix}${msg}`);
 };
 
-exports._printDeprecationMessage = function(msg, warned) {
-  if (process.noDeprecation)
-    return true;
-
-  if (warned)
-    return warned;
-
-  if (process.throwDeprecation)
-    throw new Error(msg);
-  else if (process.traceDeprecation)
-    console.trace(msg.startsWith(prefix) ? msg.replace(prefix, '') : msg);
-  else
-    console.error(msg);
-
-  return true;
-};
-
 // Mark that a method should not be used.
 // Returns a modified function which warns once by default.
 // If --no-deprecation is set, then it is a no-op.
@@ -69,7 +57,7 @@ exports._deprecate = function(fn, msg) {
 
   var warned = false;
   function deprecated() {
-    warned = exports._printDeprecationMessage(msg, warned);
+    warned = exports.printDeprecationMessage(msg, warned, deprecated);
     return fn.apply(this, arguments);
   }