doc: topic blocking vs non-blocking by jrit · Pull Request #5326 · nodejs/node · GitHub

The need for an overview of blocking vs non-blocking was
identified in the docs WG Q1 roadmap. As there are several
topics also pending creation, this one tries to hit the correct
level of detail based on completion of the others. One
which is referenced is
https://github.com/nodejs/node/pull/4936/files and URLs
within this PR need to change based on where that will land
on the node website.

Any reviews appreciated, thank you.

@chrisdickinson @techjeffharris

The need for an overview of blocking vs non-blocking was identified in the docs WG Q1 roadmap. As there are several topics also pending creation, this one tries to hit the correct level of detail based on completion of the others. One which is referenced is https://github.com/nodejs/node/pull/4936/files and URLs within this PR need to change based on where that will land on the node website.

nit: it's not just limited to i/o operations

Would it be more appropriate to just take I/O out of the sentence or is there a better way to explain this? My goal is to distinguish that the process is waiting not just because JavaScript is executing.

Leaving the I/O in there is fine since that's the most likely case. It may just be worthwhile indicating that non-I/O operations can cause it to bog down as well. crypto operations, for instance.

I'm not sure you consider things like waiting for synchronization ( a lock for instance) I/O.

generally LGTM. /cc @nodejs/documentation

Could you refer here always to fs.unlink(), fs.readFile() for consistency?

minus nits LGTM

Could we highlight: put this in Bold this is a synchronous file read -> this is a synchronous file read
then highlight: equivalent asynchronous example to equivalent asynchronous example
I think it's easier to notice.

🐢 LGTM

LGTM too, minus the nits.

technically any native module can do any sort of blocking - it doesn't have to be through libuv but I guess that absolute correctness isn't a goal here.

provides clarification based on PR feedback

Thank you for the feedback everyone. Aside from specific formatting, the biggest issue seemed to be referring to I/O in a way that wasn't technically accurate. I tried to address that by rewriting some of the ## Blocking section and referring more directly to "non-JavaScript" instead of "I/O". I hope this will read more accurately without becoming unnecessarily technical.

This is quoting, right? Source is missing.

Not a quote, just a note

Well, PRs are WIP items. So quoting them is a not a good idea I think.

This shouldn't be merged with this like this, my issue is that there should be a reference to the other topic on nodejs.org but the PR hasn't even been merged into master yet. This was mentioned above when the PR was opened.

additional clarifications

After one read LGTM, sans the link to #4936. I'll read through it again later to look for nits. Great Job!

Generally LGTM with the nits addressed.

I'm +1 on merging and then improving it later - so LGTM.

LGTM

Removed reference to an open PR which was blocking this, it makes more sense to add cross linking at a later date when relevant topics have been merged. Also removed reference to specific percent performance change that had objections from @jasnell and others

This should be in a good place to merge now. Thanks everyone for your feedback.

LGTM

LGTM too.

Landed in 5f1eb43 - thanks!

The need for an overview of blocking vs non-blocking was identified in the docs WG Q1 roadmap. As there are several topics also pending creation, this one tries to hit the correct level of detail based on completion of the others. One which is referenced is https://github.com/nodejs/node/pull/4936/files and URLs within this PR need to change based on where that will land on the node website. PR-URL: #5326 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

mscdex added the doc Issues and PRs related to the documentations. label Feb 19, 2016

jasnell reviewed Feb 19, 2016
View reviewed changes

eljefedelrodeodeljefe reviewed Feb 19, 2016
View reviewed changes

Knighton910 reviewed Feb 19, 2016
View reviewed changes

jasnell added the lts-watch-v4.x label Feb 19, 2016

benjamingr reviewed Feb 20, 2016
View reviewed changes

eljefedelrodeodeljefe mentioned this pull request Feb 20, 2016

Create overview for "Blocking vs. non-blocking" nodejs/docs#77

Closed

doc: revise blocking vs non-blocking

4f73022

provides clarification based on PR feedback

thefourtheye reviewed Feb 21, 2016
View reviewed changes

doc: revise blocking vs non-blocking

4178660

additional clarifications

remove refs to PR and percent gain

d215d63

benjamingr closed this Mar 19, 2016

MylesBorins added land-on-v4.x and removed lts-watch-v4.x labels Mar 21, 2016

Fishrock123 mentioned this pull request Mar 22, 2016

v5.9.1 Release Proposal #5831

Merged

eljefedelrodeodeljefe mentioned this pull request May 4, 2016

Doc: Adding guide on Timers nodejs/nodejs.org#718

Closed

+              Blocking is when the execution of additional JavaScript in the Node.js process
+              must wait until an I/O operation completes. Blocking may occur when using any of
+              the synchronous I/O methods in the Node.js standard library that use libuv. Use
+              of blocking methods prevents the event loop from doing additional work while

+              The event loop is different than models in many other languages where additional
+              threads may be created to handle concurrent work. For an introduction to the
+              event loop see [Overview of the Event Loop, Timers, and
+              `process.nextTick()`](https://github.com/nodejs/node/pull/4936)

+              ```
+              The above places a non-blocking call to `unlink` within the callback of
+              `readFile` which guarantees the correct order of operations.

		also implement blocking methods, which usually have names that end with `Sync`.


		## Comparing Code

+              prior knowledge of those topics is required. Readers are assumed to have a
+              basic understanding of the JavaScript language and Node.js callback pattern.
+              > "I/O" refers primarily to interaction with the system's disk and

doc: topic blocking vs non-blocking by jrit · Pull Request #5326 · nodejs/node · GitHub

Uh oh!

Uh oh!

doc: topic blocking vs non-blocking - #5326

doc: topic blocking vs non-blocking#5326jrit wants to merge 4 commits intonodejs:masternodejs/node:masterfrom jrit:doc-blockingjrit/node:doc-blockingCopy head branch name to clipboard

Conversation

jrit commented Feb 19, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell commented Feb 19, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eljefedelrodeodeljefe commented Feb 19, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Knighton910 commented Feb 19, 2016

Uh oh!

Qard commented Feb 20, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jrit commented Feb 21, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

techjeffharris commented Feb 24, 2016

Uh oh!

jasnell commented Mar 2, 2016

Uh oh!

benjamingr commented Mar 3, 2016

Uh oh!

laosb commented Mar 5, 2016

Uh oh!

jrit commented Mar 17, 2016

Uh oh!

jasnell commented Mar 17, 2016

Uh oh!

Qard commented Mar 17, 2016

Uh oh!

benjamingr commented Mar 19, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

13 participants

doc: topic blocking vs non-blocking#5326
jrit wants to merge 4 commits into
nodejs:masterfrom
jrit:doc-blocking