https://github.com/python/cpython/commit/ab89ccff3ca6efc2a8e6f5f45c30d568fb3... commit: ab89ccff3ca6efc2a8e6f5f45c30d568fb3d212f branch: main author: Andrew Svetlov <andrew.svetlov@gmail.com> committer: asvetlov <andrew.svetlov@gmail.com> date: 2022-04-01T00:06:07+03:00 summary: bpo-45099: Document asyncio internal API (GH-32166) files: A Doc/library/asyncio-extending.rst A Misc/NEWS.d/next/Documentation/2022-03-29-13-25-49.bpo-45099.dagdhx.rst M Doc/library/asyncio.rst diff --git a/Doc/library/asyncio-extending.rst b/Doc/library/asyncio-extending.rst new file mode 100644 index 0000000000000..619723e61b5f9 --- /dev/null +++ b/Doc/library/asyncio-extending.rst @@ -0,0 +1,93 @@ +.. currentmodule:: asyncio + + +========= +Extending +========= + +The main direction for :mod:`asyncio` extending is writing custom *event loop* +classes. Asyncio has helpers that could be used to simplify this task. + +.. note:: + + Third-parties should reuse existing asyncio code with caution, + a new Python version is free to break backward compatibility + in *internal* part of API. + + +Writing a Custom Event Loop +=========================== + +:class:`asyncio.AbstractEventLoop` declares very many methods. Implementing all them +from scratch is a tedious job. + +A loop can get many common methods implementation for free by inheriting from +:class:`asyncio.BaseEventLoop`. + +In turn, the successor should implement a bunch of *private* methods declared but not +implemented in :class:`asyncio.BaseEventLoop`. + +For example, ``loop.create_connection()`` checks arguments, resolves DNS addresses, and +calls ``loop._make_socket_transport()`` that should be implemented by inherited class. +The ``_make_socket_transport()`` method is not documented and is considered as an +*internal* API. + + + +Future and Task private constructors +==================================== + +:class:`asyncio.Future` and :class:`asyncio.Task` should be never created directly, +please use corresponding :meth:`loop.create_future` and :meth:`loop.create_task`, +or :func:`asyncio.create_task` factories instead. + +However, third-party *event loops* may *reuse* built-in future and task implementations +for the sake of getting a complex and highly optimized code for free. + +For this purpose the following, *private* constructors are listed: + +.. method:: Future.__init__(*, loop=None) + +Create a built-in future instance. + +*loop* is an optional event loop instance. + +.. method:: Task.__init__(coro, *, loop=None, name=None, context=None) + +Create a built-in task instance. + +*loop* is an optional event loop instance. The rest of arguments are described in +:meth:`loop.create_task` description. + + +Task lifetime support +===================== + +A third party task implementation should call the following functions to keep a task +visible by :func:`asyncio.get_tasks` and :func:`asyncio.current_task`: + +.. function:: _register_task(task) + + Register a new *task* as managed by *asyncio*. + + Call the function from a task constructor. + +.. function:: _unregister_task(task) + + Unregister a *task* from *asyncio* internal structures. + + The function should be called when a task is about to finish. + +.. function:: _enter_task(loop, task) + + Switch the current task to the *task* argument. + + Call the function just before executing a portion of embedded *coroutine* + (:meth:`coroutine.send` or :meth:`coroutine.throw`). + +.. function:: _leave_task(loop, task) + + Switch the current task back from *task* to ``None``. + + Call the function just after :meth:`coroutine.send` or :meth:`coroutine.throw` + execution. diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index 8b3a060ffad52..8f4d55a9de059 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -84,6 +84,7 @@ Additionally, there are **low-level** APIs for asyncio-protocol.rst asyncio-policy.rst asyncio-platforms.rst + asyncio-extending.rst .. toctree:: :caption: Guides and Tutorials diff --git a/Misc/NEWS.d/next/Documentation/2022-03-29-13-25-49.bpo-45099.dagdhx.rst b/Misc/NEWS.d/next/Documentation/2022-03-29-13-25-49.bpo-45099.dagdhx.rst new file mode 100644 index 0000000000000..7b38682b452d2 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2022-03-29-13-25-49.bpo-45099.dagdhx.rst @@ -0,0 +1 @@ +Document internal :mod:`asyncio` API.