From 1f1eadaace0aae60e707b47beebea59e59f83898 Mon Sep 17 00:00:00 2001 From: Roger Iyengar Date: Mon, 22 Jun 2020 22:16:00 -0400 Subject: [PATCH] Improve asyncio.loop.call_soon() documentation (GH-20883) * Add a glossary entry for the term "callback" * Link to it in loop.call_soon() and in the "Concurrency and Multithreading" section Co-authored-by: Kyle Stanley (cherry picked from commit a16d6970496cae5ecab5aaea2b416a4b77527cc2) Co-authored-by: Roger Iyengar --- Doc/glossary.rst | 4 ++++ Doc/library/asyncio-dev.rst | 2 +- Doc/library/asyncio-eventloop.rst | 4 ++-- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 6189cb045049c2..e997d366777b38 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -189,6 +189,10 @@ Glossary A list of bytecode instructions can be found in the documentation for :ref:`the dis module `. + callback + A subroutine function which is passed as an argument to be executed at + some point in the future. + class A template for creating user-defined objects. Class definitions normally contain method definitions which operate on instances of the diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index ff51c4fa3b20f4..77f80671978369 100644 --- a/Doc/library/asyncio-dev.rst +++ b/Doc/library/asyncio-dev.rst @@ -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 :term:`callback` from another OS thread, the :meth:`loop.call_soon_threadsafe` method should be used. Example:: loop.call_soon_threadsafe(callback, *args) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index d60a6ce95cdd87..b1e73189a7a4cf 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -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 the *callback* :term:`callback` to be called with + *args* 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.