diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index aed312bfec06a8..7ed597a5057057 100644 --- a/Doc/library/asyncio-dev.rst +++ b/Doc/library/asyncio-dev.rst @@ -109,7 +109,7 @@ that the event loop runs in. There is currently no way to schedule coroutines or callbacks directly from a different process (such as one started with -:mod:`multiprocessing`). The :ref:`Event Loop Methods ` +:mod:`multiprocessing`). The :ref:`asyncio-event-loop-methods` section lists APIs that can read from pipes and watch file descriptors without blocking the event loop. In addition, asyncio's :ref:`Subprocess ` APIs provide a way to start a diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 0e66b3e7a6c576..a6250be6be55fa 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1,6 +1,8 @@ .. currentmodule:: asyncio +.. _asyncio-event-loop: + ========== Event Loop ========== @@ -92,7 +94,7 @@ This documentation page contains the following sections: loop APIs. -.. _asyncio-event-loop: +.. _asyncio-event-loop-methods: Event Loop Methods ================== @@ -1498,6 +1500,7 @@ Do not instantiate the class directly. .. _asyncio-event-loops: +.. _asyncio-event-loop-implementations: Event Loop Implementations ========================== @@ -1544,7 +1547,7 @@ on Unix and :class:`ProactorEventLoop` on Windows. Abstract base class for asyncio-compliant event loops. - The :ref:`Event Loop Methods ` section lists all + The :ref:`asyncio-event-loop-methods` section lists all methods that an alternative implementation of ``AbstractEventLoop`` should have defined. diff --git a/Doc/library/asyncio-llapi-index.rst b/Doc/library/asyncio-llapi-index.rst index 0315d2e3d37d95..63ab1483e1fbd2 100644 --- a/Doc/library/asyncio-llapi-index.rst +++ b/Doc/library/asyncio-llapi-index.rst @@ -37,7 +37,7 @@ Event Loop Methods ================== See also the main documentation section about the -:ref:`event loop methods `. +:ref:`asyncio-event-loop-methods`. .. rubric:: Lifecycle .. list-table:: diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst index ef6a0588506b52..a73e99510f0b4e 100644 --- a/Doc/library/asyncio-policy.rst +++ b/Doc/library/asyncio-policy.rst @@ -7,22 +7,29 @@ Policies ======== -An event loop policy is a global per-process object that controls -the management of the event loop. Each event loop has a default -policy, which can be changed and customized using the policy API. - -A policy defines the notion of *context* and manages a -separate event loop per context. The default policy -defines *context* to be the current thread. - -By using a custom event loop policy, the behavior of -:func:`get_event_loop`, :func:`set_event_loop`, and -:func:`new_event_loop` functions can be customized. +An event loop policy is a global (per-interpreter) object +used to get and set the current :ref:`event loop `, +as well as create new event loops. +The default policy can be :ref:`replaced ` with +:ref:`built-in alternatives ` +to use different event loop implementations, +or substituted by a :ref:`custom policy ` +that can override these behaviors. + +The :ref:`policy object ` +gets and sets a separate event loop per *context*. +This is per-thread by default, +though custom policies could define *context* differently. + +Custom event loop policies can control the behavior of +:func:`get_event_loop`, :func:`set_event_loop`, and :func:`new_event_loop`. Policy objects should implement the APIs defined in the :class:`AbstractEventLoopPolicy` abstract base class. +.. _asyncio-policy-get-set: + Getting and Setting the Policy ============================== @@ -40,6 +47,8 @@ for the current process: If *policy* is set to ``None``, the default policy is restored. +.. _asyncio-policy-objects: + Policy Objects ============== @@ -86,6 +95,8 @@ The abstract event loop policy base class is defined as follows: This function is Unix specific. +.. _asyncio-policy-builtin: + asyncio ships with the following built-in policies: @@ -117,6 +128,7 @@ asyncio ships with the following built-in policies: .. availability:: Windows. + .. _asyncio-watchers: Process Watchers @@ -270,6 +282,8 @@ implementation used by the asyncio event loop: .. versionadded:: 3.9 +.. _asyncio-custom-policies: + Custom Policies ===============