document more precise semantics for uv_async_send

[libuv]

document more precise semantics for uv_async_send

[saghul]

Is that indeed a possible sequence of execution? If so, I suggest replacing the text "within a short period of time" with "for the given async handle", making it clearer that the strongest guarantee made is that the callback will be executed once, ever.

No. At least on Unix, uv_async_send will mark the handle as "pending" using atomic ops and when the callback is executed it's unmarked. As a result, if the callback was called, next time you call uv_async_send you'll get the callback called again. If you call uv_async_send 5 times in a row, however, it's only guaranteed that your callback is called once.

If uv_async_send actually makes stronger guarantees, then please document them precisely. For example, a useful stronger guarantee would be that the callback is executed consistent with a model where uv_async_send atomically sets a "needs execution" flag, and the event loop atomically resets this flag before running the callback. That would rule out the sequence of execution above.

Async handles don't have strong guarantees, that's the whole point. People have used async handles to try to send data from one thread to the loop thread by attaching a void* data pointer to the request and calling uv_async_send. This doesn't work and won't work for the reasons I mention above. The only guarantee is that your callback will be called once, but once the callback is called the story begins again.

If you feel this can be fursther clarified please do send a PR with a fix for the documentation.

[txdv]

Can't we just try to make it issue as many callbacks as there were function calls?

People are constantly confused.

[saghul]

@txdv that's uv_callback. For 1.x this is what we have. Even if we could make it issue the right amount of callbacks, it wouldn't help much because you cannot attach data to them anyway. In uv_callback I tried to solve both problems.

[txdv]

People have used async handles to try to send data from one thread to the loop thread by attaching a void* data pointer to the request and calling uv_async_send

His description mislead me a bit. I don't understand why people have so much trouble with that. Maybe we should add an object which wraps async and provides them the functionality so they stop with these posts.

[saghul]

@jfirebaugh can you have a look at #122 ?