-
Notifications
You must be signed in to change notification settings - Fork 29.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Event Loop Guide grammar fixes #7479
Changes from 4 commits
61cb735
8a3a5d2
e25d593
4e673cd
9d74fa5
1f3ade9
bb971d6
95da32c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -4,20 +4,20 @@ | |
|
||
The event loop is what allows Node.js to perform non-blocking I/O | ||
operations — despite the fact that JavaScript is single-threaded — by | ||
offloading operations to the system kernel whenever possible. | ||
offloading operations to the system kernel whenever possible. | ||
|
||
Since most modern kernels are multi-threaded, they can handle multiple | ||
operations executing in the background. When one of these operations | ||
completes, the kernel tells Node.js so that the appropriate callback | ||
may added to the `poll` queue to eventually be executed. We'll explain | ||
this in further detail later in this topic. | ||
|
||
## Event Loop Explained | ||
## Event Loop Explained | ||
|
||
When Node.js starts, it initializes the event loop, processes the | ||
provided input script (or drops into the REPL, which is not covered in | ||
this document) which may make async API calls, schedule timers, or call | ||
`process.nextTick()`, then begins processing the event loop. | ||
`process.nextTick()`, then begins processing the event loop. | ||
|
||
The following diagram shows a simplified overview of the event loop's | ||
order of operations. | ||
|
@@ -67,7 +67,7 @@ actually uses are those above._ | |
|
||
## Phases Overview: | ||
|
||
* `timers`: this phase executes callbacks scheduled by `setTimeout()` | ||
* `timers`: this phase executes callbacks scheduled by `setTimeout()` | ||
and `setInterval()`. | ||
* `I/O callbacks`: most types of callback except timers, setImmedate, close | ||
* `idle, prepare`: only used internally | ||
|
@@ -81,29 +81,29 @@ any. | |
|
||
## Phases in Detail | ||
|
||
### timers | ||
### `timers`: | ||
|
||
A timer specifies the **threshold** _after which_ a provided callback | ||
_may be executed_ rather than the **exact** time a person _wants it to | ||
be executed_. Timers callbacks will run as early as they can be | ||
scheduled after the specified amount of time has passed; however, | ||
Operating System scheduling or the running of other callbacks may delay | ||
them. | ||
them. | ||
|
||
_**Note**: Technically, the [`poll` phase](#poll) controls when timers | ||
_**Note**: Technically, the [`poll` phase](#poll) controls when timers | ||
are executed._ | ||
|
||
For example, say you schedule a timeout to execute after a 100 ms | ||
threshold, then your script starts asynchronously reading a file which | ||
For example, say you schedule a timeout to execute after a 100 ms | ||
threshold, then your script starts asynchronously reading a file which | ||
takes 95 ms: | ||
|
||
```js | ||
|
||
var fs = require('fs'); | ||
|
||
function someAsyncOperation (callback) { | ||
// let's assume this takes 95ms to complete | ||
|
||
// let's assume this takes 95ms to complete | ||
fs.readFile('/path/to/file', callback); | ||
|
||
} | ||
|
@@ -140,38 +140,37 @@ executed. When the callback finishes, there are no more callbacks in the | |
queue, so the event loop will see that the threshold of the soonest | ||
timer has been reached then wrap back to the `timers` phase to execute | ||
the timer's callback. In this example, you will see that the total delay | ||
between the timer being scheduled and its callback being executed will | ||
between the timer being scheduled and its callback being executed will | ||
be 105ms. | ||
|
||
Note: To prevent the `poll` phase from starving the event loop, libuv | ||
also has a hard maximum (system dependent) before it stops `poll`ing for | ||
more events. | ||
|
||
### I/O callbacks: | ||
### `I/O callbacks`: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This doesn't need backticks. |
||
|
||
This phase executes callbacks for some system operations such as types | ||
This phase executes callbacks for some system operations such as types | ||
of TCP errors. For example if a TCP socket receives `ECONNREFUSED` when | ||
attempting to connect, some \*nix systems want to wait to report the | ||
error. This will be queued to execute in the `I/O callbacks` phase. | ||
|
||
### poll: | ||
### `poll`: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Same here. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. For these back-ticks, I was copying the pattern in the above "phases overview" section. Also, subsequent phase headers do have back-ticks. I think consistency should be maintained, so do you suggest removing them all, or keeping them? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Seems like they should be removed unless they are referencing something that is code, such as There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Okay, sounds good. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ah, one more thing, these event loop phases are back-ticked all over the document. I think it really helps for them to stand out from normal text, but I agree that the reader should probably not think of them as code. What do you think about a different designation for these phases, maybe italics? or just quotes? |
||
|
||
The poll phase has two main functions: | ||
|
||
1. Executing scripts for timers who's threshold has elapsed, then | ||
2. Processing events in the `poll` queue. | ||
|
||
|
||
When the event loop enters the `poll` phase _and there are no timers | ||
scheduled_, one of two things will happen: | ||
|
||
* _If the `poll` queue **is not empty**_, the event loop will iterate | ||
through its queue of callbacks executing them synchronously until | ||
either the queue has been exhausted, or the system-dependent hard limit | ||
through its queue of callbacks executing them synchronously until | ||
either the queue has been exhausted, or the system-dependent hard limit | ||
is reached. | ||
|
||
* _If the `poll` queue **is empty**_, one of two more things will | ||
happen: | ||
happen: | ||
* If scripts have been scheduled by `setImmediate()`, the event loop | ||
will end the `poll` phase and continue to the `check` phase to | ||
execute those scheduled scripts. | ||
|
@@ -182,14 +181,14 @@ happen: | |
|
||
Once the `poll` queue is empty the event loop will check for timers | ||
_whose time thresholds have been reached_. If one or more timers are | ||
ready, the event loop will wrap back to the timers phase to execute | ||
ready, the event loop will wrap back to the `timers` phase to execute | ||
those timers' callbacks. | ||
|
||
### `check`: | ||
|
||
This phase allows a person to execute callbacks immediately after the | ||
`poll` phase has completed. If the `poll` phase becomes idle and | ||
scripts have been queued with `setImmediate()`, the event loop may | ||
This phase allows a person to execute callbacks immediately after the | ||
`poll` phase has completed. If the `poll` phase becomes idle and | ||
scripts have been queued with `setImmediate()`, the event loop may | ||
continue to the `check` phase rather than waiting. | ||
|
||
`setImmediate()` is actually a special timer that runs in a separate | ||
|
@@ -199,10 +198,10 @@ execute after the `poll` phase has completed. | |
Generally, as the code is executed, the event loop will eventually hit | ||
the `poll` phase where it will wait for an incoming connection, request, | ||
etc. However, after a callback has been scheduled with `setImmediate()`, | ||
then the `poll` phase becomes idle, it will end and continue to the | ||
`check` phase rather than waiting for `poll` events. | ||
then the `poll` phase becomes idle, it will end and continue to the | ||
`check` phase rather than waiting for `poll` events. | ||
|
||
### `close callbacks`: | ||
### `close callbacks`: | ||
|
||
If a socket or handle is closed abruptly (e.g. `socket.destroy()`), the | ||
`'close'` event will be emitted in this phase. Otherwise it will be | ||
|
@@ -211,15 +210,15 @@ emitted via `process.nextTick()`. | |
## `setImmediate()` vs `setTimeout()` | ||
|
||
`setImmediate` and `setTimeout()` are similar, but behave in different | ||
ways depending on when they are called. | ||
ways depending on when they are called. | ||
|
||
* `setImmediate()` is designed to execute a script once the current | ||
`poll` phase completes. | ||
`poll` phase completes. | ||
* `setTimeout()` schedules a script to be run | ||
after a minimum threshold in ms has elapsed. | ||
|
||
The order in which the timers are executed will vary depending on the | ||
context in which they are called. If both are called from within the | ||
context in which they are called. If both are called from within the | ||
main module, then timing will be bound by the performance of the process | ||
(which can be impacted by other applications running on the machine). | ||
|
||
|
@@ -283,16 +282,16 @@ within an I/O cycle, independently of how many timers are present. | |
### Understanding `process.nextTick()` | ||
|
||
You may have noticed that `process.nextTick()` was not displayed in the | ||
diagram, even though its a part of the asynchronous API. This is because | ||
diagram, even though it's a part of the asynchronous API. This is because | ||
`process.nextTick()` is not technically part of the event loop. Instead, | ||
the nextTickQueue will be processed after the current operation | ||
completes, regardless of the current `phase` of the event loop. | ||
the `nextTickQueue` will be processed after the current operation | ||
completes, regardless of the current phase of the event loop. | ||
|
||
Looking back at our diagram, any time you call `process.nextTick()` in a | ||
given phase, all callbacks passed to `process.nextTick()` will be | ||
resolved before the event loop continues. This can create some bad | ||
situations because **it allows you to "starve" your I/O by making | ||
recursive `process.nextTick()` calls.** which prevents the event loop | ||
recursive `process.nextTick()` calls,** which prevents the event loop | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Small nit, but the comma probably doesn't need to be inside the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. K |
||
from reaching the `poll` phase. | ||
|
||
### Why would that be allowed? | ||
|
@@ -319,9 +318,9 @@ What we're doing is passing an error back to the user but only *after* | |
we have allowed the rest of the user's code to execute. By using | ||
`process.nextTick()` we guarantee that `apiCall()` always runs its | ||
callback *after* the rest of the user's code and *before* the event loop | ||
is allowed to proceed. To acheive this, the JS call stack is allowed to | ||
is allowed to proceed. To achieve this, the JS call stack is allowed to | ||
unwind then immediately execute the provided callback which allows a | ||
person to make recursive calls to nextTick without reaching a | ||
person to make recursive calls to `process.nextTick()` without reaching a | ||
`RangeError: Maximum call stack size exceeded from v8`. | ||
|
||
This philosophy can lead to some potentially problematic situations. | ||
|
@@ -343,21 +342,33 @@ var bar = 1; | |
``` | ||
|
||
The user defines `someAsyncApiCall()` to have an asynchronous signature, | ||
actually operates synchronously. When it is called, the callback | ||
provided to `someAsyncApiCall ()` is called in the same phase of the | ||
but it actually operates synchronously. When it is called, the callback | ||
provided to `someAsyncApiCall()` is called in the same phase of the | ||
event loop because `someAsyncApiCall()` doesn't actually do anything | ||
asynchronously. As a result, the callback tries to reference `bar` but | ||
it may not have that variable in scope yet because the script has not | ||
asynchronously. As a result, the callback tries to reference `bar` even | ||
though it may not have that variable in scope yet, because the script has not | ||
been able to run to completion. | ||
|
||
By placing it in a `process.nextTick()`, the script still has the | ||
By placing the callback in a `process.nextTick()`, the script still has the | ||
ability to run to completion, allowing all the variables, functions, | ||
etc., to be initialized prior to the callback being called. It also has | ||
etc., to be initialized prior to the callback being called. It also has | ||
the advantage of not allowing the event loop to continue. It may be | ||
useful that the user be alerted to an error before the event loop is | ||
allowed to continue. | ||
useful for the user to be alerted to an error before the event loop is | ||
allowed to continue. Here is the previous example using `process.nextTick()`: | ||
|
||
```js | ||
function someAsyncApiCall (callback) { | ||
process.nextTick(callback); | ||
}; | ||
|
||
someAsyncApiCall(() => { | ||
console.log('bar', bar); // 1 | ||
}); | ||
|
||
var bar = 1; | ||
``` | ||
|
||
A real world example in node would be: | ||
Here's another real world example: | ||
|
||
```js | ||
const server = net.createServer(() => {}).listen(8080); | ||
|
@@ -367,10 +378,10 @@ server.on('listening', () => {}); | |
|
||
When only a port is passed the port is bound immediately. So the | ||
`'listening'` callback could be called immediately. Problem is that the | ||
`.on('listening')` will not have been set by that time. | ||
`.on('listening')` will not have been set by that time. | ||
|
||
To get around this the `'listening'` event is queued in a `nextTick()` | ||
to allow the script to run to completion. Which allows the user to set | ||
to allow the script to run to completion. Which allows the user to set | ||
any event handlers they want. | ||
|
||
## `process.nextTick()` vs `setImmediate()` | ||
|
@@ -379,7 +390,7 @@ We have two calls that are similar as far as users are concerned, but | |
their names are confusing. | ||
|
||
* `process.nextTick()` fires immediately on the same phase | ||
* `setImmediate()` fires on the following iteration or 'tick' of the | ||
* `setImmediate()` fires on the following iteration or 'tick' of the | ||
event loop | ||
|
||
In essence, the names should be swapped. `process.nextTick()` fires more | ||
|
@@ -389,11 +400,11 @@ percentage of the packages on npm. Every day more new modules are being | |
added, which mean every day we wait, more potential breakages occur. | ||
While they are confusing, the names themselves won't change. | ||
|
||
*We recommend developers use `setImmediate()` in all cases because its | ||
*We recommend developers use `setImmediate()` in all cases because it's | ||
easier to reason about (and it leads to code that's compatible with a | ||
wider variety of environments, like browser JS.)* | ||
|
||
## Why use `process.nextTick()`? | ||
## Why use `process.nextTick()`? | ||
|
||
There are two main reasons: | ||
|
||
|
@@ -415,12 +426,12 @@ server.on('listening', function() { }); | |
|
||
Say that listen() is run at the beginning of the event loop, but the | ||
listening callback is placed in a `setImmediate()`. Now, unless a | ||
hostname is passed binding to the port will happen immediately. Now for | ||
hostname is passed binding to the port will happen immediately. Now for | ||
the event loop to proceed it must hit the `poll` phase, which means | ||
there is a non-zero chance that a connection could have been received | ||
there is a non-zero chance that a connection could have been received | ||
allowing the connection event to be fired before the listening event. | ||
|
||
Another example is running a function constructor that was to, say, | ||
Another example is running a function constructor that was to, say, | ||
inherit from `EventEmitter` and it wanted to call an event within the | ||
constructor: | ||
|
||
|
@@ -440,10 +451,10 @@ myEmitter.on('event', function() { | |
}); | ||
``` | ||
|
||
You can't emit an event from the constructor immediately | ||
because the script will not have processed to the point where the user | ||
assigns a callback to that event. So, within the constructor itself, | ||
you can use `process.nextTick()` to set a callback to emit the event | ||
You can't emit an event from the constructor immediately | ||
because the script will not have processed to the point where the user | ||
assigns a callback to that event. So, within the constructor itself, | ||
you can use `process.nextTick()` to set a callback to emit the event | ||
after the constructor has finished, which provides the expected results: | ||
|
||
```js | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This probably doesn't need backticks.