<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>Synchronization Primitives — Python 3.7.10 documentation</title>
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.7.10 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="Subprocesses" href="asyncio-subprocess.html" />
<link rel="prev" title="Streams" href="asyncio-stream.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/3/library/asyncio-sync.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
</head><body>
<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-subprocess.html" title="Subprocesses"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="asyncio-stream.html" title="Streams"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">3.7.10 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="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="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>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="synchronization-primitives">
<span id="asyncio-sync"></span><h1>Synchronization Primitives<a class="headerlink" href="#synchronization-primitives" title="Permalink to this headline">¶</a></h1>
<p>asyncio synchronization primitives are designed to be similar to
those of the <a class="reference internal" href="threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module with two important caveats:</p>
<ul class="simple">
<li><p>asyncio primitives are not thread-safe, therefore they should not
be used for OS thread synchronization (use <a class="reference internal" href="threading.html#module-threading" title="threading: Thread-based parallelism."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> for
that);</p></li>
<li><p>methods of these synchronization primitives do not accept the <em>timeout</em>
argument; use the <a class="reference internal" href="asyncio-task.html#asyncio.wait_for" title="asyncio.wait_for"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.wait_for()</span></code></a> function to perform
operations with timeouts.</p></li>
</ul>
<p>asyncio has the following basic synchronization primitives:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#asyncio.Lock" title="asyncio.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Lock</span></code></a></p></li>
<li><p><a class="reference internal" href="#asyncio.Event" title="asyncio.Event"><code class="xref py py-class docutils literal notranslate"><span class="pre">Event</span></code></a></p></li>
<li><p><a class="reference internal" href="#asyncio.Condition" title="asyncio.Condition"><code class="xref py py-class docutils literal notranslate"><span class="pre">Condition</span></code></a></p></li>
<li><p><a class="reference internal" href="#asyncio.Semaphore" title="asyncio.Semaphore"><code class="xref py py-class docutils literal notranslate"><span class="pre">Semaphore</span></code></a></p></li>
<li><p><a class="reference internal" href="#asyncio.BoundedSemaphore" title="asyncio.BoundedSemaphore"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundedSemaphore</span></code></a></p></li>
</ul>
<hr class="docutils" />
<div class="section" id="lock">
<h2>Lock<a class="headerlink" href="#lock" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="asyncio.Lock">
<em class="property">class </em><code class="sig-prename descclassname">asyncio.</code><code class="sig-name descname">Lock</code><span class="sig-paren">(</span><em class="sig-param">*</em>, <em class="sig-param">loop=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Lock" title="Permalink to this definition">¶</a></dt>
<dd><p>Implements a mutex lock for asyncio tasks. Not thread-safe.</p>
<p>An asyncio lock can be used to guarantee exclusive access to a
shared resource.</p>
<p>The preferred way to use a Lock is an <a class="reference internal" href="../reference/compound_stmts.html#async-with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code></a>
statement:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">lock</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Lock</span><span class="p">()</span>
<span class="c1"># ... later</span>
<span class="k">async</span> <span class="k">with</span> <span class="n">lock</span><span class="p">:</span>
<span class="c1"># access shared state</span>
</pre></div>
</div>
<p>which is equivalent to:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">lock</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Lock</span><span class="p">()</span>
<span class="c1"># ... later</span>
<span class="k">await</span> <span class="n">lock</span><span class="o">.</span><span class="n">acquire</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="c1"># access shared state</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">lock</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
</pre></div>
</div>
<dl class="method">
<dt id="asyncio.Lock.acquire">
<em class="property">coroutine </em><code class="sig-name descname">acquire</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Lock.acquire" title="Permalink to this definition">¶</a></dt>
<dd><p>Acquire the lock.</p>
<p>This method waits until the lock is <em>unlocked</em>, sets it to
<em>locked</em> and returns <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
<p>When more than one coroutine is blocked in <a class="reference internal" href="#asyncio.Lock.acquire" title="asyncio.Lock.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a>
waiting for the lock to be unlocked, only one coroutine
eventually proceeds.</p>
<p>Acquiring a lock is <em>fair</em>: the coroutine that proceeds will be
the first coroutine that started waiting on the lock.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Lock.release">
<code class="sig-name descname">release</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Lock.release" title="Permalink to this definition">¶</a></dt>
<dd><p>Release the lock.</p>
<p>When the lock is <em>locked</em>, reset it to <em>unlocked</em> and return.</p>
<p>If the lock is <em>unlocked</em>, a <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>
</dd></dl>
<dl class="method">
<dt id="asyncio.Lock.locked">
<code class="sig-name descname">locked</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Lock.locked" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the lock is <em>locked</em>.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="event">
<h2>Event<a class="headerlink" href="#event" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="asyncio.Event">
<em class="property">class </em><code class="sig-prename descclassname">asyncio.</code><code class="sig-name descname">Event</code><span class="sig-paren">(</span><em class="sig-param">*</em>, <em class="sig-param">loop=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Event" title="Permalink to this definition">¶</a></dt>
<dd><p>An event object. Not thread-safe.</p>
<p>An asyncio event can be used to notify multiple asyncio tasks
that some event has happened.</p>
<p>An Event object manages an internal flag that can be set to <em>true</em>
with the <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set()</span></code></a> method and reset to <em>false</em> with the
<a class="reference internal" href="#asyncio.Event.clear" title="asyncio.Event.clear"><code class="xref py py-meth docutils literal notranslate"><span class="pre">clear()</span></code></a> method. The <a class="reference internal" href="asyncio-task.html#asyncio.wait" title="asyncio.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a> method blocks until the
flag is set to <em>true</em>. The flag is set to <em>false</em> initially.</p>
<p id="asyncio-example-sync-event">Example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span> <span class="nf">waiter</span><span class="p">(</span><span class="n">event</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'waiting for it ...'</span><span class="p">)</span>
<span class="k">await</span> <span class="n">event</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'... got it!'</span><span class="p">)</span>
<span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
<span class="c1"># Create an Event object.</span>
<span class="n">event</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Event</span><span class="p">()</span>
<span class="c1"># Spawn a Task to wait until 'event' is set.</span>
<span class="n">waiter_task</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">waiter</span><span class="p">(</span><span class="n">event</span><span class="p">))</span>
<span class="c1"># Sleep for 1 second and set the event.</span>
<span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="n">event</span><span class="o">.</span><span class="n">set</span><span class="p">()</span>
<span class="c1"># Wait until the waiter task is finished.</span>
<span class="k">await</span> <span class="n">waiter_task</span>
<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
</pre></div>
</div>
<dl class="method">
<dt id="asyncio.Event.wait">
<em class="property">coroutine </em><code class="sig-name descname">wait</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Event.wait" title="Permalink to this definition">¶</a></dt>
<dd><p>Wait until the event is set.</p>
<p>If the event is set, return <code class="docutils literal notranslate"><span class="pre">True</span></code> immediately.
Otherwise block until another task calls <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set()</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Event.set">
<code class="sig-name descname">set</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Event.set" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the event.</p>
<p>All tasks waiting for event to be set will be immediately
awakened.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Event.clear">
<code class="sig-name descname">clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Event.clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear (unset) the event.</p>
<p>Tasks awaiting on <a class="reference internal" href="asyncio-task.html#asyncio.wait" title="asyncio.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a> will now block until the
<a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set()</span></code></a> method is called again.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Event.is_set">
<code class="sig-name descname">is_set</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Event.is_set" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the event is set.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="condition">
<h2>Condition<a class="headerlink" href="#condition" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="asyncio.Condition">
<em class="property">class </em><code class="sig-prename descclassname">asyncio.</code><code class="sig-name descname">Condition</code><span class="sig-paren">(</span><em class="sig-param">lock=None</em>, <em class="sig-param">*</em>, <em class="sig-param">loop=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Condition" title="Permalink to this definition">¶</a></dt>
<dd><p>A Condition object. Not thread-safe.</p>
<p>An asyncio condition primitive can be used by a task to wait for
some event to happen and then get exclusive access to a shared
resource.</p>
<p>In essence, a Condition object combines the functionality
of an <a class="reference internal" href="#asyncio.Event" title="asyncio.Event"><code class="xref py py-class docutils literal notranslate"><span class="pre">Event</span></code></a> and a <a class="reference internal" href="#asyncio.Lock" title="asyncio.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Lock</span></code></a>. It is possible to have
multiple Condition objects share one Lock, which allows coordinating
exclusive access to a shared resource between different tasks
interested in particular states of that shared resource.</p>
<p>The optional <em>lock</em> argument must be a <a class="reference internal" href="#asyncio.Lock" title="asyncio.Lock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Lock</span></code></a> object or
<code class="docutils literal notranslate"><span class="pre">None</span></code>. In the latter case a new Lock object is created
automatically.</p>
<p>The preferred way to use a Condition is an <a class="reference internal" href="../reference/compound_stmts.html#async-with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code></a>
statement:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">cond</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Condition</span><span class="p">()</span>
<span class="c1"># ... later</span>
<span class="k">async</span> <span class="k">with</span> <span class="n">cond</span><span class="p">:</span>
<span class="k">await</span> <span class="n">cond</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>
</pre></div>
</div>
<p>which is equivalent to:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">cond</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Condition</span><span class="p">()</span>
<span class="c1"># ... later</span>
<span class="k">await</span> <span class="n">cond</span><span class="o">.</span><span class="n">acquire</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">await</span> <span class="n">cond</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">cond</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
</pre></div>
</div>
<dl class="method">
<dt id="asyncio.Condition.acquire">
<em class="property">coroutine </em><code class="sig-name descname">acquire</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Condition.acquire" title="Permalink to this definition">¶</a></dt>
<dd><p>Acquire the underlying lock.</p>
<p>This method waits until the underlying lock is <em>unlocked</em>,
sets it to <em>locked</em> and returns <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Condition.notify">
<code class="sig-name descname">notify</code><span class="sig-paren">(</span><em class="sig-param">n=1</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Condition.notify" title="Permalink to this definition">¶</a></dt>
<dd><p>Wake up at most <em>n</em> tasks (1 by default) waiting on this
condition. The method is no-op if no tasks are waiting.</p>
<p>The lock must be acquired before this method is called and
released shortly after. If called with an <em>unlocked</em> lock
a <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> error is raised.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Condition.locked">
<code class="sig-name descname">locked</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Condition.locked" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the underlying lock is acquired.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Condition.notify_all">
<code class="sig-name descname">notify_all</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Condition.notify_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Wake up all tasks waiting on this condition.</p>
<p>This method acts like <a class="reference internal" href="#asyncio.Condition.notify" title="asyncio.Condition.notify"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify()</span></code></a>, but wakes up all waiting
tasks.</p>
<p>The lock must be acquired before this method is called and
released shortly after. If called with an <em>unlocked</em> lock
a <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> error is raised.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Condition.release">
<code class="sig-name descname">release</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Condition.release" title="Permalink to this definition">¶</a></dt>
<dd><p>Release the underlying lock.</p>
<p>When invoked on an unlocked lock, a <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>
</dd></dl>
<dl class="method">
<dt id="asyncio.Condition.wait">
<em class="property">coroutine </em><code class="sig-name descname">wait</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Condition.wait" title="Permalink to this definition">¶</a></dt>
<dd><p>Wait until notified.</p>
<p>If the calling task has not acquired the lock when this method is
called, a <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>This method releases the underlying lock, and then blocks until
it is awakened by a <a class="reference internal" href="#asyncio.Condition.notify" title="asyncio.Condition.notify"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify()</span></code></a> or <a class="reference internal" href="#asyncio.Condition.notify_all" title="asyncio.Condition.notify_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">notify_all()</span></code></a> call.
Once awakened, the Condition re-acquires its lock and this method
returns <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Condition.wait_for">
<em class="property">coroutine </em><code class="sig-name descname">wait_for</code><span class="sig-paren">(</span><em class="sig-param">predicate</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Condition.wait_for" title="Permalink to this definition">¶</a></dt>
<dd><p>Wait until a predicate becomes <em>true</em>.</p>
<p>The predicate must be a callable which result will be
interpreted as a boolean value. The final value is the
return value.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="semaphore">
<h2>Semaphore<a class="headerlink" href="#semaphore" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="asyncio.Semaphore">
<em class="property">class </em><code class="sig-prename descclassname">asyncio.</code><code class="sig-name descname">Semaphore</code><span class="sig-paren">(</span><em class="sig-param">value=1</em>, <em class="sig-param">*</em>, <em class="sig-param">loop=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Semaphore" title="Permalink to this definition">¶</a></dt>
<dd><p>A Semaphore object. Not thread-safe.</p>
<p>A semaphore manages an internal counter which is decremented by each
<a class="reference internal" href="#asyncio.Semaphore.acquire" title="asyncio.Semaphore.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a> call and incremented by each <a class="reference internal" href="#asyncio.Semaphore.release" title="asyncio.Semaphore.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a> call.
The counter can never go below zero; when <a class="reference internal" href="#asyncio.Semaphore.acquire" title="asyncio.Semaphore.acquire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">acquire()</span></code></a> finds
that it is zero, it blocks, waiting until some task calls
<a class="reference internal" href="#asyncio.Semaphore.release" title="asyncio.Semaphore.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a>.</p>
<p>The optional <em>value</em> argument gives the initial value for the
internal counter (<code class="docutils literal notranslate"><span class="pre">1</span></code> by default). If the given value is
less than <code class="docutils literal notranslate"><span class="pre">0</span></code> a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised.</p>
<p>The preferred way to use a Semaphore is an <a class="reference internal" href="../reference/compound_stmts.html#async-with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code></a>
statement:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sem</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Semaphore</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="c1"># ... later</span>
<span class="k">async</span> <span class="k">with</span> <span class="n">sem</span><span class="p">:</span>
<span class="c1"># work with shared resource</span>
</pre></div>
</div>
<p>which is equivalent to:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sem</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">Semaphore</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="c1"># ... later</span>
<span class="k">await</span> <span class="n">sem</span><span class="o">.</span><span class="n">acquire</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="c1"># work with shared resource</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">sem</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
</pre></div>
</div>
<dl class="method">
<dt id="asyncio.Semaphore.acquire">
<em class="property">coroutine </em><code class="sig-name descname">acquire</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Semaphore.acquire" title="Permalink to this definition">¶</a></dt>
<dd><p>Acquire a semaphore.</p>
<p>If the internal counter is greater than zero, decrement
it by one and return <code class="docutils literal notranslate"><span class="pre">True</span></code> immediately. If it is zero, wait
until a <a class="reference internal" href="#asyncio.Semaphore.release" title="asyncio.Semaphore.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a> is called and return <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Semaphore.locked">
<code class="sig-name descname">locked</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Semaphore.locked" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if semaphore can not be acquired immediately.</p>
</dd></dl>
<dl class="method">
<dt id="asyncio.Semaphore.release">
<code class="sig-name descname">release</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.Semaphore.release" title="Permalink to this definition">¶</a></dt>
<dd><p>Release a semaphore, incrementing the internal counter by one.
Can wake up a task waiting to acquire the semaphore.</p>
<p>Unlike <a class="reference internal" href="#asyncio.BoundedSemaphore" title="asyncio.BoundedSemaphore"><code class="xref py py-class docutils literal notranslate"><span class="pre">BoundedSemaphore</span></code></a>, <a class="reference internal" href="#asyncio.Semaphore" title="asyncio.Semaphore"><code class="xref py py-class docutils literal notranslate"><span class="pre">Semaphore</span></code></a> allows
making more <code class="docutils literal notranslate"><span class="pre">release()</span></code> calls than <code class="docutils literal notranslate"><span class="pre">acquire()</span></code> calls.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="boundedsemaphore">
<h2>BoundedSemaphore<a class="headerlink" href="#boundedsemaphore" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="asyncio.BoundedSemaphore">
<em class="property">class </em><code class="sig-prename descclassname">asyncio.</code><code class="sig-name descname">BoundedSemaphore</code><span class="sig-paren">(</span><em class="sig-param">value=1</em>, <em class="sig-param">*</em>, <em class="sig-param">loop=None</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncio.BoundedSemaphore" title="Permalink to this definition">¶</a></dt>
<dd><p>A bounded semaphore object. Not thread-safe.</p>
<p>Bounded Semaphore is a version of <a class="reference internal" href="#asyncio.Semaphore" title="asyncio.Semaphore"><code class="xref py py-class docutils literal notranslate"><span class="pre">Semaphore</span></code></a> that raises
a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> in <a class="reference internal" href="#asyncio.Semaphore.release" title="asyncio.Semaphore.release"><code class="xref py py-meth docutils literal notranslate"><span class="pre">release()</span></code></a> if it
increases the internal counter above the initial <em>value</em>.</p>
</dd></dl>
<hr class="docutils" />
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 3.7: </span>Acquiring a lock using <code class="docutils literal notranslate"><span class="pre">await</span> <span class="pre">lock</span></code> or <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span> <span class="pre">lock</span></code> and/or
<a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement (<code class="docutils literal notranslate"><span class="pre">with</span> <span class="pre">await</span> <span class="pre">lock</span></code>, <code class="docutils literal notranslate"><span class="pre">with</span> <span class="pre">(yield</span> <span class="pre">from</span>
<span class="pre">lock)</span></code>) is deprecated. Use <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span> <span class="pre">lock</span></code> instead.</p>
</div>
</div>
</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="#">Synchronization Primitives</a><ul>
<li><a class="reference internal" href="#lock">Lock</a></li>
<li><a class="reference internal" href="#event">Event</a></li>
<li><a class="reference internal" href="#condition">Condition</a></li>
<li><a class="reference internal" href="#semaphore">Semaphore</a></li>
<li><a class="reference internal" href="#boundedsemaphore">BoundedSemaphore</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="asyncio-stream.html"
title="previous chapter">Streams</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="asyncio-subprocess.html"
title="next chapter">Subprocesses</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.7/Doc/library/asyncio-sync.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-subprocess.html" title="Subprocesses"
>next</a> |</li>
<li class="right" >
<a href="asyncio-stream.html" title="Streams"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">3.7.10 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="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="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>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001-2021, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Feb 26, 2021.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.3.1.
</div>
</body>
</html>
