[Python-checkins] [3.11] gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst (GH-100270) (#102006)
gvanrossum
webhook-mailer at python.org
Sat Feb 18 18:57:25 EST 2023
https://github.com/python/cpython/commit/5220c2df9eb5bf0333b2bdfceea98ec80a140fd6
commit: 5220c2df9eb5bf0333b2bdfceea98ec80a140fd6
branch: 3.11
author: Brian Skinn <brian.skinn at gmail.com>
committer: gvanrossum <gvanrossum at gmail.com>
date: 2023-02-18T15:57:06-08:00
summary:
[3.11] gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst (GH-100270) (#102006)
Note: the `timeout` parameter was not added until 3.12.
(cherry picked from commit c4de6b1d52304a0a9cdfafc1dad5098993710404)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach at Gerlach.CAM>
Co-authored-by: Terry Jan Reedy <tjreedy at udel.edu>.
Co-authored-by: Brian Skinn <brian.skinn at gmail.com>
files:
M Doc/library/asyncio-eventloop.rst
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index c7343826be3f..020d8a0ca8a8 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -192,12 +192,15 @@ Running and stopping the loop
.. coroutinemethod:: loop.shutdown_default_executor()
Schedule the closure of the default executor and wait for it to join all of
- the threads in the :class:`ThreadPoolExecutor`. After calling this method, a
- :exc:`RuntimeError` will be raised if :meth:`loop.run_in_executor` is called
- while using the default executor.
+ the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`.
+ Once this method has been called,
+ using the default executor with :meth:`loop.run_in_executor`
+ will raise a :exc:`RuntimeError`.
- Note that there is no need to call this function when
- :func:`asyncio.run` is used.
+ .. note::
+
+ Do not call this method when using :func:`asyncio.run`,
+ as the latter handles default executor shutdown automatically.
.. versionadded:: 3.9
@@ -210,22 +213,23 @@ Scheduling callbacks
Schedule the *callback* :term:`callback` to be called with
*args* arguments at the next iteration of the event loop.
+ Return an instance of :class:`asyncio.Handle`,
+ which can be used later to cancel the callback.
+
Callbacks are called in the order in which they are registered.
Each callback will be called exactly once.
- An optional keyword-only *context* argument allows specifying a
+ The optional keyword-only *context* argument specifies a
custom :class:`contextvars.Context` for the *callback* to run in.
- The current context is used when no *context* is provided.
-
- An instance of :class:`asyncio.Handle` is returned, which can be
- used later to cancel the callback.
+ Callbacks use the current context when no *context* is provided.
- This method is not thread-safe.
+ Unlike :meth:`call_soon_threadsafe`, this method is not thread-safe.
.. method:: loop.call_soon_threadsafe(callback, *args, context=None)
- A thread-safe variant of :meth:`call_soon`. Must be used to
- schedule callbacks *from another thread*.
+ A thread-safe variant of :meth:`call_soon`. When scheduling callbacks from
+ another thread, this function *must* be used, since :meth:`call_soon` is not
+ thread-safe.
Raises :exc:`RuntimeError` if called on a loop that's been closed.
This can happen on a secondary thread when the main application is
More information about the Python-checkins
mailing list