process: add process.cpuUsage() - implementation, doc, tests

Add process.cpuUsage() method that returns the user and system CPU time usage of the current process PR-URL: #6157 Reviewed-By: Robert Lindstaedt <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Santiago Gimeno <[email protected]>

Author: Patrick Mueller

doc/api/process.md

@@ -504,6 +504,29 @@ the value of `process.config`.*
 
 If `process.connected` is `false`, it is no longer possible to send messages.
 
+## process.cpuUsage([previousValue])
+
+Returns the user and system CPU time usage of the current process, in an object
+with properties `user` and `system`, whose values are microsecond values
+(millionth of a second). 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.
+
+The result of a previous call to `process.cpuUsage()` can be passed as the
+argument to the function, to get a diff reading.
+
+```js
+conststartUsage=process.cpuUsage();
+//{user: 38579, system: 6986 }
+
+// spin the CPU for 500 milliseconds
+constnow=Date.now();
+while (Date.now() - now <500);
+
+console.log(process.cpuUsage(startUsage));
+//{user: 514883, system: 11226 }
+```
+
 ## 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,57 @@ const assert = process.assert = function(x, msg){
 };
 
 
+// Set up the process.cpuUsage() function.
+functionsetup_cpuUsage(){
+// Get the native function, which will be replaced with a JS version.
+const_cpuUsage=process.cpuUsage;
+
+// Create the argument array that will be passed to the native function.
+constcpuValues=newFloat64Array(2);
+
+// Replace the native function with the JS version that calls the native
+// function.
+process.cpuUsage=functioncpuUsage(prevValue){
+// If a previous value was passed in, ensure it has the correct shape.
+if(prevValue){
+if(!previousValueIsValid(prevValue.user)){
+thrownewTypeError('value of user property of argument is invalid');
+}
+
+if(!previousValueIsValid(prevValue.system)){
+thrownewTypeError('value of system property of argument is invalid');
+}
+}
+
+// Call the native function to get the current values.
+consterrmsg=_cpuUsage(cpuValues);
+if(errmsg){
+thrownewError('unable to obtain CPU usage: '+errmsg);
+}
+
+// If a previous value was passed in, return diff of current from previous.
+if(prevValue)return{
+user: cpuValues[0]-prevValue.user,
+system: cpuValues[1]-prevValue.system
+};
+
+// If no previous value passed in, return current value.
+return{
+user: cpuValues[0],
+system: cpuValues[1]
+};
+
+// Ensure that a previously passed in value is valid. Currently, the native
+// implementation always returns numbers <= Number.MAX_SAFE_INTEGER.
+functionpreviousValueIsValid(num){
+returnNumber.isFinite(num)&&
+num<=Number.MAX_SAFE_INTEGER&&
+num>=0;
+}
+};
+}
+
+
 functionsetup_hrtime(){
 const_hrtime=process.hrtime;
 consthrValues=newUint32Array(3);

src/node.cc

@@ -106,6 +106,7 @@ using v8::Boolean;
 using v8::Context;
 using v8::EscapableHandleScope;
 using v8::Exception;
+using v8::Float64Array;
 using v8::Function;
 using v8::FunctionCallbackInfo;
 using v8::FunctionTemplate;
@@ -2220,6 +2221,38 @@ void Hrtime(const FunctionCallbackInfo<Value>& args){
  fields[2] = t % NANOS_PER_SEC;
 }
 
+// Microseconds in a second, as a float, used in CPUUsage() below
+#defineMICROS_PER_SEC1e6
+
+// CPUUsage use 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).
+// Returns those values as Float64 microseconds in the elements of the array
+// passed to the function.
+voidCPUUsage(const FunctionCallbackInfo<Value>& args){
+uv_rusage_t rusage;
+
+// Call libuv to get the values we'll return.
+int err = uv_getrusage(&rusage);
+if (err){
+// On error, return the strerror version of the error code.
+ Local<String> errmsg = OneByteString(args.GetIsolate(), uv_strerror(err));
+ args.GetReturnValue().Set(errmsg);
+return;
+ }
+
+// Get the double array pointer from the Float64Array argument.
+CHECK(args[0]->IsFloat64Array());
+ Local<Float64Array> array = args[0].As<Float64Array>();
+CHECK_EQ(array->Length(), 2);
+ Local<ArrayBuffer> ab = array->Buffer();
+double* fields = static_cast<double*>(ab->GetContents().Data());
+
+// Set the Float64Array elements to be user / system values in microseconds.
+ fields[0] = MICROS_PER_SEC * rusage.ru_utime.tv_sec + rusage.ru_utime.tv_usec;
+ fields[1] = MICROS_PER_SEC * rusage.ru_stime.tv_sec + rusage.ru_stime.tv_usec;
+}
+
 extern"C"voidnode_module_register(void* m){
 structnode_module* mp = reinterpret_cast<structnode_module*>(m);
 
@@ -3212,6 +3245,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,63 @@
+'use strict';
+require('../common');
+constassert=require('assert');
+
+constresult=process.cpuUsage();
+
+// Validate the result of calling with no previous value argument.
+validateResult(result);
+
+// Validate the result of calling with a previous value argument.
+validateResult(process.cpuUsage(result));
+
+// Ensure the results are >= the previous.
+letthisUsage;
+letlastUsage=process.cpuUsage();
+for(leti=0;i<10;i++){
+thisUsage=process.cpuUsage();
+validateResult(thisUsage);
+assert(thisUsage.user>=lastUsage.user);
+assert(thisUsage.system>=lastUsage.system);
+lastUsage=thisUsage;
+}
+
+// Ensure that the diffs are >= 0.
+letstartUsage;
+letdiffUsage;
+for(leti=0;i<10;i++){
+startUsage=process.cpuUsage();
+diffUsage=process.cpuUsage(startUsage);
+validateResult(startUsage);
+validateResult(diffUsage);
+assert(diffUsage.user>=0);
+assert(diffUsage.system>=0);
+}
+
+// Ensure that an invalid shape for the previous value argument throws an error.
+assert.throws(function(){process.cpuUsage(1);});
+assert.throws(function(){process.cpuUsage({});});
+assert.throws(function(){process.cpuUsage({user: 'a'});});
+assert.throws(function(){process.cpuUsage({system: 'b'});});
+assert.throws(function(){process.cpuUsage({user: null,system: 'c'});});
+assert.throws(function(){process.cpuUsage({user: 'd',system: null});});
+assert.throws(function(){process.cpuUsage({user: -1,system: 2});});
+assert.throws(function(){process.cpuUsage({user: 3,system: -2});});
+assert.throws(function(){process.cpuUsage({
+user: Number.POSITIVE_INFINITY,
+system: 4
+});});
+assert.throws(function(){process.cpuUsage({
+user: 5,
+system: Number.NEGATIVE_INFINITY
+});});
+
+// Ensure that the return value is the expected shape.
+functionvalidateResult(result){
+assert.notEqual(result,null);
+
+assert(Number.isFinite(result.user));
+assert(Number.isFinite(result.system));
+
+assert(result.user>=0);
+assert(result.system>=0);
+}

test/pummel/test-process-cpuUsage.js

@@ -0,0 +1,30 @@
+'use strict';
+require('../common');
+constassert=require('assert');
+
+conststart=process.cpuUsage();
+
+// Run a busy-loop for specified # of milliseconds.
+constRUN_FOR_MS=500;
+
+// Define slop factor for checking maximum expected diff values.
+constSLOP_FACTOR=2;
+
+// Run a busy loop.
+constnow=Date.now();
+while(Date.now()-now<RUN_FOR_MS);
+
+// Get a diff reading from when we started.
+constdiff=process.cpuUsage(start);
+
+constMICROSECONDS_PER_SECOND=1000*1000;
+
+// Diff usages should be >= 0, <= ~RUN_FOR_MS millis.
+// Let's be generous with the slop factor, defined above, in case other things
+// are happening on this CPU. The <= check may be invalid if the node process
+// is making use of multiple CPUs, in which case, just remove it.
+assert(diff.user>=0);
+assert(diff.user<=SLOP_FACTOR*RUN_FOR_MS*MICROSECONDS_PER_SECOND);
+
+assert(diff.system>=0);
+assert(diff.system<=SLOP_FACTOR*RUN_FOR_MS*MICROSECONDS_PER_SECOND);