[New-bugs-announce] [issue22875] asyncio: call_soon() documentation unclear on timing

[Corbin Simpson]

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.BaseEventLoop.call_soon
[2]: http://twistedmatrix.com/documents/current/core/howto/time.html
[3]: http://twistedmatrix.com/documents/current/api/twisted.internet.interfaces.IReactorTime.html#callLater

----------
assignee: docs at python
components: Documentation, asyncio
messages: 231180
nosy: Corbin.Simpson, docs at python, gvanrossum, haypo, yselivanov
priority: normal
severity: normal
status: open
title: asyncio: call_soon() documentation unclear on timing

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue22875>
_______________________________________