openstack
/
deb-python-eventlet
Code Issues Proposed changes
deb-python-eventlet/doc/modules/semaphore.html

308 lines
19 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>semaphore – Semaphore classes &#8212; Eventlet 0.21.0 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.21.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="timeout – Universal Timeouts" href="timeout.html" />
<link rel="prev" title="queue – Queue class" href="queue.html" />
</head>
<body role="document">
<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="timeout.html" title="timeout – Universal Timeouts"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="queue.html" title="queue – Queue class"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Eventlet 0.21.0 documentation</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../modules.html" accesskey="U">Module Reference</a> &#187;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="semaphore-semaphore-classes">
<h1><code class="xref py py-mod docutils literal"><span class="pre">semaphore</span></code> &#8211; Semaphore classes<a class="headerlink" href="#semaphore-semaphore-classes" title="Permalink to this headline"></a></h1>
<dl class="class">
<dt id="eventlet.semaphore.Semaphore">
<em class="property">class </em><code class="descclassname">eventlet.semaphore.</code><code class="descname">Semaphore</code><span class="sig-paren">(</span><em>value=1</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.Semaphore" title="Permalink to this definition"></a></dt>
<dd><p>An unbounded semaphore.
Optionally initialize with a resource <em>count</em>, then <code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code> and
<code class="xref py py-meth docutils literal"><span class="pre">release()</span></code> resources as needed. Attempting to <code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code> when
<em>count</em> is zero suspends the calling greenthread until <em>count</em> becomes
nonzero again.</p>
<p>This is API-compatible with <a class="reference external" href="https://docs.python.org/2/library/threading.html#threading.Semaphore" title="(in Python v2.7)"><code class="xref py py-class docutils literal"><span class="pre">threading.Semaphore</span></code></a>.</p>
<p>It is a context manager, and thus can be used in a with block:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sem</span> <span class="o">=</span> <span class="n">Semaphore</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="k">with</span> <span class="n">sem</span><span class="p">:</span>
<span class="n">do_some_stuff</span><span class="p">()</span>
</pre></div>
</div>
<p>If not specified, <em>value</em> defaults to 1.</p>
<p>It is possible to limit acquire time:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sem</span> <span class="o">=</span> <span class="n">Semaphore</span><span class="p">()</span>
<span class="n">ok</span> <span class="o">=</span> <span class="n">sem</span><span class="o">.</span><span class="n">acquire</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mf">0.1</span><span class="p">)</span>
<span class="c1"># True if acquired, False if timed out.</span>
</pre></div>
</div>
<dl class="method">
<dt id="eventlet.semaphore.Semaphore.acquire">
<code class="descname">acquire</code><span class="sig-paren">(</span><em>blocking=True</em>, <em>timeout=None</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.Semaphore.acquire" title="Permalink to this definition"></a></dt>
<dd><p>Acquire a semaphore.</p>
<p>When invoked without arguments: if the internal counter is larger than
zero on entry, decrement it by one and return immediately. If it is zero
on entry, block, waiting until some other thread has called release() to
make it larger than zero. This is done with proper interlocking so that
if multiple acquire() calls are blocked, release() will wake exactly one
of them up. The implementation may pick one at random, so the order in
which blocked threads are awakened should not be relied on. There is no
return value in this case.</p>
<p>When invoked with blocking set to true, do the same thing as when called
without arguments, and return true.</p>
<p>When invoked with blocking set to false, do not block. If a call without
an argument would block, return false immediately; otherwise, do the
same thing as when called without arguments, and return true.</p>
<p>Timeout value must be strictly positive.</p>
</dd></dl>
<dl class="attribute">
<dt id="eventlet.semaphore.Semaphore.balance">
<code class="descname">balance</code><a class="headerlink" href="#eventlet.semaphore.Semaphore.balance" title="Permalink to this definition"></a></dt>
<dd><p>An integer value that represents how many new calls to
<code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code> or <code class="xref py py-meth docutils literal"><span class="pre">release()</span></code> would be needed to get the counter to
0. If it is positive, then its value is the number of acquires that can
happen before the next acquire would block. If it is negative, it is
the negative of the number of releases that would be required in order
to make the counter 0 again (one more release would push the counter to
1 and unblock acquirers). It takes into account how many greenthreads
are currently blocking in <code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.semaphore.Semaphore.bounded">
<code class="descname">bounded</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.Semaphore.bounded" title="Permalink to this definition"></a></dt>
<dd><p>Returns False; for consistency with
<a class="reference internal" href="#eventlet.semaphore.CappedSemaphore" title="eventlet.semaphore.CappedSemaphore"><code class="xref py py-class docutils literal"><span class="pre">CappedSemaphore</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.semaphore.Semaphore.locked">
<code class="descname">locked</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.Semaphore.locked" title="Permalink to this definition"></a></dt>
<dd><p>Returns true if a call to acquire would block.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.semaphore.Semaphore.release">
<code class="descname">release</code><span class="sig-paren">(</span><em>blocking=True</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.Semaphore.release" title="Permalink to this definition"></a></dt>
<dd><p>Release a semaphore, incrementing the internal counter by one. When
it was zero on entry and another thread is waiting for it to become
larger than zero again, wake up that thread.</p>
<p>The <em>blocking</em> argument is for consistency with CappedSemaphore and is
ignored</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="eventlet.semaphore.BoundedSemaphore">
<em class="property">class </em><code class="descclassname">eventlet.semaphore.</code><code class="descname">BoundedSemaphore</code><span class="sig-paren">(</span><em>value=1</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.BoundedSemaphore" title="Permalink to this definition"></a></dt>
<dd><p>A bounded semaphore checks to make sure its current value doesn&#8217;t exceed
its initial value. If it does, ValueError is raised. In most situations
semaphores are used to guard resources with limited capacity. If the
semaphore is released too many times it&#8217;s a sign of a bug. If not given,
<em>value</em> defaults to 1.</p>
<dl class="method">
<dt id="eventlet.semaphore.BoundedSemaphore.release">
<code class="descname">release</code><span class="sig-paren">(</span><em>blocking=True</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.BoundedSemaphore.release" title="Permalink to this definition"></a></dt>
<dd><p>Release a semaphore, incrementing the internal counter by one. If
the counter would exceed the initial value, raises ValueError. When
it was zero on entry and another thread is waiting for it to become
larger than zero again, wake up that thread.</p>
<p>The <em>blocking</em> argument is for consistency with <code class="xref py py-class docutils literal"><span class="pre">CappedSemaphore</span></code>
and is ignored</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="eventlet.semaphore.CappedSemaphore">
<em class="property">class </em><code class="descclassname">eventlet.semaphore.</code><code class="descname">CappedSemaphore</code><span class="sig-paren">(</span><em>count</em>, <em>limit</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.CappedSemaphore" title="Permalink to this definition"></a></dt>
<dd><p>A blockingly bounded semaphore.</p>
<p>Optionally initialize with a resource <em>count</em>, then <code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code> and
<code class="xref py py-meth docutils literal"><span class="pre">release()</span></code> resources as needed. Attempting to <code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code> when
<em>count</em> is zero suspends the calling greenthread until count becomes nonzero
again. Attempting to <code class="xref py py-meth docutils literal"><span class="pre">release()</span></code> after <em>count</em> has reached <em>limit</em>
suspends the calling greenthread until <em>count</em> becomes less than <em>limit</em>
again.</p>
<p>This has the same API as <a class="reference external" href="https://docs.python.org/2/library/threading.html#threading.Semaphore" title="(in Python v2.7)"><code class="xref py py-class docutils literal"><span class="pre">threading.Semaphore</span></code></a>, though its
semantics and behavior differ subtly due to the upper limit on calls
to <code class="xref py py-meth docutils literal"><span class="pre">release()</span></code>. It is <strong>not</strong> compatible with
<code class="xref py py-class docutils literal"><span class="pre">threading.BoundedSemaphore</span></code> because it blocks when reaching <em>limit</em>
instead of raising a ValueError.</p>
<p>It is a context manager, and thus can be used in a with block:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sem</span> <span class="o">=</span> <span class="n">CappedSemaphore</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="k">with</span> <span class="n">sem</span><span class="p">:</span>
<span class="n">do_some_stuff</span><span class="p">()</span>
</pre></div>
</div>
<dl class="method">
<dt id="eventlet.semaphore.CappedSemaphore.acquire">
<code class="descname">acquire</code><span class="sig-paren">(</span><em>blocking=True</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.CappedSemaphore.acquire" title="Permalink to this definition"></a></dt>
<dd><p>Acquire a semaphore.</p>
<p>When invoked without arguments: if the internal counter is larger than
zero on entry, decrement it by one and return immediately. If it is zero
on entry, block, waiting until some other thread has called release() to
make it larger than zero. This is done with proper interlocking so that
if multiple acquire() calls are blocked, release() will wake exactly one
of them up. The implementation may pick one at random, so the order in
which blocked threads are awakened should not be relied on. There is no
return value in this case.</p>
<p>When invoked with blocking set to true, do the same thing as when called
without arguments, and return true.</p>
<p>When invoked with blocking set to false, do not block. If a call without
an argument would block, return false immediately; otherwise, do the
same thing as when called without arguments, and return true.</p>
</dd></dl>
<dl class="attribute">
<dt id="eventlet.semaphore.CappedSemaphore.balance">
<code class="descname">balance</code><a class="headerlink" href="#eventlet.semaphore.CappedSemaphore.balance" title="Permalink to this definition"></a></dt>
<dd><p>An integer value that represents how many new calls to
<code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code> or <code class="xref py py-meth docutils literal"><span class="pre">release()</span></code> would be needed to get the counter to
0. If it is positive, then its value is the number of acquires that can
happen before the next acquire would block. If it is negative, it is
the negative of the number of releases that would be required in order
to make the counter 0 again (one more release would push the counter to
1 and unblock acquirers). It takes into account how many greenthreads
are currently blocking in <code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code> and <code class="xref py py-meth docutils literal"><span class="pre">release()</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.semaphore.CappedSemaphore.bounded">
<code class="descname">bounded</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.CappedSemaphore.bounded" title="Permalink to this definition"></a></dt>
<dd><p>Returns true if a call to release would block.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.semaphore.CappedSemaphore.locked">
<code class="descname">locked</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.CappedSemaphore.locked" title="Permalink to this definition"></a></dt>
<dd><p>Returns true if a call to acquire would block.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.semaphore.CappedSemaphore.release">
<code class="descname">release</code><span class="sig-paren">(</span><em>blocking=True</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.semaphore.CappedSemaphore.release" title="Permalink to this definition"></a></dt>
<dd><p>Release a semaphore. In this class, this behaves very much like
an <code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code> but in the opposite direction.</p>
<p>Imagine the docs of <code class="xref py py-meth docutils literal"><span class="pre">acquire()</span></code> here, but with every direction
reversed. When calling this method, it will block if the internal
counter is greater than or equal to <em>limit</em>.</p>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="queue.html"
title="previous chapter"><code class="docutils literal"><span class="pre">queue</span></code> &#8211; Queue class</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="timeout.html"
title="next chapter"><code class="docutils literal"><span class="pre">timeout</span></code> &#8211; Universal Timeouts</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/modules/semaphore.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</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="timeout.html" title="timeout – Universal Timeouts"
>next</a> |</li>
<li class="right" >
<a href="queue.html" title="queue – Queue class"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Eventlet 0.21.0 documentation</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../modules.html" >Module Reference</a> &#187;</li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2005-2010, Eventlet Contributors.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.
</div>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-42952223-1', 'eventlet.net');
ga('send', 'pageview');
</script>
</body>
</html>
View Git Blame Copy Permalink