openstack/deb-python-eventlet
Code Issues Proposed changes
Files
d75f9506e5c4a8413e2182149bfdd92c4323019e
deb-python-eventlet/doc/modules/timeout.html
Sergey Shepelev d75f9506e5 Website built from v0.20.0-3-gb1d11e3
2016-12-12 01:37:21 +03:00

246 lines
15 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>timeout – Universal Timeouts &#8212; Eventlet 0.20.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.20.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="websocket – Websocket Server" href="websocket.html" />
<link rel="prev" title="semaphore – Semaphore classes" href="semaphore.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="websocket.html" title="websocket – Websocket Server"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="semaphore.html" title="semaphore – Semaphore classes"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Eventlet 0.20.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="timeout-universal-timeouts">
<h1><code class="xref py py-mod docutils literal"><span class="pre">timeout</span></code> &#8211; Universal Timeouts<a class="headerlink" href="#timeout-universal-timeouts" title="Permalink to this headline"></a></h1>
<dl class="class">
<dt id="eventlet.timeout.Timeout">
<em class="property">class </em><code class="descclassname">eventlet.timeout.</code><code class="descname">Timeout</code><a class="headerlink" href="#eventlet.timeout.Timeout" title="Permalink to this definition"></a></dt>
<dd><p>Raises <em>exception</em> in the current greenthread after <em>timeout</em> seconds:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">timeout</span> <span class="o">=</span> <span class="n">Timeout</span><span class="p">(</span><span class="n">seconds</span><span class="p">,</span> <span class="n">exception</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="o">...</span> <span class="c1"># execution here is limited by timeout</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">timeout</span><span class="o">.</span><span class="n">cancel</span><span class="p">()</span>
</pre></div>
</div>
<p>When <em>exception</em> is omitted or is <code class="docutils literal"><span class="pre">None</span></code>, the <code class="xref py py-class docutils literal"><span class="pre">Timeout</span></code> instance
itself is raised:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Timeout</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">eventlet</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.2</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">Timeout</span>: <span class="n">0.1 seconds</span>
</pre></div>
</div>
<p>You can use the <code class="docutils literal"><span class="pre">with</span></code> statement for additional convenience:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">Timeout</span><span class="p">(</span><span class="n">seconds</span><span class="p">,</span> <span class="n">exception</span><span class="p">)</span> <span class="k">as</span> <span class="n">timeout</span><span class="p">:</span>
<span class="k">pass</span> <span class="c1"># ... code block ...</span>
</pre></div>
</div>
<p>This is equivalent to the try/finally block in the first example.</p>
<p>There is an additional feature when using the <code class="docutils literal"><span class="pre">with</span></code> statement: if
<em>exception</em> is <code class="docutils literal"><span class="pre">False</span></code>, the timeout is still raised, but the with
statement suppresses it, so the code outside the with-block won&#8217;t see it:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="kc">None</span>
<span class="k">with</span> <span class="n">Timeout</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="kc">False</span><span class="p">):</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">mysock</span><span class="o">.</span><span class="n">makefile</span><span class="p">()</span><span class="o">.</span><span class="n">readline</span><span class="p">()</span>
<span class="k">if</span> <span class="n">data</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<span class="o">...</span> <span class="c1"># 5 seconds passed without reading a line</span>
<span class="k">else</span><span class="p">:</span>
<span class="o">...</span> <span class="c1"># a line was read within 5 seconds</span>
</pre></div>
</div>
<p>As a very special case, if <em>seconds</em> is None, the timer is not scheduled,
and is only useful if you&#8217;re planning to raise it directly.</p>
<p>There are two Timeout caveats to be aware of:</p>
<ul class="simple">
<li>If the code block in the try/finally or with-block never cooperatively yields, the timeout cannot be raised. In Eventlet, this should rarely be a problem, but be aware that you cannot time out CPU-only operations with this class.</li>
<li>If the code block catches and doesn&#8217;t re-raise <code class="xref py py-class docutils literal"><span class="pre">BaseException</span></code> (for example, with <code class="docutils literal"><span class="pre">except:</span></code>), then it will catch the Timeout exception, and might not abort as intended.</li>
</ul>
<p>When catching timeouts, keep in mind that the one you catch may not be the
one you set; if you plan on silencing a timeout, always check that it&#8217;s the
same instance that you set:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">timeout</span> <span class="o">=</span> <span class="n">Timeout</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="o">...</span>
<span class="k">except</span> <span class="n">Timeout</span> <span class="k">as</span> <span class="n">t</span><span class="p">:</span>
<span class="k">if</span> <span class="n">t</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">timeout</span><span class="p">:</span>
<span class="k">raise</span> <span class="c1"># not my timeout</span>
</pre></div>
</div>
<dl class="method">
<dt id="eventlet.timeout.eventlet.timeout.Timeout.Timeout.cancel">
<code class="descclassname">Timeout.</code><code class="descname">cancel</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.timeout.eventlet.timeout.Timeout.Timeout.cancel" title="Permalink to this definition"></a></dt>
<dd><p>If the timeout is pending, cancel it. If not using
Timeouts in <code class="docutils literal"><span class="pre">with</span></code> statements, always call cancel() in a
<code class="docutils literal"><span class="pre">finally</span></code> after the block of code that is getting timed out.
If not canceled, the timeout will be raised later on, in some
unexpected section of the application.</p>
</dd></dl>
<dl class="attribute">
<dt id="eventlet.timeout.eventlet.timeout.Timeout.Timeout.pending">
<code class="descclassname">Timeout.</code><code class="descname">pending</code><a class="headerlink" href="#eventlet.timeout.eventlet.timeout.Timeout.Timeout.pending" title="Permalink to this definition"></a></dt>
<dd><p>True if the timeout is scheduled to be raised.</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="eventlet.timeout.with_timeout">
<code class="descclassname">eventlet.timeout.</code><code class="descname">with_timeout</code><span class="sig-paren">(</span><em>seconds</em>, <em>function</em>, <em>*args</em>, <em>**kwds</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.timeout.with_timeout" title="Permalink to this definition"></a></dt>
<dd><p>Wrap a call to some (yielding) function with a timeout; if the called
function fails to return before the timeout, cancel it and return a flag
value.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>seconds</strong> (<a class="reference external" href="https://docs.python.org/2/library/functions.html#int" title="(in Python v2.7)"><em>int</em></a><em> or </em><a class="reference external" href="https://docs.python.org/2/library/functions.html#float" title="(in Python v2.7)"><em>float</em></a>) &#8211; seconds before timeout occurs</li>
<li><strong>func</strong> &#8211; the callable to execute with a timeout; it must cooperatively yield, or else the timeout will not be able to trigger</li>
<li><strong>*args</strong> &#8211; positional arguments to pass to <em>func</em></li>
<li><strong>**kwds</strong> &#8211; keyword arguments to pass to <em>func</em></li>
<li><strong>timeout_value</strong> &#8211; value to return if timeout occurs (by default raises
<code class="xref py py-class docutils literal"><span class="pre">Timeout</span></code>)</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first">Value returned by <em>func</em> if <em>func</em> returns before <em>seconds</em>, else
<em>timeout_value</em> if provided, else raises <code class="xref py py-class docutils literal"><span class="pre">Timeout</span></code>.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><p class="first"><a class="reference internal" href="../basic_usage.html#eventlet.Timeout" title="eventlet.Timeout"><strong>Timeout</strong></a> &#8211; if <em>func</em> times out and no <code class="docutils literal"><span class="pre">timeout_value</span></code> has
been provided.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Exception:</th><td class="field-body"><p class="first last">Any exception raised by <em>func</em></p>
</td>
</tr>
</tbody>
</table>
<p>Example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">with_timeout</span><span class="p">(</span><span class="mi">30</span><span class="p">,</span> <span class="n">urllib2</span><span class="o">.</span><span class="n">open</span><span class="p">,</span> <span class="s1">&#39;http://www.google.com/&#39;</span><span class="p">,</span> <span class="n">timeout_value</span><span class="o">=</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Here <em>data</em> is either the result of the <code class="docutils literal"><span class="pre">get()</span></code> call, or the empty string
if it took too long to return. Any exception raised by the <code class="docutils literal"><span class="pre">get()</span></code> call
is passed through to the caller.</p>
</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="semaphore.html"
title="previous chapter"><code class="docutils literal"><span class="pre">semaphore</span></code> &#8211; Semaphore classes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="websocket.html"
title="next chapter"><code class="docutils literal"><span class="pre">websocket</span></code> &#8211; Websocket Server</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/modules/timeout.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="websocket.html" title="websocket – Websocket Server"
>next</a> |</li>
<li class="right" >
<a href="semaphore.html" title="semaphore – Semaphore classes"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Eventlet 0.20.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