new topic: asynchronous programming

[drewfish]

I would like to attempt a first version of the guidetopic to asynchronous programming.

The intended audience is javascript programmers new to node.js.

This doc would probably live at src/topics/async.md.

I'm thinking of the following rough outline:

• what is async programming
  • something about function returning early, results available later
• why async is done in node.js
  • something about servers and requests
• considerations for async programming
  • something about the event loop
  • something about concurrent in-flight requests (and how that affects use of global resources)
  • something about exceptions and stack traces
• async approach: callbacks
  • short intro
  • link to the callback topic
  • mention and then link to events
  • mention and then link to streams
• async approach: promises
  • short intro
  • link to the promises topic
• async approach: ES7 async/await
  • short intro
  • link to the async/await topic
• when synchronous is OK
  • e.g. CLIs

[drewfish]

It occurred to me that there's another type of async programming: polling. (For example, startWork(); while (!resultsAvailable()) { do other stuff } results = getResults().) It's very uncommon in node.js programming and so would probably just confuse new users.

[drewfish]

Since we currently have neither the the callback topic, nor promises topic, I'll probably include a small placeholder description and links to guides on the internet. Once we have these topics we can revise this doc to leverage the topic docs to describe the material.

[chrisdickinson]

Sounds good! The outline seems a bit more like a topic doc than a guide doc — but it could go either way depending on how the document is written; either way, it would be a valuable addition!

[drewfish]

Hmmm... which do you think would best serve the community, topic or guide?

If this should be a guide, what might a guide outline look like?

[chrisdickinson]

Usually a guide has the reader build something — a little webserver, or CLI — and explains the concept it's trying to convey using examples from the readers experience with that code. Guides are great for introducing new concepts in a comfortable way, by letting the reader "simulate" the process of what development will be like using those concepts. Django's getting started guide is a great example of this, though it doesn't necessarily have to be aimed at beginners.

Guides aren't a great place for "deep dive" information, though — they have to link off to topic docs to handle anything that's fairly intricate. Pulling from Django again, in this tutorial it's noted that to continue the reader will have to have pip available. Instead of detailing how to get pip in the guide, it links to the other topic document.

Eventually / ideally we ought to have both a guide and a topic doc on this concept to help folks reason about async programming in Node.

[drewfish]

Got it, thanks. I think I was thinking more of a topic, so I'll attempt that.

[Trott]

Closing as this repository is dormant and likely to be archived soon. If this is still an issue, feel free to open it as an issue on the main node repository.