Skip to content
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

doc: expand documentation for process.exit() #6410

Closed
wants to merge 2 commits into from

Conversation

jasnell
Copy link
Member

@jasnell jasnell commented Apr 27, 2016

Checklist
  • documentation is changed or added
  • the commit message follows commit guidelines
Affected core subsystem(s)

doc (process)

Description of change

The fact that process.exit() interrupts pending async operations such as non-blocking i/o is becoming a bit more pronounced with the recent libuv update. This commit expands the documentation for process.exit() to explain clearly how it affects async operations.

@jasnell jasnell added doc Issues and PRs related to the documentations. process Issues and PRs related to the process subsystem. labels Apr 27, 2016
@ChALkeR
Copy link
Member

ChALkeR commented Apr 27, 2016

LGTM

'success' code `0`.
* `code` {Integer} The exit code. Defaults to `0`.

The `process.exit()` methods instructs Node.js to terminate the process as
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should "methods" be singular?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

method

@cjihrig
Copy link
Contributor

cjihrig commented Apr 27, 2016

LGTM with a couple comments.

It is important to note that calling `process.exit()` will force the process to
exit as quickly as possible *even if there are still asynchronous operations
pending* in the event loop, *including* i/o operations to `process.stdout` and
`process.stderr`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's where it gets weird: those stdio operations are actually synchronous on the node layer, sometimes full synchronous, sometimes not at an os/libuv level.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep. Tried to capture some of those nuances in my first edit but gave up because it ended up being too confusing. Open to wording that works better.

@Fishrock123
Copy link
Contributor

Additional note that I'm not sure fits in: It's actually "safer" to exit the process by throwing.

The fact that process.exit() interrupts pending async operations
such as non-blocking i/o is becoming a bit more pronounced with
the recent libuv update. This commit expands the documentation
for `process.exit()` to explain clearly how it affects async
operations.
@jasnell
Copy link
Member Author

jasnell commented Apr 28, 2016

@cjihrig @Fishrock123 ... updated to address nits

@eljefedelrodeodeljefe
Copy link
Contributor

LGTM, very good. I hope this will clarified through API rather in the future, as per linked discussions.

@Qix-
Copy link

Qix- commented Apr 28, 2016

Lgtm, sharing the same sentiments as @eljefedelrodeodeljefe.

@kzc
Copy link

kzc commented Apr 28, 2016

Should add a description of how to correctly flush/drain stdout/stderr if process.exit() must be used.

@jasnell
Copy link
Member Author

jasnell commented Apr 29, 2016

@kzc ... do you recommend a particular approach for that example?

@kzc
Copy link

kzc commented Apr 29, 2016

@kzc ... do you recommend a particular approach for that example?

@jasnell I'd have to recommend the use of node-exit as it is widely used and I've tested it to work on node versions 0.10.x - 6.0.0 on Mac and Linux. I assume it works on Windows as that seems to be why it was specifically created. (Edit: no longer recommended - see #6410 (comment))

https://www.npmjs.com/package/exit

Some might argue that it's less than ideal, but it was created to fill a need. People want to call process.exit() and expect to have stdout/stderr flushed - rightly or wrongly.

@eljefedelrodeodeljefe
Copy link
Contributor

@kzc sorry, but we cannot do this. Hints to userland packages are really rare. Also the way they do it is not advisable. Please just wait for resolutions around process.exit().

Since you haven't brought up an example, I would say this PR is good to merge.

@kzc
Copy link

kzc commented Apr 29, 2016

Then make an equivalent example not citing this third party user land package that drains stdout and stderr. This is a legitimate concern and is the obvious question people ask when they use process.exit.

Edit: There's a reason why node-exit has had 3.5 million downloads in the last month. To workaround this very issue.

@jasnell
Copy link
Member Author

jasnell commented Apr 29, 2016

@kzc ... my preference would be to go ahead and get this change landed as is then add an example of stdout/stderr draining later once we're a bit more settled on the right approach. Fair?

@kzc
Copy link

kzc commented Apr 29, 2016

@jasnell Cool.

@jasnell
Copy link
Member Author

jasnell commented Apr 29, 2016

@ChALkeR @cjihrig ... still LGTY?

@cjihrig
Copy link
Contributor

cjihrig commented Apr 29, 2016

Yep.

jasnell added a commit that referenced this pull request Apr 29, 2016
The fact that process.exit() interrupts pending async operations
such as non-blocking i/o is becoming a bit more pronounced with
the recent libuv update. This commit expands the documentation
for `process.exit()` to explain clearly how it affects async
operations.

PR-URL: #6410
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Robert Lindstaedt <[email protected]>
@jasnell
Copy link
Member Author

jasnell commented Apr 29, 2016

Landed in c2bbfe2

@kzc
Copy link

kzc commented Apr 30, 2016

I just studied the implementation of the third party node-exit module. Contrary to my prior remarks, it is not advisable for it to be used as a replacement for process.exit to flush stdout and stderr.

It only does partial stdout/stderr flushing at the best of times, and at worse it simply disables writes to stdout/stderr, and then it returns and allows program execution to continue - which can have bad consequences. Because node-exit happens to stop output to stdio and it installs an on "exit" handler which calls process.exit() with the correct exit code, it had me fooled in initial testing.

I do not believe it is possible to fully flush any stream synchronously immediately prior to calling process.exit() as node is currently implemented.

Fishrock123 pushed a commit that referenced this pull request May 4, 2016
The fact that process.exit() interrupts pending async operations
such as non-blocking i/o is becoming a bit more pronounced with
the recent libuv update. This commit expands the documentation
for `process.exit()` to explain clearly how it affects async
operations.

PR-URL: #6410
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Robert Lindstaedt <[email protected]>
joelostrowski pushed a commit to joelostrowski/node that referenced this pull request May 4, 2016
The fact that process.exit() interrupts pending async operations
such as non-blocking i/o is becoming a bit more pronounced with
the recent libuv update. This commit expands the documentation
for `process.exit()` to explain clearly how it affects async
operations.

PR-URL: nodejs#6410
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Robert Lindstaedt <[email protected]>
@MylesBorins
Copy link
Contributor

This does not land cleanly on v4.x

if someone would like to manually backport let me know

@MylesBorins
Copy link
Contributor

ping @jasnell

@kzc
Copy link

kzc commented Jun 1, 2016

In light of #6867 this sentence in the doc PR 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().

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. process Issues and PRs related to the process subsystem.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants