gh-96377: Update asyncio policy doc intro paras to be clear and accurate (#97603)

Also fix up some cross-references in the asyncio docs.
This commit is contained in:
C.A.M. Gerlach 2022-09-27 18:47:14 -05:00 committed by GitHub
parent aab01e3524
commit cc0f3a10f0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 30 additions and 13 deletions

View file

@ -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.
An event loop policy is a global (per-interpreter) object
used to get and set the current :ref:`event loop <asyncio-event-loop>`,
as well as create new event loops.
The default policy can be :ref:`replaced <asyncio-policy-get-set>` with
:ref:`built-in alternatives <asyncio-policy-builtin>`
to use different event loop implementations,
or substituted by a :ref:`custom policy <asyncio-custom-policies>`
that can override these behaviors.
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.
The :ref:`policy object <asyncio-policy-objects>`
gets and sets a separate event loop per *context*.
This is per-thread by default,
though custom policies could define *context* differently.
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.
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
===============