initial stab at process.cpuUsage()

Author: Patrick Mueller

doc/api/process.markdown

@@ -495,6 +495,29 @@ An example of the possible output looks like:
 
 If `process.connected` is false, it is no longer possible to send messages.
 
+## process.cpuUsage()
+
+Returns the user and system cpu time usage of the current process, in an object
+with properties `user` and `system`, whose values are arrays of integers as
+`[seconds, nanoseconds]` tuples. These values measure time spent in user and
+system code respectively, and may end up being greater than actual elapsed time
+if multiple cpu cores are performing work for this process.
+
+You may pass in the result of a previous call to `process.cpuUsage()` to get a
+diff reading.
+
+```js
+var startUsage  = process.cpuUsage();
+// { user: [ 0, 35884000 ], system: [ 0, 7320000 ] }
+
+// spin the CPU for 500 milliseconds
+var now = Date.now();
+while (Date.now() - now < 500);
+
+console.log(process.cpuUsage(startUsage));
+// { user: [ 0, 509627000 ], system: [ 0, 9993000 ] }
+```
+
 ## process.cwd()
 
 Returns the current working directory of the process.

lib/internal/bootstrap_node.js

@@ -47,6 +47,7 @@
     const _process = NativeModule.require('internal/process');
 
     _process.setup_hrtime();
+    _process.setup_cpuUsage();
     _process.setupConfig(NativeModule._source);
     NativeModule.require('internal/process/warning').setup();
     NativeModule.require('internal/process/next_tick').setup();

lib/internal/process.js

@@ -9,6 +9,7 @@ function lazyConstants() {
   return _lazyConstants;
 }
 
+exports.setup_cpuUsage = setup_cpuUsage;
 exports.setup_hrtime = setup_hrtime;
 exports.setupConfig = setupConfig;
 exports.setupKillAndExit = setupKillAndExit;
@@ -22,6 +23,65 @@ const assert = process.assert = function(x, msg) {
 };
 
 
