Requesting documentation of v8.getHeapStatistics() properties

[SimonSimCity]

#32206 mentions that none of the properties returned by v8.getHeapStatistics() are properly documented.

I'm currently relying on an answer I found on stackoverflow (https://stackoverflow.com/questions/41541843/nodejs-v8-getheapstatistics-method) but there should be some official documentation about the individual values returned in the documentation.

[bnoordhuis]

Pull request welcome.

[SimonSimCity]

Some of the values are also available by process.memoryUsage() and therefore already described at https://nodejs.org/api/process.html#process_process_memoryusage:

• v8.getHeapStatistics().total_heap_size -> process.memoryUsage().heapTotal
• v8.getHeapStatistics().used_heap_size -> process.memoryUsage().heapUsed
• v8.getHeapStatistics().external_memory -> process.memoryUsage().external

See:

node/src/node_process_methods.cc

Lines 190 to 219 in 60c4c2b

	static void MemoryUsage(const FunctionCallbackInfo<Value>& args) {
	Environment* env = Environment::GetCurrent(args);
	size_t rss;
	int err = uv_resident_set_memory(&rss);
	if (err)
	return env->ThrowUVException(err, "uv_resident_set_memory");
	Isolate* isolate = env->isolate();
	// V8 memory usage
	HeapStatistics v8_heap_stats;
	isolate->GetHeapStatistics(&v8_heap_stats);
	NodeArrayBufferAllocator* array_buffer_allocator =
	env->isolate_data()->node_allocator();
	// Get the double array pointer from the Float64Array argument.
	CHECK(args[0]->IsFloat64Array());
	Local<Float64Array> array = args[0].As<Float64Array>();
	CHECK_EQ(array->Length(), 5);
	Local<ArrayBuffer> ab = array->Buffer();
	double* fields = static_cast<double*>(ab->GetBackingStore()->Data());
	fields[0] = rss;
	fields[1] = v8_heap_stats.total_heap_size();
	fields[2] = v8_heap_stats.used_heap_size();
	fields[3] = v8_heap_stats.external_memory();
	fields[4] = array_buffer_allocator == nullptr ?
	0 : array_buffer_allocator->total_mem_usage();
	}

and

node/lib/internal/process/per_thread.js

Lines 149 to 159 in abe6a2e

	const memValues = new Float64Array(5);
	function memoryUsage() {
	_memoryUsage(memValues);
	return {
	rss: memValues[0],
	heapTotal: memValues[1],
	heapUsed: memValues[2],
	external: memValues[3],
	arrayBuffers: memValues[4]
	};
	}

Maybe we should mention that those are the same.

[gireeshpunathil]

this is fully documented now, here. Closing, pls re-open if my understanding is wrong

[marc-guenther]

Only does_zap_garbage, number_of_native_contexts and number_of_detached_contexts are documented, the rest of the properties are not explained at all, nor is the relationship to process.memoryUsage().