File: //usr/share/doc/python3/html/library/asyncio-policy.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Policies — Python 3.10.12 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?2022.1" />
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.10.12 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Platform Support" href="asyncio-platforms.html" />
<link rel="prev" title="Transports and Protocols" href="asyncio-protocol.html" />
<link rel="canonical" href="file:///usr/share/doc/python3.10/html/library/asyncio-policy.html" />
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<nav class="nav-content" role="navigation">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Logo"/>
</a>
<div class="version_switcher_placeholder"></div>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero"
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
</svg>
<input type="text" name="q" aria-label="Quick search"/>
<input type="submit" value="Go"/>
</form>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Policies</a><ul>
<li><a class="reference internal" href="#getting-and-setting-the-policy">Getting and Setting the Policy</a></li>
<li><a class="reference internal" href="#policy-objects">Policy Objects</a></li>
<li><a class="reference internal" href="#process-watchers">Process Watchers</a></li>
<li><a class="reference internal" href="#custom-policies">Custom Policies</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="asyncio-protocol.html"
title="previous chapter">Transports and Protocols</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="asyncio-platforms.html"
title="next chapter">Platform Support</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.10/Doc/library/asyncio-policy.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="asyncio-platforms.html" title="Platform Support"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="asyncio-protocol.html" title="Transports and Protocols"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.10.12 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> »</li>
<li class="nav-item nav-item-3"><a href="asyncio.html" accesskey="U"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a> »</li>
<li class="nav-item nav-item-this"><a href="">Policies</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="policies">
<span id="asyncio-policies"></span><h1>Policies<a class="headerlink" href="#policies" title="Permalink to this headline">¶</a></h1>
<p>An event loop policy is a global object
used to get and set the current <a class="reference internal" href="asyncio-eventloop.html#asyncio-event-loop"><span class="std std-ref">event loop</span></a>,
as well as create new event loops.
The default policy can be <a class="reference internal" href="#asyncio-policy-get-set"><span class="std std-ref">replaced</span></a> with
<a class="reference internal" href="#asyncio-policy-builtin"><span class="std std-ref">built-in alternatives</span></a>
to use different event loop implementations,
or substituted by a <a class="reference internal" href="#asyncio-custom-policies"><span class="std std-ref">custom policy</span></a>
that can override these behaviors.</p>
<p>The <a class="reference internal" href="#asyncio-policy-objects"><span class="std std-ref">policy object</span></a>
gets and sets a separate event loop per <em>context</em>.
This is per-thread by default,
though custom policies could define <em>context</em> differently.</p>
<p>Custom event loop policies can control the behavior of
<a class="reference internal" href="asyncio-eventloop.html#asyncio.get_event_loop" title="asyncio.get_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_event_loop()</span></code></a>, <a class="reference internal" href="asyncio-eventloop.html#asyncio.set_event_loop" title="asyncio.set_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_event_loop()</span></code></a>, and <a class="reference internal" href="asyncio-eventloop.html#asyncio.new_event_loop" title="asyncio.new_event_loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">new_event_loop()</span></code></a>.</p>
<p>Policy objects should implement the APIs defined
in the <a class="reference internal" href="#asyncio.AbstractEventLoopPolicy" title="asyncio.AbstractEventLoopPolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractEventLoopPolicy</span></code></a> abstract base class.</p>
<section id="getting-and-setting-the-policy">
<span id="asyncio-policy-get-set"></span><h2>Getting and Setting the Policy<a class="headerlink" href="#getting-and-setting-the-policy" title="Permalink to this headline">¶</a></h2>
<p>The following functions can be used to get and set the policy
for the current process:</p>
<dl class="py function">
<dt class="sig sig-object py" id="asyncio.get_event_loop_policy">
<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">get_event_loop_policy</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.get_event_loop_policy" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the current process-wide policy.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="asyncio.set_event_loop_policy">
<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">set_event_loop_policy</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">policy</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.set_event_loop_policy" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the current process-wide policy to <em>policy</em>.</p>
<p>If <em>policy</em> is set to <code class="docutils literal notranslate"><span class="pre">None</span></code>, the default policy is restored.</p>
</dd></dl>
</section>
<section id="policy-objects">
<span id="asyncio-policy-objects"></span><h2>Policy Objects<a class="headerlink" href="#policy-objects" title="Permalink to this headline">¶</a></h2>
<p>The abstract event loop policy base class is defined as follows:</p>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.AbstractEventLoopPolicy">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">AbstractEventLoopPolicy</span></span><a class="headerlink" href="#asyncio.AbstractEventLoopPolicy" title="Permalink to this definition">¶</a></dt>
<dd><p>An abstract base class for asyncio policies.</p>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractEventLoopPolicy.get_event_loop">
<span class="sig-name descname"><span class="pre">get_event_loop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractEventLoopPolicy.get_event_loop" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the event loop for the current context.</p>
<p>Return an event loop object implementing the
<a class="reference internal" href="asyncio-eventloop.html#asyncio.AbstractEventLoop" title="asyncio.AbstractEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractEventLoop</span></code></a> interface.</p>
<p>This method should never return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.6.</span></p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractEventLoopPolicy.set_event_loop">
<span class="sig-name descname"><span class="pre">set_event_loop</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">loop</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractEventLoopPolicy.set_event_loop" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the event loop for the current context to <em>loop</em>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractEventLoopPolicy.new_event_loop">
<span class="sig-name descname"><span class="pre">new_event_loop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractEventLoopPolicy.new_event_loop" title="Permalink to this definition">¶</a></dt>
<dd><p>Create and return a new event loop object.</p>
<p>This method should never return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractEventLoopPolicy.get_child_watcher">
<span class="sig-name descname"><span class="pre">get_child_watcher</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractEventLoopPolicy.get_child_watcher" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a child process watcher object.</p>
<p>Return a watcher object implementing the
<a class="reference internal" href="#asyncio.AbstractChildWatcher" title="asyncio.AbstractChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractChildWatcher</span></code></a> interface.</p>
<p>This function is Unix specific.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractEventLoopPolicy.set_child_watcher">
<span class="sig-name descname"><span class="pre">set_child_watcher</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">watcher</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractEventLoopPolicy.set_child_watcher" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the current child process watcher to <em>watcher</em>.</p>
<p>This function is Unix specific.</p>
</dd></dl>
</dd></dl>
<p id="asyncio-policy-builtin">asyncio ships with the following built-in policies:</p>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.DefaultEventLoopPolicy">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">DefaultEventLoopPolicy</span></span><a class="headerlink" href="#asyncio.DefaultEventLoopPolicy" title="Permalink to this definition">¶</a></dt>
<dd><p>The default asyncio policy. Uses <a class="reference internal" href="asyncio-eventloop.html#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a>
on Unix and <a class="reference internal" href="asyncio-eventloop.html#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a> on Windows.</p>
<p>There is no need to install the default policy manually. asyncio
is configured to use the default policy automatically.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.8: </span>On Windows, <a class="reference internal" href="asyncio-eventloop.html#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a> is now used by default.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>In Python versions 3.10.9, 3.11.1 and 3.12 the <a class="reference internal" href="asyncio-eventloop.html#asyncio.get_event_loop" title="asyncio.get_event_loop"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_event_loop()</span></code></a>
method of the default asyncio policy emits a <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a>
if there is no running event loop and no current loop is set.
In some future Python release this will become an error.</p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.WindowsSelectorEventLoopPolicy">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">WindowsSelectorEventLoopPolicy</span></span><a class="headerlink" href="#asyncio.WindowsSelectorEventLoopPolicy" title="Permalink to this definition">¶</a></dt>
<dd><p>An alternative event loop policy that uses the
<a class="reference internal" href="asyncio-eventloop.html#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">SelectorEventLoop</span></code></a> event loop implementation.</p>
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.WindowsProactorEventLoopPolicy">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">WindowsProactorEventLoopPolicy</span></span><a class="headerlink" href="#asyncio.WindowsProactorEventLoopPolicy" title="Permalink to this definition">¶</a></dt>
<dd><p>An alternative event loop policy that uses the
<a class="reference internal" href="asyncio-eventloop.html#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal notranslate"><span class="pre">ProactorEventLoop</span></code></a> event loop implementation.</p>
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
</dd></dl>
</section>
<section id="process-watchers">
<span id="asyncio-watchers"></span><h2>Process Watchers<a class="headerlink" href="#process-watchers" title="Permalink to this headline">¶</a></h2>
<p>A process watcher allows customization of how an event loop monitors
child processes on Unix. Specifically, the event loop needs to know
when a child process has exited.</p>
<p>In asyncio, child processes are created with
<a class="reference internal" href="asyncio-subprocess.html#asyncio.create_subprocess_exec" title="asyncio.create_subprocess_exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_subprocess_exec()</span></code></a> and <a class="reference internal" href="asyncio-eventloop.html#asyncio.loop.subprocess_exec" title="asyncio.loop.subprocess_exec"><code class="xref py py-meth docutils literal notranslate"><span class="pre">loop.subprocess_exec()</span></code></a>
functions.</p>
<p>asyncio defines the <a class="reference internal" href="#asyncio.AbstractChildWatcher" title="asyncio.AbstractChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractChildWatcher</span></code></a> abstract base class, which child
watchers should implement, and has four different implementations:
<a class="reference internal" href="#asyncio.ThreadedChildWatcher" title="asyncio.ThreadedChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">ThreadedChildWatcher</span></code></a> (configured to be used by default),
<a class="reference internal" href="#asyncio.MultiLoopChildWatcher" title="asyncio.MultiLoopChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">MultiLoopChildWatcher</span></code></a>, <a class="reference internal" href="#asyncio.SafeChildWatcher" title="asyncio.SafeChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">SafeChildWatcher</span></code></a>, and
<a class="reference internal" href="#asyncio.FastChildWatcher" title="asyncio.FastChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">FastChildWatcher</span></code></a>.</p>
<p>See also the <a class="reference internal" href="asyncio-subprocess.html#asyncio-subprocess-threads"><span class="std std-ref">Subprocess and Threads</span></a>
section.</p>
<p>The following two functions can be used to customize the child process watcher
implementation used by the asyncio event loop:</p>
<dl class="py function">
<dt class="sig sig-object py" id="asyncio.get_child_watcher">
<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">get_child_watcher</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.get_child_watcher" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the current child watcher for the current policy.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="asyncio.set_child_watcher">
<span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">set_child_watcher</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">watcher</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.set_child_watcher" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the current child watcher to <em>watcher</em> for the current
policy. <em>watcher</em> must implement methods defined in the
<a class="reference internal" href="#asyncio.AbstractChildWatcher" title="asyncio.AbstractChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractChildWatcher</span></code></a> base class.</p>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Third-party event loops implementations might not support
custom child watchers. For such event loops, using
<a class="reference internal" href="#asyncio.set_child_watcher" title="asyncio.set_child_watcher"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_child_watcher()</span></code></a> might be prohibited or have no effect.</p>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.AbstractChildWatcher">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">AbstractChildWatcher</span></span><a class="headerlink" href="#asyncio.AbstractChildWatcher" title="Permalink to this definition">¶</a></dt>
<dd><dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractChildWatcher.add_child_handler">
<span class="sig-name descname"><span class="pre">add_child_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">pid</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">callback</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractChildWatcher.add_child_handler" title="Permalink to this definition">¶</a></dt>
<dd><p>Register a new child handler.</p>
<p>Arrange for <code class="docutils literal notranslate"><span class="pre">callback(pid,</span> <span class="pre">returncode,</span> <span class="pre">*args)</span></code> to be called
when a process with PID equal to <em>pid</em> terminates. Specifying
another callback for the same process replaces the previous
handler.</p>
<p>The <em>callback</em> callable must be thread-safe.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractChildWatcher.remove_child_handler">
<span class="sig-name descname"><span class="pre">remove_child_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">pid</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractChildWatcher.remove_child_handler" title="Permalink to this definition">¶</a></dt>
<dd><p>Removes the handler for process with PID equal to <em>pid</em>.</p>
<p>The function returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if the handler was successfully
removed, <code class="docutils literal notranslate"><span class="pre">False</span></code> if there was nothing to remove.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractChildWatcher.attach_loop">
<span class="sig-name descname"><span class="pre">attach_loop</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">loop</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractChildWatcher.attach_loop" title="Permalink to this definition">¶</a></dt>
<dd><p>Attach the watcher to an event loop.</p>
<p>If the watcher was previously attached to an event loop, then
it is first detached before attaching to the new loop.</p>
<p>Note: loop may be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractChildWatcher.is_active">
<span class="sig-name descname"><span class="pre">is_active</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractChildWatcher.is_active" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the watcher is ready to use.</p>
<p>Spawning a subprocess with <em>inactive</em> current child watcher raises
<a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.8.</span></p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="asyncio.AbstractChildWatcher.close">
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.AbstractChildWatcher.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Close the watcher.</p>
<p>This method has to be called to ensure that underlying
resources are cleaned-up.</p>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.ThreadedChildWatcher">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">ThreadedChildWatcher</span></span><a class="headerlink" href="#asyncio.ThreadedChildWatcher" title="Permalink to this definition">¶</a></dt>
<dd><p>This implementation starts a new waiting thread for every subprocess spawn.</p>
<p>It works reliably even when the asyncio event loop is run in a non-main OS thread.</p>
<p>There is no noticeable overhead when handling a big number of children (<em>O(1)</em> each
time a child terminates), but starting a thread per process requires extra memory.</p>
<p>This watcher is used by default.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.8.</span></p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.MultiLoopChildWatcher">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">MultiLoopChildWatcher</span></span><a class="headerlink" href="#asyncio.MultiLoopChildWatcher" title="Permalink to this definition">¶</a></dt>
<dd><p>This implementation registers a <code class="xref py py-data docutils literal notranslate"><span class="pre">SIGCHLD</span></code> signal handler on
instantiation. That can break third-party code that installs a custom handler for
<code class="xref py py-data docutils literal notranslate"><span class="pre">SIGCHLD</span></code> signal.</p>
<p>The watcher avoids disrupting other code spawning processes
by polling every process explicitly on a <code class="xref py py-data docutils literal notranslate"><span class="pre">SIGCHLD</span></code> signal.</p>
<p>There is no limitation for running subprocesses from different threads once the
watcher is installed.</p>
<p>The solution is safe but it has a significant overhead when
handling a big number of processes (<em>O(n)</em> each time a
<code class="xref py py-data docutils literal notranslate"><span class="pre">SIGCHLD</span></code> is received).</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.8.</span></p>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.SafeChildWatcher">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">SafeChildWatcher</span></span><a class="headerlink" href="#asyncio.SafeChildWatcher" title="Permalink to this definition">¶</a></dt>
<dd><p>This implementation uses active event loop from the main thread to handle
<code class="xref py py-data docutils literal notranslate"><span class="pre">SIGCHLD</span></code> signal. If the main thread has no running event loop another
thread cannot spawn a subprocess (<a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> is raised).</p>
<p>The watcher avoids disrupting other code spawning processes
by polling every process explicitly on a <code class="xref py py-data docutils literal notranslate"><span class="pre">SIGCHLD</span></code> signal.</p>
<p>This solution is as safe as <a class="reference internal" href="#asyncio.MultiLoopChildWatcher" title="asyncio.MultiLoopChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">MultiLoopChildWatcher</span></code></a> and has the same <em>O(N)</em>
complexity but requires a running event loop in the main thread to work.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.FastChildWatcher">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">FastChildWatcher</span></span><a class="headerlink" href="#asyncio.FastChildWatcher" title="Permalink to this definition">¶</a></dt>
<dd><p>This implementation reaps every terminated processes by calling
<code class="docutils literal notranslate"><span class="pre">os.waitpid(-1)</span></code> directly, possibly breaking other code spawning
processes and waiting for their termination.</p>
<p>There is no noticeable overhead when handling a big number of
children (<em>O(1)</em> each time a child terminates).</p>
<p>This solution requires a running event loop in the main thread to work, as
<a class="reference internal" href="#asyncio.SafeChildWatcher" title="asyncio.SafeChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">SafeChildWatcher</span></code></a>.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="asyncio.PidfdChildWatcher">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">asyncio.</span></span><span class="sig-name descname"><span class="pre">PidfdChildWatcher</span></span><a class="headerlink" href="#asyncio.PidfdChildWatcher" title="Permalink to this definition">¶</a></dt>
<dd><p>This implementation polls process file descriptors (pidfds) to await child
process termination. In some respects, <a class="reference internal" href="#asyncio.PidfdChildWatcher" title="asyncio.PidfdChildWatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">PidfdChildWatcher</span></code></a> is a
“Goldilocks” child watcher implementation. It doesn’t require signals or
threads, doesn’t interfere with any processes launched outside the event
loop, and scales linearly with the number of subprocesses launched by the
event loop. The main disadvantage is that pidfds are specific to Linux, and
only work on recent (5.3+) kernels.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.9.</span></p>
</div>
</dd></dl>
</section>
<section id="custom-policies">
<span id="asyncio-custom-policies"></span><h2>Custom Policies<a class="headerlink" href="#custom-policies" title="Permalink to this headline">¶</a></h2>
<p>To implement a new event loop policy, it is recommended to subclass
<a class="reference internal" href="#asyncio.DefaultEventLoopPolicy" title="asyncio.DefaultEventLoopPolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultEventLoopPolicy</span></code></a> and override the methods for which
custom behavior is wanted, e.g.:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyEventLoopPolicy</span><span class="p">(</span><span class="n">asyncio</span><span class="o">.</span><span class="n">DefaultEventLoopPolicy</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">get_event_loop</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""Get the event loop.</span>
<span class="sd"> This may be None or an instance of EventLoop.</span>
<span class="sd"> """</span>
<span class="n">loop</span> <span class="o">=</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">get_event_loop</span><span class="p">()</span>
<span class="c1"># Do something with loop ...</span>
<span class="k">return</span> <span class="n">loop</span>
<span class="n">asyncio</span><span class="o">.</span><span class="n">set_event_loop_policy</span><span class="p">(</span><span class="n">MyEventLoopPolicy</span><span class="p">())</span>
</pre></div>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Policies</a><ul>
<li><a class="reference internal" href="#getting-and-setting-the-policy">Getting and Setting the Policy</a></li>
<li><a class="reference internal" href="#policy-objects">Policy Objects</a></li>
<li><a class="reference internal" href="#process-watchers">Process Watchers</a></li>
<li><a class="reference internal" href="#custom-policies">Custom Policies</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="asyncio-protocol.html"
title="previous chapter">Transports and Protocols</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="asyncio-platforms.html"
title="next chapter">Platform Support</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.10/Doc/library/asyncio-policy.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="asyncio-platforms.html" title="Platform Support"
>next</a> |</li>
<li class="right" >
<a href="asyncio-protocol.html" title="Transports and Protocols"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.10.12 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> »</li>
<li class="nav-item nav-item-3"><a href="asyncio.html" ><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code> — Asynchronous I/O</a> »</li>
<li class="nav-item nav-item-this"><a href="">Policies</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
|
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001-2025, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
See <a href="/license.html">History and License</a> for more information.<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
Last updated on August 15, 2025.
<a href="/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.3.2.
</div>
</body>
</html>