+function setup_cpuUsage() {
+  const _cpuUsage = process.cpuUsage;
+  const cpuValues = new Uint32Array(8);
+
+  process.cpuUsage = function cpuUsage(prevValue) {
+    const err = _cpuUsage(cpuValues);
+    if (err !== 0) throw new Error('unable to obtain cpu usage time');
+
+    // the second element of user/system comes back from libuv as
+    // microseconds, but we convert to nanoseconds here (* 1000) to
+    // be consistent with hrtime()
+    var currValue = {
+      user: [
+        cpuValues[0] * 0x100000000 + cpuValues[1],
+        (cpuValues[2] * 0x100000000 + cpuValues[3]) * 1000
+      ],
+      system: [
+        cpuValues[4] * 0x100000000 + cpuValues[5],
+        (cpuValues[6] * 0x100000000 + cpuValues[7]) * 1000
+      ]
+    };
+
+    if (prevValue == null) return currValue;
+
+    if (prevValue.user == null) {
+      throw new Error('previous value argument missing "user" property');
+    }
+    if (prevValue.system == null) {
+      throw new Error('previous value argument missing "system" property');
+    }
+
+    currValue.user = diffSecUsec(currValue.user, prevValue.user);
+    currValue.system = diffSecUsec(currValue.system, prevValue.system);
+
+    return currValue;
+  };
+}
+
+
+// diff the value from a current and previous [sec, usec] array
+function diffSecUsec(curr, prev) {
+  if (prev == null) return curr;
+
+  // perform the diff
+  var result = [];
+
+  result[0] = curr[0] - prev[0];
+  result[1] = curr[1] - prev[1];
+
+  // result[1] could be negative, on roll-overs, so ... be nice and normalize
+  if (result[1] < 0) {
+    result[0] -= 1;                   // subtract 1 sec
+    result[1] += 1000 * 1000 * 1000;  // add 1 sec's worth of usec's
+  }
+
+  return result;
+}
+
+
 function setup_hrtime() {
   const _hrtime = process.hrtime;
   const hrValues = new Uint32Array(3);

src/node.cc

@@ -2216,6 +2216,35 @@ void Hrtime(const FunctionCallbackInfo<Value>& args) {
   fields[2] = t % NANOS_PER_SEC;
 }
 
+// CPUUsage exposes libuv's uv_getrusage() this-process resource usage accessor,
+// to access ru_utime (user CPU time used) and ru_stime (system CPU time used),
+// which are uv_timeval_t structs (long tv_sec, long tv_usec) as tuples
+// similar to process.hrtime() values.  Only it's seconds/microseconds instead
+// of hrtime()'s seconds/nanoseconds.
+void CPUUsage(const FunctionCallbackInfo<Value>& args) {
+  uv_rusage_t rusage;
+
+  // call to libuv to get the values we'll return
+  int err = uv_getrusage(&rusage);
+
+  // expecting to be passed in a uint array, of length 8
+  Local<ArrayBuffer> ab = args[0].As<Uint32Array>()->Buffer();
+  uint32_t* fields = static_cast<uint32_t*>(ab->GetContents().Data());
+
+  // results passed as split values, reassembled in JS
+  fields[0] = (rusage.ru_utime.tv_sec) >> 32;
+  fields[1] = (rusage.ru_utime.tv_sec) & 0xffffffff;
+  fields[2] = (rusage.ru_utime.tv_usec) >> 32;
+  fields[3] = (rusage.ru_utime.tv_usec) & 0xffffffff;
+  fields[4] = (rusage.ru_stime.tv_sec) >> 32;
+  fields[5] = (rusage.ru_stime.tv_sec) & 0xffffffff;
+  fields[6] = (rusage.ru_stime.tv_usec) >> 32;
+  fields[7] = (rusage.ru_stime.tv_usec) & 0xffffffff;
+
+  // return value will be return code from the libuv call
+  args.GetReturnValue().Set(err);
+}
+
 extern "C" void node_module_register(void* m) {
   struct node_module* mp = reinterpret_cast<struct node_module*>(m);
 
@@ -3208,6 +3237,8 @@ void SetupProcessObject(Environment* env,
 
   env->SetMethod(process, "hrtime", Hrtime);
 
+  env->SetMethod(process, "cpuUsage", CPUUsage);
+
   env->SetMethod(process, "dlopen", DLOpen);
 
   env->SetMethod(process, "uptime", Uptime);

test/parallel/test-process-cpuUsage.js

@@ -0,0 +1,47 @@
+'use strict';
+require('../common');
+var assert = require('assert');
+
+// the default behavior, return { user: [int, int], system: [int, int]}
+var result = process.cpuUsage();
+
+// validate the default behavior
+validateResult(result);
+
+// validate that passing an existing result returns another valid result
+validateResult(process.cpuUsage(result));
+
+// test that only a previous result object may be passed to process.cpuUsage()
+assert.throws(function() { process.cpuUsage(1); });
+assert.throws(function() { process.cpuUsage({}); });
+assert.throws(function() { process.cpuUsage({ user: [0, 0] }); });
+assert.throws(function() { process.cpuUsage({ system: [0, 0] }); });
+assert.throws(function() { process.cpuUsage({ user: null, system: [0, 0] }); });
+assert.throws(function() { process.cpuUsage({ user: [0, 0], system: null }); });
+
+function validateResult(result) {
+  assert(result.user != null);
+  assert(result.system != null);
+
+  assert(Array.isArray(result.user));
+  assert(Array.isArray(result.system));
+
+  assert.equal(2, result.user.length);
+  assert.equal(2, result.system.length);
+
+  result.user.forEach(function(v) {
+    assert.equal('number', typeof v);
+    assert(isFinite(v));
+  });
+
+  result.system.forEach(function(v) {
+    assert.equal('number', typeof v);
+    assert(isFinite(v));
+  });
+}
+
+// ensure we don't end up sending negative values on second rollovers
+// https://github.com/nodejs/node/issues/4751
+const diff = process.cpuUsage({ user: [0, 1e9 - 1], system: [0, 1e9 - 1] });
+assert(diff.user[1] >= 0);
+assert(diff.system[1] >= 0);

test/pummel/test-process-cpuUsage.js

@@ -0,0 +1,30 @@
+'use strict';
+require('../common');
+var assert = require('assert');
+
+var start = process.cpuUsage();
+
+// process.cpuUsage() should return {user: [int, int], system: [int, int]}
+assert(start != null);
+assert(Array.isArray(start.user));
+assert(Array.isArray(start.system));
+
+// busy-loop for 2 seconds
+var now = Date.now();
+while (Date.now() - now < 2000);
+
+// get a diff reading
+var diff = process.cpuUsage(start);
+
+// user should be at least 1 second, at most 2 seconds later
+// (the while loop will usually exit a few nanoseconds before 2)
+assert(diff.user[0] >= 1);
+assert(diff.user[0] <= 2);
+
+// hard to tell what the system number should be, but at least > 0, < 2
+assert(diff.system[0] >= 0);
+assert(diff.system[0] <= 2);
+
+// make sure nanosecond value is not negative
+assert(diff.user[1] >= 0);
+assert(diff.system[1] >= 0);