New submission from Corbin Simpson: Hi there! While assisting somebody on #python (where manners go to die), I was consulting asyncio's documentation. Given my unfamiliarity with asyncio, I was surprised to read BaseEventLoop.call_soon()'s documented behavior: "Arrange for a callback to be called as soon as possible." [1] The question in mind is whether call_soon() waits for control to return to the event loop before calling the first callback in the queue. After all, given the documented behavior, it would not be unreasonable for call_soon() to always call callbacks immediately if no other callbacks were enqueued. I can imagine scenarios where a previous queued callback from e.g. call_soon_threadsafe() creates a callback that causes queueing behavior, but otherwise I would expect "as soon as possible" to mean "immediately". It's true that in other event loops, this kind of callback registration waits for control to return to the event loop before running callbacks. However, many event loops that I've worked with indicate that call_later() is the correct API for adding callbacks that respect the event loop. In fact, call_later(0, callback, args) looks quite a bit like the familiar Twisted callLater(0, callback, args) pattern! Additionally, there is no indication as to whether call_later() and call_soon() use the same queue. I'd like clarification on these points in the Python 3 documentation, please. I'd like to know whether call_soon() can be immediate, and whether call_soon() preempts or interleaves with call_later(). (Yes, I know that Twisted's documentation is missing this too [2] [3]. I'll get to that soon enough.) Thanks! ~ C. [1]: https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.BaseEventLo... [2]: http://twistedmatrix.com/documents/current/core/howto/time.html [3]: http://twistedmatrix.com/documents/current/api/twisted.internet.interfaces.I... ---------- assignee: docs@python components: Documentation, asyncio messages: 231180 nosy: Corbin.Simpson, docs@python, gvanrossum, haypo, yselivanov priority: normal severity: normal status: open title: asyncio: call_soon() documentation unclear on timing _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22875> _______________________________________