Understanding the Node.js Event Loop

This content originally appeared on DEV Community and was authored by Tyler Hawkins

JavaScript is single-threaded, so how does it handle asynchronous code without blocking the main thread while it waits for an action to complete? The key to understanding the asynchronous nature of JavaScript is understanding the event loop.

In the browser, the event loop coordinates the execution of code between the call stack, web APIs, and the callback queue. Node.js, however, implements its own “Node.js event loop,” which is different from the regular “JavaScript event loop.” How confusing!

The Node.js event loop follows many of the same patterns as the JavaScript event loop but works slightly differently, as it doesn’t interact with the DOM but does deal with things like input and output (I/O).

In this article, we’ll dive into the theory behind the Node.js event loop and then look at a few examples using setTimeout, setImmediate, and process.nextTick. We'll even deploy some working code to Heroku (an easy way to quickly deploy apps) to see it all in action.

The Node.js Event Loop

The Node.js event loop coordinates the execution of operations from timers, callbacks, and I/O events. This is how Node.js handles asynchronous behavior while still being single-threaded. Let’s look at a diagram of the event loop below to get a better understanding of the order of operations:

The Node.js event loop’s order of operations (Source: Node.js docs)

As you can see, there are six main phases in the Node.js event loop. Let’s briefly look at what happens in each phase:

• Timers: callbacks scheduled by setTimeout and setInterval are executed during this phase

• Pending callbacks: I/O callbacks that were previously deferred to the next loop iteration are executed during this phase

• Idle, prepare: this phase is only used internally by Node.js

• Poll: new I/O events are retrieved and I/O callbacks are executed during this phase (except for callbacks scheduled by timers, callbacks scheduled by setImmediate, and close callbacks, because those are all handled in different phases)

• Check: callbacks scheduled by setImmediate are executed during this phase

• Close callbacks: close callbacks, like when a socket connection is destroyed, are executed during this phase

It’s interesting to note that process.nextTick isn't mentioned anywhere in any of these phases. That's because it's a special method that's not technically part of the Node.js event loop. Instead, whenever the process.nextTick method is called, it places its callbacks into a queue, and those queued callbacks are then "processed after the current operation is completed, regardless of the current phase of the event loop" (Source: Node.js event loop docs).

Event Loop Example Scenarios

Now, if you’re like me, those explanations of each phase of the Node.js event loop may still seem a little abstract. I learn by seeing and by doing, so I created this demo app on Heroku for running various code snippet examples. In the app, clicking on any of the example buttons sends an API request to the server. The code snippet for the selected example is then executed by Node.js on the backend, and the response is returned to the frontend via the API. You can view the full code on GitHub.

Node.js event loop demo app

Let’s look at some examples to better understand the order of operations in the Node.js event loop.

Example 1

We’ll start with an easy one:

Example 1 — synchronous code

Here we have three synchronous functions called one after the other. Because these functions are all synchronous, the code is simply executed from top to bottom. So because we call our functions in the order first, second, third, the functions are executed in the same order: first, second, third.

Example 2

Next, we’ll introduce the concept of setTimeout with our second example:

Example 2 — setTimeout

Here we call our first function, then schedule our second function using setTimeout with a delay of 0 milliseconds, then call our third function. The functions are executed in this order: first, third, second. Why is that? Why is the second function executed last?

There are a couple key principles to understand here. The first principle is that using the setTimeout method and providing a delay value doesn't mean that the callback function will be executed exactly after that number of milliseconds. Rather, that value represents the minimum amount of time that needs to elapse before the callback will be executed.

The second key principle to understand is that using setTimeout schedules the callback to be executed at a later time, which will always be at least during the next iteration of the event loop. So during this first iteration of the event loop, the first function was executed, the second function was scheduled, and the third function was executed. Then, during the second iteration of the event loop, the minimum delay of 0 milliseconds had been reached, so the second function was executed during the “timers” phase of this second iteration.

Example 3

Next up, we’ll introduce the concept of setImmediate with our third example:

Example 3 — setImmediate vs. setTimeout

In this example, we execute our first function, schedule our second function using setTimeout with a delay of 0 milliseconds, and then schedule our third function using setImmediate. This example begs the question: Which type of scheduling takes precedence in this scenario? setTimeout or setImmediate?

We’ve already discussed how setTimeout works, so we should give a brief background on the setImmediate method. The setImmediate method executes its callback function during the "check" phase of the next iteration of the event loop. So if setImmediate is called during the first iteration of the event loop, its callback method will be scheduled and then will be executed during the second iteration of the event loop.

As you can see from the output, the functions in this example are executed in this order: first, third, second. So in our case, the callback scheduled by setImmediate was executed before the callback scheduled by setTimeout.

It’s interesting to note that the behavior you see with setImmediate and setTimeout may vary depending on the context in which these methods are called. When these methods are called directly from the main module in a Node.js script, the timing depends on the performance of the process, so the callbacks could actually be executed in either order each time you run the script. However, when these methods are called within an I/O cycle, the setImmediate callback is always invoked before the setTimeout callback. Since we are invoking these methods as part of a response in an API endpoint in our example, our setImmediate callback always gets executed before our setTimeout callback.

Example 4

As a quick sanity check, let’s run one more example using setImmediate and setTimeout.

Example 4 — setImmediate versus setTimeout again

In this example, we schedule our first function using setImmediate, execute our second function, and then schedule our third function using setTimeout with a delay of 0 milliseconds. As you might have guessed, the functions are executed in this order: second, first, third. This is because the first function is scheduled, the second function is immediately executed, and then the third function is scheduled. During the second iteration of the event loop, the second function is executed since it was scheduled by setImmediate and we're in an I/O cycle, and then the third function is executed now that we're in the second iteration of the event loop and the specified delay of 0 milliseconds has passed.

Are you starting to get the hang of it?

Example 5

Let’s look at one last example. This time we’ll introduce another method called process.nextTick.

Example 5 — process.nextTick

In this example, we schedule our first function using setImmediate, schedule our second function using process.nextTick, schedule our third function using setTimeout with a delay of 0 milliseconds, and then execute our fourth function. The functions end up being called in the following order: fourth, second, first, third.

The fact that the fourth function was executed first shouldn't be a surprise. This function was called directly without being scheduled by any of our other methods. The second function was executed second. This is the one that was scheduled with process.nextTick. The first function was executed third, followed by the third function last, which shouldn't be a surprise to us either since we already know that callbacks scheduled by setImmediate get executed before callbacks scheduled by setTimeout when inside an I/O cycle.

So why did the second function scheduled by process.nextTick get executed before the first function scheduled by setImmediate? The method names are misleading here! You would think that a callback from setImmediate would get executed immediately while a callback from process.nextTick would get executed on the next tick of the event loop. However, it's actually the other way around. Confusing, right?

It turns out that a callback from process.nextTick gets executed immediately during the same phase as it was scheduled. A callback from setImmediate gets executed during the next iteration or tick of the event loop. So in our example, it makes sense that the second function scheduled by process.nextTick was executed before the first function scheduled by setImmediate.

Conclusion

By now you should be a little more familiar with the Node.js event loop as well as with methods like setTimeout, setImmediate, and process.nextTick. You can certainly get by without digging into the internals of Node.js and the order of operations in which commands are processed. However, when you begin to understand the Node.js event loop, Node.js becomes a little less of a black box.

If you want to see these examples live in action again, you can always check out the demo app or view the code on GitHub. You can even deploy the code to Heroku yourself by clicking here.

Thanks for reading!

This content originally appeared on DEV Community and was authored by Tyler Hawkins