doc: improvements to cluster.markdown copy

[jasnell]

A number of general improvements to cluster.markdown including
copyedits and revised examples

[sam-github]

"terminated normally" or just "exited" would be more consistent with child process docs

[jasnell]

@sam-github ... updated to address #4409 (comment)

[ryansobol]

The first sentence is a bit long in the tooth and hard to understand. Maybe the same thing can be said with less.

"Node.js executes JavaScript code within the context of a single-threaded event loop."

[jasnell]

@ryansobol ... fixed!

[ryansobol]

I took a stab at making the cluster introduction more approachable to beginners. I was able to consolidate three paragraphs down to two which is a win with respects to the reader quickly seeing their first code example. In addition, I tried to answer why clusters are important by first explaining the benefits and shortcomings of libuv concurrency model at a high level.

In the process, the references about child_process.fork() and IPC channels was cut. In my experience as a teacher, a newcomer wants to know three things in the beginning—what a thing is, why it's important, and how to use it. Implementation details can come later.

Anyway, feel free to use none, some, or all of it. :)

Edit: Remembered that the cluster API's primarily used for non-blocking socket I/O bound apps. While I'm sure it's also useful for CPU bound apps too, it's probably better to focus on the primary use case.

---

Node.js executes JavaScript code within the context of an event loop. Under the hood, non-blocking socket I/O runs on the main event loop thread while blocking DNS and filesystem I/O runs on a secondary thread that notifies the main thread when it's finished. This concurrency model allows a blocking I/O bound application to easily distribute work across multiple CPU cores. For more details, see the libuv project.

The cluster API allows a non-blocking I/O bound application to distribute its work across multiple CPU cores. A Node.js cluster is created when a master process forks one or more worker processes. By design, workers use the same application code as the master. Conveniently, the cluster.isMaster property determines if a running process is the master or a worker.

const cluster = require('cluster');
if (cluster.isMaster) {
  for (var i = 0; i < numCPUs; i++) {
    cluster.fork();
  }
} else {
  // Non-blocking I/O work
}

[jasnell]

Updated to use @ryansobol's wording for the intro

[jasnell]

@nodejs/documentation @sam-github @ryansobol ... would appreciate one more quick review on this before landing.

[ryansobol]

Maybe add const numCPUs = require('os').cpus().length;?

[jasnell]

@ryansobol ... thanks for the comments! I'll update shortly

[benjamingr]

Hey @jasnell are you still working on these? Need a review?

[jasnell]

@benjamingr ... yeah, I still have a few of these queued up. I plan to revisit them hopefully later this week.

[jasnell]

@benjamingr @ryansobol ... ping.. rebased and updated!
@nodejs/documentation

[stevemao]

I generally prefer let in loops but I see both var or let in the docs. (https://github.com/nodejs/node/blob/master/doc/api/buffer.markdown has both)
Excuse me if this has been brought up before.

[stevemao]

So this is not going to land?