| 1 |
.. currentmodule:: asyncio |
| 2 |
|
| 3 |
|
| 4 |
========= |
| 5 |
Extending |
| 6 |
========= |
| 7 |
|
| 8 |
The main direction for :mod:`asyncio` extending is writing custom *event loop* |
| 9 |
classes. Asyncio has helpers that could be used to simplify this task. |
| 10 |
|
| 11 |
.. note:: |
| 12 |
|
| 13 |
Third-parties should reuse existing asyncio code with caution, |
| 14 |
a new Python version is free to break backward compatibility |
| 15 |
in *internal* part of API. |
| 16 |
|
| 17 |
|
| 18 |
Writing a Custom Event Loop |
| 19 |
=========================== |
| 20 |
|
| 21 |
:class:`asyncio.AbstractEventLoop` declares very many methods. Implementing all them |
| 22 |
from scratch is a tedious job. |
| 23 |
|
| 24 |
A loop can get many common methods implementation for free by inheriting from |
| 25 |
:class:`asyncio.BaseEventLoop`. |
| 26 |
|
| 27 |
In turn, the successor should implement a bunch of *private* methods declared but not |
| 28 |
implemented in :class:`asyncio.BaseEventLoop`. |
| 29 |
|
| 30 |
For example, ``loop.create_connection()`` checks arguments, resolves DNS addresses, and |
| 31 |
calls ``loop._make_socket_transport()`` that should be implemented by inherited class. |
| 32 |
The ``_make_socket_transport()`` method is not documented and is considered as an |
| 33 |
*internal* API. |
| 34 |
|
| 35 |
|
| 36 |
|
| 37 |
Future and Task private constructors |
| 38 |
==================================== |
| 39 |
|
| 40 |
:class:`asyncio.Future` and :class:`asyncio.Task` should be never created directly, |
| 41 |
please use corresponding :meth:`loop.create_future` and :meth:`loop.create_task`, |
| 42 |
or :func:`asyncio.create_task` factories instead. |
| 43 |
|
| 44 |
However, third-party *event loops* may *reuse* built-in future and task implementations |
| 45 |
for the sake of getting a complex and highly optimized code for free. |
| 46 |
|
| 47 |
For this purpose the following, *private* constructors are listed: |
| 48 |
|
| 49 |
.. method:: Future.__init__(*, loop=None) |
| 50 |
|
| 51 |
Create a built-in future instance. |
| 52 |
|
| 53 |
*loop* is an optional event loop instance. |
| 54 |
|
| 55 |
.. method:: Task.__init__(coro, *, loop=None, name=None, context=None) |
| 56 |
|
| 57 |
Create a built-in task instance. |
| 58 |
|
| 59 |
*loop* is an optional event loop instance. The rest of arguments are described in |
| 60 |
:meth:`loop.create_task` description. |
| 61 |
|
| 62 |
.. versionchanged:: 3.11 |
| 63 |
|
| 64 |
*context* argument is added. |
| 65 |
|
| 66 |
|
| 67 |
|
| 68 |
Task lifetime support |
| 69 |
===================== |
| 70 |
|
| 71 |
A third party task implementation should call the following functions to keep a task |
| 72 |
visible by :func:`asyncio.all_tasks` and :func:`asyncio.current_task`: |
| 73 |
|
| 74 |
.. function:: _register_task(task) |
| 75 |
|
| 76 |
Register a new *task* as managed by *asyncio*. |
| 77 |
|
| 78 |
Call the function from a task constructor. |
| 79 |
|
| 80 |
.. function:: _unregister_task(task) |
| 81 |
|
| 82 |
Unregister a *task* from *asyncio* internal structures. |
| 83 |
|
| 84 |
The function should be called when a task is about to finish. |
| 85 |
|
| 86 |
.. function:: _enter_task(loop, task) |
| 87 |
|
| 88 |
Switch the current task to the *task* argument. |
| 89 |
|
| 90 |
Call the function just before executing a portion of embedded *coroutine* |
| 91 |
(:meth:`coroutine.send` or :meth:`coroutine.throw`). |
| 92 |
|
| 93 |
.. function:: _leave_task(loop, task) |
| 94 |
|
| 95 |
Switch the current task back from *task* to ``None``. |
| 96 |
|
| 97 |
Call the function just after :meth:`coroutine.send` or :meth:`coroutine.throw` |
| 98 |
execution. |