Documentation: performance warning about timeout.unref() is not clear.

[cakoose]

Affected URL(s)

https://nodejs.org/api/timers.html#timeoutunref

Description of the problem

The documentation for timeout.unref() ends with this warning:

Calling timeout.unref() creates an internal timer that will wake the Node.js event loop. Creating too many of these can adversely impact performance of the Node.js application.

I don't understand what this means.

"creates an internal timer that will wake the Node.js event loop" sounds roughly like what setTimeout does. Is it different?

Tangent: I also noticed that the docs for the new timersPromises.setInterval (link) supports the ref parameter but there's no similar warning there.

[Trott]

@nodejs/timers

[meixg]

It had been added for a long time: bdd1a74
Maybe we need to check its current status.

[meixg]

I checked the code in v0.9.1, there is indeed a new Timer process:

node/lib/timers.js

Lines 254 to 267 in e6ce259

	Timeout.prototype.unref = function() {
	if (!this._handle) {
	var delay = this._when - Date.now();
	if (delay < 0) delay = 0;
	exports.unenroll(this);
	this._handle = new Timer();
	this._handle.ontimeout = this._onTimeout;
	this._handle.start(delay, 0);
	this._handle.domain = this.domain;
	this._handle.unref();
	} else {
	this._handle.unref();
	}
	};

But this is not the case now.