docs: clarify timer execution order after libuv 1.45.0

[Archkon]

The previous wording said that timers now run only after the poll phase,
"instead of both before and after" as in earlier versions. That phrasing can
be misleading because it sounds like earlier libuv versions ran timers twice
during a normal event loop iteration: once before polling and once after
polling.

Looking at the actual libuv code, the behavior is more precise:

Before libuv 1.45.0, the regular UV_RUN_DEFAULT path ran timers near the
beginning of each loop iteration, before polling:

while (...) {
  uv__update_time(loop);
  uv__run_timers(loop);

  ...
  uv__io_poll(loop, timeout);
  ...
}

There was a post-poll timer run only for the UV_RUN_ONCE special case, not for
the normal UV_RUN_DEFAULT path used by Node.js' main event loop.

Starting with libuv 1.45.0, the regular per-iteration timer processing was
moved to after polling:

while (...) {
  ...
  uv__io_poll(loop, timeout);
  ...
  uv__update_time(loop);
  uv__run_timers(loop);
}

libuv 1.45.0 also keeps a compatibility behavior for UV_RUN_DEFAULT: it runs
timers once before entering the uv_run() loop. This preserves backwards
compatibility while still making the per-iteration timer ordering happen after
the poll phase.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nodejs-learn	Ready	Preview	Jun 29, 2026 10:23am

[cursor]

PR Summary

Low Risk
Documentation-only clarification with no runtime or API changes.

Overview
Updates the libuv 1.45.0 (Node.js 20) note in the event loop docs so it no longer implies older libuv ran timers twice per normal iteration (“before and after” poll).

The revised text states that per iteration, timers now run after poll, whereas they used to run before poll, and adds that 1.45.0 still runs timers once before entering the event loop for backwards compatibility. The existing warning about setImmediate() vs timer timing is unchanged.

^{Reviewed by Cursor Bugbot for commit 57df605. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

👋 Codeowner Review Request

The following codeowners have been identified for the changed files:

Team reviewers: @nodejs/timers

Please review the changes when you have a chance. Thank you! 🙏

[Copilot]

Pull request overview

Updates the event-loop documentation to more precisely describe how libuv 1.45.0 changed timer execution order, avoiding the misleading implication that older libuv versions ran timers twice per normal UV_RUN_DEFAULT loop iteration.

Changes:

• Clarifies that, starting with libuv 1.45.0, timers run after the poll phase in each iteration.
• Clarifies that earlier versions ran timers before polling in the normal per-iteration path.
• Notes the compatibility behavior in libuv 1.45.0: a one-time timer run before entering the main uv_run() loop.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.