doc: topic blocking vs non-blocking

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: https://github.com/nodejs/node/pull/5326
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

diff --git a/doc/topics/blocking-vs-non-blocking.md b/doc/topics/blocking-vs-non-blocking.md
new file mode 100644 (file)
index 0000000..788887a
--- /dev/null
+++ b/doc/topics/blocking-vs-non-blocking.md
@@ -0,0 +1,143 @@
+# Overview of Blocking vs Non-Blocking
+
+This overview covers the difference between **blocking** and **non-blocking**
+calls in Node.js. This overview will refer to the event loop and libuv but no
+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
+network supported by [libuv](http://libuv.org/).
+
+
+## Blocking
+
+**Blocking** is when the execution of additional JavaScript in the Node.js
+process must wait until a non-JavaScript operation completes. This happens
+because the event loop is unable to continue running JavaScript while a
+**blocking** operation is occurring.
+
+In Node.js, JavaScript that exhibits poor performance due to being CPU intensive
+rather than waiting on a non-JavaScript operation, such as I/O, isn't typically
+referred to as **blocking**. Synchronous methods in the Node.js standard library
+that use libuv are the most commonly used **blocking** operations. Native
+modules may also have **blocking** methods.
+
+All of the I/O methods in the Node.js standard library provide asynchronous
+versions, which are **non-blocking**, and accept callback functions. Some
+methods also have **blocking** counterparts, which have names that end with
+`Sync`.
+
+
+## Comparing Code
+
+**Blocking** methods execute **synchronously** and **non-blocking** methods
+execute **asynchronously**.
+
+Using the File System module as an example, this is a **synchronous** file read:
+
+```js
+const fs = require('fs');
+const data = fs.readFileSync('/file.md'); // blocks here until file is read
+```
+
+And here is an equivalent **asynchronous** example:
+
+```js
+const fs = require('fs');
+fs.readFile('/file.md', (err, data) => {
+  if (err) throw err;
+});
+```
+
+The first example appears simpler than the second but has the disadvantage of
+the second line **blocking** the execution of any additional JavaScript until
+the entire file is read. Note that in the synchronous version if an error is
+thrown it will need to be caught or the process will crash. In the asynchronous
+version, it is up to the author to decide whether an error should throw as
+shown.
+
+Let's expand our example a little bit:
+
+```js
+const fs = require('fs');
+const data = fs.readFileSync('/file.md'); // blocks here until file is read
+console.log(data);
+// moreWork(); will run after console.log
+```
+
+And here is a similar, but not equivalent asynchronous example:
+
+```js
+const fs = require('fs');
+fs.readFile('/file.md', (err, data) => {
+  if (err) throw err;
+  console.log(data);
+});
+// moreWork(); will run before console.log
+```
+
+In the first example above, `console.log` will be called before `moreWork()`. In
+the second example `fs.readFile()` is **non-blocking** so JavaScript execution
+can continue and `moreWork()` will be called first. The ability to run
+`moreWork()` without waiting for the file read to complete is a key design
+choice that allows for higher throughput.
+
+
+## Concurrency and Throughput
+
+JavaScript execution in Node.js is single threaded, so concurrency refers to the
+event loop's capacity to execute JavaScript callback functions after completing
+other work. Any code that is expected to run in a concurrent manner must allow
+the event loop to continue running as non-JavaScript operations, like I/O, are
+occurring.
+
+As an example, let's consider a case where each request to a web server takes
+50ms to complete and 45ms of that 50ms is database I/O that can be done
+asychronously. Choosing **non-blocking** asynchronous operations frees up that
+45ms per request to handle other requests. This is a significant difference in
+capacity just by choosing to use **non-blocking** methods instead of
+**blocking** methods.
+
+The event loop is different than models in many other languages where additional
+threads may be created to handle concurrent work.
+
+
+## Dangers of Mixing Blocking and Non-Blocking Code
+
+There are some patterns that should be avoided when dealing with I/O. Let's look
+at an example:
+
+```js
+const fs = require('fs');
+fs.readFile('/file.md', (err, data) => {
+  if (err) throw err;
+  console.log(data);
+});
+fs.unlinkSync('/file.md');
+```
+
+In the above example, `fs.unlinkSync()` is likely to be run before
+`fs.readFile()`, which would delete `file.md` before it is actually read. A
+better way to write this that is completely **non-blocking** and guaranteed to
+execute in the correct order is:
+
+
+```js
+const fs = require('fs');
+fs.readFile('/file.md', (err, data) => {
+  if (err) throw err;
+  console.log(data);
+  fs.unlink('/file.md', (err) => {
+    if (err) throw err;
+  });
+});
+```
+
+The above places a **non-blocking** call to `fs.unlink()` within the callback of
+`fs.readFile()` which guarantees the correct order of operations.
+
+
+## Additional Resources
+
+- [libuv](http://libuv.org/)
+- [About Node.js](https://nodejs.org/en/about/)