new repository

1 files changed, 24 insertions, 0 deletions

diff --git a/devdocs/python~3.12/library%2Fasyncio-extending.html b/devdocs/python~3.12/library%2Fasyncio-extending.html
new file mode 100644
index 00000000..d34d7230
--- /dev/null
+++ b/devdocs/python~3.12/library%2Fasyncio-extending.html
@@ -0,0 +1,24 @@
+ <h1>Extending</h1> <p>The main direction for <a class="reference internal" href="asyncio#module-asyncio" title="asyncio: Asynchronous I/O."><code>asyncio</code></a> extending is writing custom <em>event loop</em> classes. Asyncio has helpers that could be used to simplify this task.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Third-parties should reuse existing asyncio code with caution, a new Python version is free to break backward compatibility in <em>internal</em> part of API.</p> </div> <section id="writing-a-custom-event-loop"> <h2>Writing a Custom Event Loop</h2> <p><a class="reference internal" href="asyncio-eventloop#asyncio.AbstractEventLoop" title="asyncio.AbstractEventLoop"><code>asyncio.AbstractEventLoop</code></a> declares very many methods. Implementing all them from scratch is a tedious job.</p> <p>A loop can get many common methods implementation for free by inheriting from <code>asyncio.BaseEventLoop</code>.</p> <p>In turn, the successor should implement a bunch of <em>private</em> methods declared but not implemented in <code>asyncio.BaseEventLoop</code>.</p> <p>For example, <code>loop.create_connection()</code> checks arguments, resolves DNS addresses, and calls <code>loop._make_socket_transport()</code> that should be implemented by inherited class. The <code>_make_socket_transport()</code> method is not documented and is considered as an <em>internal</em> API.</p> </section> <section id="future-and-task-private-constructors"> <h2>Future and Task private constructors</h2> <p><a class="reference internal" href="asyncio-future#asyncio.Future" title="asyncio.Future"><code>asyncio.Future</code></a> and <a class="reference internal" href="asyncio-task#asyncio.Task" title="asyncio.Task"><code>asyncio.Task</code></a> should be never created directly, please use corresponding <a class="reference internal" href="asyncio-eventloop#asyncio.loop.create_future" title="asyncio.loop.create_future"><code>loop.create_future()</code></a> and <a class="reference internal" href="asyncio-eventloop#asyncio.loop.create_task" title="asyncio.loop.create_task"><code>loop.create_task()</code></a>, or <a class="reference internal" href="asyncio-task#asyncio.create_task" title="asyncio.create_task"><code>asyncio.create_task()</code></a> factories instead.</p> <p>However, third-party <em>event loops</em> may <em>reuse</em> built-in future and task implementations for the sake of getting a complex and highly optimized code for free.</p> <p>For this purpose the following, <em>private</em> constructors are listed:</p> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.Future.__init__">
+<code>Future.__init__(*, loop=None)</code> </dt> <dd>
+<p>Create a built-in future instance.</p> <p><em>loop</em> is an optional event loop instance.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="asyncio.Task.__init__">
+<code>Task.__init__(coro, *, loop=None, name=None, context=None)</code> </dt> <dd>
+<p>Create a built-in task instance.</p> <p><em>loop</em> is an optional event loop instance. The rest of arguments are described in <a class="reference internal" href="asyncio-eventloop#asyncio.loop.create_task" title="asyncio.loop.create_task"><code>loop.create_task()</code></a> description.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span><em>context</em> argument is added.</p> </div> </dd>
+</dl> </section> <section id="task-lifetime-support"> <h2>Task lifetime support</h2> <p>A third party task implementation should call the following functions to keep a task visible by <a class="reference internal" href="asyncio-task#asyncio.all_tasks" title="asyncio.all_tasks"><code>asyncio.all_tasks()</code></a> and <a class="reference internal" href="asyncio-task#asyncio.current_task" title="asyncio.current_task"><code>asyncio.current_task()</code></a>:</p> <dl class="py function"> <dt class="sig sig-object py" id="asyncio._register_task">
+<code>asyncio._register_task(task)</code> </dt> <dd>
+<p>Register a new <em>task</em> as managed by <em>asyncio</em>.</p> <p>Call the function from a task constructor.</p> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="asyncio._unregister_task">
+<code>asyncio._unregister_task(task)</code> </dt> <dd>
+<p>Unregister a <em>task</em> from <em>asyncio</em> internal structures.</p> <p>The function should be called when a task is about to finish.</p> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="asyncio._enter_task">
+<code>asyncio._enter_task(loop, task)</code> </dt> <dd>
+<p>Switch the current task to the <em>task</em> argument.</p> <p>Call the function just before executing a portion of embedded <em>coroutine</em> (<a class="reference internal" href="../reference/datamodel#coroutine.send" title="coroutine.send"><code>coroutine.send()</code></a> or <a class="reference internal" href="../reference/datamodel#coroutine.throw" title="coroutine.throw"><code>coroutine.throw()</code></a>).</p> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="asyncio._leave_task">
+<code>asyncio._leave_task(loop, task)</code> </dt> <dd>
+<p>Switch the current task back from <em>task</em> to <code>None</code>.</p> <p>Call the function just after <a class="reference internal" href="../reference/datamodel#coroutine.send" title="coroutine.send"><code>coroutine.send()</code></a> or <a class="reference internal" href="../reference/datamodel#coroutine.throw" title="coroutine.throw"><code>coroutine.throw()</code></a> execution.</p> </dd>
+</dl> </section> <div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
+    <a href="https://docs.python.org/3.12/library/asyncio-extending.html" class="_attribution-link">https://docs.python.org/3.12/library/asyncio-extending.html</a>
+  </p>
+</div>