process, doc: discourage use of process.exit() for control flow in docs

[eljefedelrodeodeljefe]

Userland library authors have a pattern for CLIs that has lead to various issues during the introduction of v6. We had a heated discussion that I would summarize as: the below pattern should have been used in like this, since it actually never ensured to deliver what it promised; but core has a historic responsibility of not breaking such widely adopted patterns.

process.on('exit', () => {
    // do some post action here later
})

function doSomething() {
  for (var i = 0; i < 1000; i++) {
    process.stdout.write('some result' + i + '\n')
  }
  // decide that the execution of the CLI should end here
  process.exit()
}

The problem with this that stdout doesn't get flushed on process.exit(), resulting in not all all 1000 calls being printed. This became apparent in v6. Eventually this calls exit(3). In any good c++ practice exit(3) is discouraged, since functions scopes are not guaranteed to unwind properly.

Imo, authors should at be just return from functions, from top scope, or use proper event emitters.

Someone could open a doc PR.

Ref: #6980, #6456

cc @Fishrock123

[mscdex]

Won't this be irrelevant once the stdio issues are fixed?

[Fishrock123]

Won't this be irrelevant once the stdio issues are fixed?

Yes and this is not really a feasible solution for the problem is question.

[kzc]

While we're on the subject of docs about process.exit(), this statement is incorrect:

"If it is necessary to terminate the Node.js process due to an error condition, throwing an uncaught error and allowing the process to terminate accordingly is safer than calling process.exit()."
https://nodejs.org/dist/latest-v6.x/docs/api/process.html#process_process_exit_code

Throwing uncaught exceptions actually have the same problem as process.exit().

See: Missing or truncated error message #6867

[vkurchatkin]

@kzc so what's incorrect? It says that it's safer, not that it doesn't truncate stdout

[rvagg]

I discovered recently that standard turns on the ESLint rule that rejects return from the top level (I didn't realise there was a rule, it has me puzzled tbh, cause it makes perfect sense in CJS). The workaround when I was converting a project to use standard was to put in a process.exit(). I bet there's more than a few folks that will be wedged by this.

[kzc]

so what's incorrect? It says that it's safer, not that it doesn't truncate stdout

I don't know how to respond to such a statement. What does safer mean then?

Node is the only programming environment I know that cannot guarantee outputting to stdout/stderr in the event of an uncaught exception or exit. It's a glaring problem.

[jasnell]

@eljefedelrodeodeljefe ... some detail about this was added to the docs already. See https://nodejs.org/dist/latest-v6.x/docs/api/process.html#process_process_exit_code

[jasnell]

Closing as I believe there's nothing else to do. Can reopen if necessary