How is setTimeout implemented in node.js

You’ve done most of the work already. V8 doesn’t provides an implementation for setTimeout because it’s not part of ECMAScript. The function you use is implemented in timers.js, which creates an instance of a Timeout object which is a wrapper around a C class.

There is a comment in the source describing how they are managing the timers.

// Because often many sockets will have the same idle timeout we will not
// use one timeout watcher per item. It is too much overhead.  Instead
// we'll use a single watcher for all sockets with the same timeout value
// and a linked list. This technique is described in the libev manual:

Which indicates it’s using a double linked list which is #4 in the linked article.

If there is not one request, but many thousands (millions…), all
employing some kind of timeout with the same timeout value, then one
can do even better:

When starting the timeout, calculate the timeout value and put the
timeout at the end of the list.

Then use an ev_timer to fire when the timeout at the beginning of the
list is expected to fire (for example, using the technique #3).

When there is some activity, remove the timer from the list,
recalculate the timeout, append it to the end of the list again, and
make sure to update the ev_timer if it was taken from the beginning of
the list.

This way, one can manage an unlimited number of timeouts in O(1) time
for starting, stopping and updating the timers, at the expense of a
major complication, and having to use a constant timeout. The constant
timeout ensures that the list stays sorted.

Node.js is designed around async operations and setTimeout is an important part of that. I wouldn’t try to get tricky, just use what they provide. Trust that it’s fast enough until you’ve proven that in your specific case it’s a bottleneck. Don’t get stuck on premature optimization.


What happens is you’ve got essentially a dictionary of timeouts at the top level, so all 100ms timeouts are grouped together. Whenever a new timeout is added, or the oldest timeout triggers, it is appended to the list. This means that the oldest timeout, the one which will trigger the soonest, is at the beginning of the list. There is a single timer for this list, and it’s set based on the time until the first item in the list is set to expire.

If you call setTimeout 1000 times each with the same timeout value, they will be appended to the list in the order you called setTimeout and no sorting is necessary. It’s a very efficient setup.

Leave a Comment