timers: reuse Timeout objects in setStreamTimeout

mcollina · richardlau · commit 086741d1214b · 2026-07-06T16:33:27.000Z
Rearm the stream's existing Timeout object instead of allocating a new Timeout and a bound callback on every setTimeout() call. The HTTP server disarms and rearms the keep-alive timeout twice per request, so this saves two allocations and the associated async resource churn on every request over a keep-alive connection. The async resource is re-initialized on reuse, so async_hooks observes the same init/destroy sequence as before. A microbenchmark of the setTimeout(msecs)/setTimeout(0) cycle improves by 2.2x (205.9ns to 92.8ns), and benchmark/http/simple.js (type=buffer len=1024 chunks=1 chunkedEnc=0 c=50) improves by 3.70% (t=2.15, 40 samples per binary with server and load generator pinned to disjoint CPU sets). Assisted-by: Claude Fable 5 (Claude Code) Signed-off-by: Matteo Collina <hello@matteocollina.com> PR-URL: #64254 Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Minwoo Jung <nodecorelab@gmail.com>
diff --git a/lib/internal/stream_base_commons.js b/lib/internal/stream_base_commons.js
@@ -22,7 +22,7 @@ const {
 const { owner_symbol } = require('internal/async_hooks').symbols;
 const {
   kTimeout,
-  setUnrefTimeout,
+  reuseOrCreateUnrefTimeout,
   getTimerDuration,
 } = require('internal/timers');
 const { isUint8Array } = require('internal/util/types');
@@ -233,6 +233,10 @@ function onStreamRead(arrayBuffer) {
   }
 }
 
+function onStreamTimeout(stream) {
+  stream._onTimeout();
+}
+
 function setStreamTimeout(msecs, callback) {
   if (this.destroyed)
     return this;
@@ -244,6 +248,8 @@ function setStreamTimeout(msecs, callback) {
 
   // Attempt to clear an existing timer in both cases -
   //  even if it will be rescheduled we don't want to leak an existing timer.
+  // The cleared Timeout stays referenced in this[kTimeout] so that it can be
+  // reused the next time a timeout is set, e.g. on keep-alive connections.
   clearTimeout(this[kTimeout]);
 
   if (msecs === 0) {
@@ -252,7 +258,8 @@ function setStreamTimeout(msecs, callback) {
       this.removeListener('timeout', callback);
     }
   } else {
-    this[kTimeout] = setUnrefTimeout(this._onTimeout.bind(this), msecs);
+    this[kTimeout] =
+      reuseOrCreateUnrefTimeout(this[kTimeout], onStreamTimeout, msecs, this);
     if (this[kSession]) this[kSession][kUpdateTimer]();
     if (this[kBoundSession]) this[kBoundSession][kUpdateTimer]();
 
diff --git a/lib/internal/timers.js b/lib/internal/timers.js
@@ -417,6 +417,36 @@ function setUnrefTimeout(callback, after) {
   return timer;
 }
 
+// Just like setUnrefTimeout() but reuses `timer` if it is a Timeout that is
+// no longer scheduled (fired or cleared), avoiding the allocation of a new
+// Timeout on rearm. This is the internal reuse path anticipated by the
+// TODO in unenroll() (lib/timers.js), used by hot paths such as the
+// keep-alive timeout handling in the HTTP server. `arg` is passed to
+// `callback` when the timer fires.
+function reuseOrCreateUnrefTimeout(timer, callback, after, arg) {
+  if (timer !== undefined && timer !== null &&
+      timer._destroyed && timer._repeat === null && !timer[kHasPrimitive]) {
+    timer._idleTimeout = after;
+    timer._onTimeout = callback;
+    const args = timer._timerArgs;
+    if (args === undefined) {
+      timer._timerArgs = [arg];
+    } else {
+      args[0] = arg;
+    }
+    // Re-inserts the timer and re-initializes its async resource, so
+    // async_hooks observes the same init/destroy sequence as if a new
+    // Timeout had been allocated.
+    unrefActive(timer);
+    return timer;
+  }
+
+  timer = new Timeout(callback, after, [arg], false, false);
+  insert(timer, timer._idleTimeout);
+
+  return timer;
+}
+
 // Type checking used by timers.enroll() and Socket#setTimeout()
 function getTimerDuration(msecs, name) {
   validateNumber(msecs, name);
@@ -704,6 +734,7 @@ module.exports = {
   kHasPrimitive,
   initAsyncResource,
   setUnrefTimeout,
+  reuseOrCreateUnrefTimeout,
   getTimerDuration,
   immediateQueue,
   getTimerCallbacks,
