Make sure it's super clear that async != threading

[jwatzman]

There has been lots of confusion on this point. See, e.g., this SO question: http://stackoverflow.com/a/32937733/3395144

There's a brief discussion of this in the current draft but I think there is still room for improvement. A paragraph discussing this point might be worth it, and I'm especially worried about this sentence:

It allows code that utilizes the async infrastructure to cede CPU time to one another in an explicit and knowing fashion.

This is not typically true; you're going and doing something else instead of blocking on IO, which is not "CPU time" (and the "something else" is probably more IO). Even when it's technically true, when you're busy-waiting, it still gives the wrong impression.

Sorry to nitpick, this is just such a common confusion and such a core feature I think it's worth spending a good bit of time to get this perfect.

[jwatzman]

The curl example is a good one, though the thing to emphasize is that you started another IO operation while waiting on the first, so both could run at the same time. Nothing to do with CPU time -- it's all about IO latency.

[jwatzman]

There was some discussion of this in the SO chat room too. Joe Watkins pointed out that this sentence is also problematic, and I agree:

While not true multithreading, this is the next best thing.

We need to be super super careful about the threading vs async thing.

I think Joe had some other points; I linked him here so he may weigh in himself.

[krakjoe]

It doesn't seem productive to pick apart the document and point out the problems in almost every sentence, rather is seems productive to suggest an alternative approach ... so I'll do that ...

The document starts out by confusing asynchronous and parallel concurrency, lumping them together, calling one "the next best thing" to the other. This is the wrong way to avoid confusion, I can see the temptation because people generally understand what is meant by parallel (it's a normal human word), so metaphorically describing asynchronous code as parallel "because they are more or less the same", and "they are executed at the same time" is easily done.

Proper use of async/await is predicated primarily on the understanding of what asynchronous actually means, and secondarily the understanding that asynchronous does not mean parallel.

I would suggest the document starts out with a clear description of what asynchronous and parallel concurrency are.

It's quite difficult to explain these patterns in words that everyone will understand, that will translate to any language.

I've previously used the images and terse explanations below to great effect, permission granted to use them, or be inspired by them.

They are accompanied by words like "Imagine you have three distinct tasks to execute, the nature of the tasks is unimportant for the explanation ..."

Synchronous Execution Start out somewhere familiar, this is normal PHP/Hack/whatever code ...
Asynchronous Execution Asynchronous concurrency means the tasks are executed concurrently with respect to each other by interleaving instructions for the tasks.
Parallel Execution Parallel concurrency means tasks are executed concurrently with respect to time by using more than one thread of execution.

What will stick in the readers mind is the patterns therein, and what we mean by concurrency in each case.

At this point, the reader clearly knows that asynchronous and parallel mean different things. Now is the time to tell the reader that what Hack has, is support for asynchronous concurrency in the form of async/await.

At this point the reader knows what hack has, and what pattern it uses; The margin for misunderstanding is surely very thin, but it's still there.

So go on to expound the best use case for asynchronous concurrency, in non-blocking I/O, carefully choosing your words, making clear that blocking operations still block, but non-blocking operations eliminate instructions that would otherwise tell a CPU to wait.

I'd be happy to have a hand in rewriting the document, if that is desirable ...

[JoelMarcey]

Thanks for the feedback @jwatzman and @krakjoe. Yes, I indeed want to get this section as correct as possible since I believe async to be one of the greatest selling features for HHVM.

@krakjoe I will definitely use some of your ideas. Thanks. If you want to send a pull request, that would be great too.

I like the diagrams in the current version; I think they convey what is going on pretty well. @krakjoe Your diagrams would also be a nice benefit too for further understanding.

The recently released Hack and HHVM book has a paragraph that looks like:

Like PHP, Hack doesn’t support multithreading, so web apps in Hack need some other form of multitasking. That’s the purpose of async. It offers a way to implement cooperative multitasking, in which tasks voluntarily and explicitly cede the CPU to one another. The opposite is preemptive multitasking, in which tasks are forcibly interrupted by the task manager. Cooperative multitasking has several advantages over preemptive multitasking. In the preemptive model, concurrency safety has to be pervasive; you have to protect critical sections and synchronize access to shared memory. In cooperative multitasking, none of that applies. Because each task gets to control when it yields to other tasks, it doesn’t have to go out of its way to protect critical sections: all it has to do is avoid breaking them. Async provides syntax for giving up the CPU to other async tasks, as well as infrastructure within HHVM (the scheduler) that manages the cooperative multitasking, deciding which async tasks to run and when.

Is that description better; I thought I tried to convey async in the same vain.

cc @oyamauchi

[JoelMarcey]

Thanks @jwatzman and @krakjoe!!

I have made changes based on your suggestions (thanks for the images @krakjoe) and added an item to our new FAQ too.

Let me know if this is better.