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

Audit/improve "don't block the event loop" and "next.tick event loop and timers" guides #4404

Closed
benjamingr opened this issue Feb 4, 2022 · 3 comments

Comments

@benjamingr
Copy link
Member

Hey,

We currently have two guides talking about how Node.js events work. It's really important to have these guides explaining the event loop and how node runs - they both would benefit from a big update for example the event loop guide starts with:

The event loop is what allows Node.js to perform non-blocking I/O operations — despite the fact that JavaScript is single-threaded — by offloading operations to the system kernel whenever possible.

JavaScript is not single threaded and it does not explain what non-blocking I/O does.


I think it's important to explain the user facing consequences of the timing of things in Node - for example from a user's point of view it is a lot more important to learn that microtasks (like nextTick/queueMicrotask and promises) get scheduled ahead of I/O all the time and it's possible to starve I/O with it.

Since these guides are so important it would be awesome if the foundation could even pay a technical writer to talk to some project people and review it.

@Trott
Copy link
Member

Trott commented Feb 4, 2022

Since these guides are so important it would be awesome if the foundation could even pay a technical writer to talk to some project people and review it.

That would get the info updated and it might not be a bad way to go. But it will be a one-time event and the two guides will go back to not being maintained at all, like all of our guides.

With the guides, I'm generally an advocate for a two step process:

  1. Find the essential Node.js-specific material in there (emphasis on essential and not merely Node.js-specific) and make sure that material is represented in the appropriate places in our API docs.
  2. Find reliable external sources that provide the other information and replace the guides with links to those sources.

We've done this in https://nodejs.org/en/knowledge/javascript-conventions/what-is-the-arguments-object/ and I'd love to see it elsewhere.

@benjamingr
Copy link
Member Author

Find reliable external sources that provide the other information and replace the guides with links to those sources.

@goldbergyoni is that something you'd be interested in maintaining (for these guides)?

@samaianikasi1228

This comment was marked as spam.

@ovflowd ovflowd closed this as completed Mar 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants