Skip to content

Improve asyncio.loop.call_soon() documentation #20883

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Jun 23, 2020
Merged

Improve asyncio.loop.call_soon() documentation #20883

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
8ffedc3
Update asyncio-eventloop.rst
akindofyoga Jun 15, 2020
305ad6f
Update asyncio-eventloop.rst
akindofyoga Jun 15, 2020
084bbc5
Update asyncio-eventloop.rst
akindofyoga Jun 15, 2020
97b04a3
Update asyncio-eventloop.rst
akindofyoga Jun 15, 2020
d1a435a
Update asyncio-eventloop.rst
akindofyoga Jun 19, 2020
36936b6
Update asyncio-dev.rst
akindofyoga Jun 19, 2020
bf275d3
Update asyncio-dev.rst
akindofyoga Jun 19, 2020
1da8579
Update asyncio-eventloop.rst
akindofyoga Jun 19, 2020
f436584
Update glossary.rst
akindofyoga Jun 19, 2020
f5b7a7e
Update asyncio-eventloop.rst
akindofyoga Jun 19, 2020
57a50e4
Update asyncio-dev.rst
akindofyoga Jun 19, 2020
1697900
Update asyncio-dev.rst
akindofyoga Jun 19, 2020
61dc896
Update asyncio-eventloop.rst
akindofyoga Jun 19, 2020
ec4e0c6
Fix trailing whitespace error
akindofyoga Jun 19, 2020
fce21c7
Update Doc/library/asyncio-dev.rst
akindofyoga Jun 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Doc/library/asyncio-dev.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ event loop, no other Tasks can run in the same thread. When a Task
executes an ``await`` expression, the running Task gets suspended, and
the event loop executes the next Task.

To schedule a callback from a different OS thread, the
To schedule a synchronous callback from a different OS thread, the
:meth:`loop.call_soon_threadsafe` method should be used. Example::

loop.call_soon_threadsafe(callback, *args)
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/asyncio-eventloop.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,8 +191,8 @@ Scheduling callbacks

.. method:: loop.call_soon(callback, *args, context=None)

Schedule a *callback* to be called with *args* arguments at
the next iteration of the event loop.
Schedule a synchronous *callback* to be called with *args*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I think this is a substantial improvement over the previous iteration, I would very much prefer to explain that callbacks are subroutine/non-coroutine functions in the Python glossary for "callback", as it universally applies to anything that uses the term in the python docs (including several other areas in the asyncio docs). So rather than repeating it every time we mention callbacks, I think it makes more sense to clarify it in the glossary definition and link to there.

Copy link
Contributor Author

@akindofyoga akindofyoga Jun 19, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for taking the time to write out the detailed explanation above! I really appreciate it and it was very helpful. Indeed, I think specifying subroutine function, rather than just function would fix the ambiguity for me. Would this pull request be a good place for me to add that to the glossary and link it in these docs? Or should I define coroutine in the glossary in a separate PR?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I think that "synchronous callback" might be a bit misleading or cause some confusion, as a callback can definitely be asynchronous depending on how it is used, such as with Future.add_done_callback(). The function itself passed as a callback is not a coroutine/"async def" function and might be considered "synchronous" in that sense, but the operation is asynchronous since it is happening out of order from the main "flow" of the program.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for taking the time to write out the detailed explanation above! I really appreciate it and it was very helpful.

No problem, I'm glad to hear it was helpful. :-)

Indeed, I think specifying subroutine function, rather than just function would fix the ambiguity for me. Would this pull request be a good place for me to add that to the glossary and link it in these docs? Or should I define coroutine in the glossary in a separate PR?

Either way works, but it would probably be easier to do it in the same PR. Just make sure to avoid anything that would require a force-push, since it could overwrite the history of the PR and remove some of the review comments (which loses some context for anyone looking in the future).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. I added a glossary definition for callback and referenced it from asyncio-eventloop and asyncio-dev.

arguments at the next iteration of the event loop.

Callbacks are called in the order in which they are registered.
Each callback will be called exactly once.
Expand Down