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

253 lines
17 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>pools - Generic pools of resources &#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="queue – Queue class" href="queue.html" />
<link rel="prev" title="greenthread – Green Thread Implementation" href="greenthread.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="queue.html" title="queue – Queue class"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="greenthread.html" title="greenthread – Green Thread Implementation"
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="module-eventlet.pools">
<span id="pools-generic-pools-of-resources"></span><h1><code class="xref py py-mod docutils literal"><span class="pre">pools</span></code> - Generic pools of resources<a class="headerlink" href="#module-eventlet.pools" title="Permalink to this headline"></a></h1>
<dl class="class">
<dt id="eventlet.pools.Pool">
<em class="property">class </em><code class="descclassname">eventlet.pools.</code><code class="descname">Pool</code><span class="sig-paren">(</span><em>min_size=0</em>, <em>max_size=4</em>, <em>order_as_stack=False</em>, <em>create=None</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.pools.Pool" title="Permalink to this definition"></a></dt>
<dd><p>Pool class implements resource limitation and construction.</p>
<p>There are two ways of using Pool: passing a <cite>create</cite> argument or
subclassing. In either case you must provide a way to create
the resource.</p>
<p>When using <cite>create</cite> argument, pass a function with no arguments:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">http_pool</span> <span class="o">=</span> <span class="n">pools</span><span class="o">.</span><span class="n">Pool</span><span class="p">(</span><span class="n">create</span><span class="o">=</span><span class="n">httplib2</span><span class="o">.</span><span class="n">Http</span><span class="p">)</span>
</pre></div>
</div>
<p>If you need to pass arguments, build a nullary function with either
<cite>lambda</cite> expression:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">http_pool</span> <span class="o">=</span> <span class="n">pools</span><span class="o">.</span><span class="n">Pool</span><span class="p">(</span><span class="n">create</span><span class="o">=</span><span class="k">lambda</span><span class="p">:</span> <span class="n">httplib2</span><span class="o">.</span><span class="n">Http</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">90</span><span class="p">))</span>
</pre></div>
</div>
<p>or <a class="reference external" href="https://docs.python.org/2/library/functools.html#functools.partial" title="(in Python v2.7)"><code class="xref py py-func docutils literal"><span class="pre">functools.partial()</span></code></a>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">functools</span> <span class="k">import</span> <span class="n">partial</span>
<span class="n">http_pool</span> <span class="o">=</span> <span class="n">pools</span><span class="o">.</span><span class="n">Pool</span><span class="p">(</span><span class="n">create</span><span class="o">=</span><span class="n">partial</span><span class="p">(</span><span class="n">httplib2</span><span class="o">.</span><span class="n">Http</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="mi">90</span><span class="p">))</span>
</pre></div>
</div>
<p>When subclassing, define only the <a class="reference internal" href="#eventlet.pools.Pool.create" title="eventlet.pools.Pool.create"><code class="xref py py-meth docutils literal"><span class="pre">create()</span></code></a> method
to implement the desired resource:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyPool</span><span class="p">(</span><span class="n">pools</span><span class="o">.</span><span class="n">Pool</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">create</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="n">MyObject</span><span class="p">()</span>
</pre></div>
</div>
<p>If using 2.5 or greater, the <a class="reference internal" href="#eventlet.pools.Pool.item" title="eventlet.pools.Pool.item"><code class="xref py py-meth docutils literal"><span class="pre">item()</span></code></a> method acts as a context manager;
that&#8217;s the best way to use it:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">mypool</span><span class="o">.</span><span class="n">item</span><span class="p">()</span> <span class="k">as</span> <span class="n">thing</span><span class="p">:</span>
<span class="n">thing</span><span class="o">.</span><span class="n">dostuff</span><span class="p">()</span>
</pre></div>
</div>
<p>The maximum size of the pool can be modified at runtime via
the <a class="reference internal" href="#eventlet.pools.Pool.resize" title="eventlet.pools.Pool.resize"><code class="xref py py-meth docutils literal"><span class="pre">resize()</span></code></a> method.</p>
<p>Specifying a non-zero <em>min-size</em> argument pre-populates the pool with
<em>min_size</em> items. <em>max-size</em> sets a hard limit to the size of the pool &#8211;
it cannot contain any more items than <em>max_size</em>, and if there are already
<em>max_size</em> items &#8216;checked out&#8217; of the pool, the pool will cause any
greenthread calling <a class="reference internal" href="#eventlet.pools.Pool.get" title="eventlet.pools.Pool.get"><code class="xref py py-meth docutils literal"><span class="pre">get()</span></code></a> to cooperatively yield until an item
is <a class="reference internal" href="#eventlet.pools.Pool.put" title="eventlet.pools.Pool.put"><code class="xref py py-meth docutils literal"><span class="pre">put()</span></code></a> in.</p>
<dl class="method">
<dt id="eventlet.pools.Pool.create">
<code class="descname">create</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.pools.Pool.create" title="Permalink to this definition"></a></dt>
<dd><p>Generate a new pool item. In order for the pool to
function, either this method must be overriden in a subclass
or the pool must be constructed with the <cite>create</cite> argument.
It accepts no arguments and returns a single instance of
whatever thing the pool is supposed to contain.</p>
<p>In general, <a class="reference internal" href="#eventlet.pools.Pool.create" title="eventlet.pools.Pool.create"><code class="xref py py-meth docutils literal"><span class="pre">create()</span></code></a> is called whenever the pool exceeds its
previous high-water mark of concurrently-checked-out-items. In other
words, in a new pool with <em>min_size</em> of 0, the very first call
to <a class="reference internal" href="#eventlet.pools.Pool.get" title="eventlet.pools.Pool.get"><code class="xref py py-meth docutils literal"><span class="pre">get()</span></code></a> will result in a call to <a class="reference internal" href="#eventlet.pools.Pool.create" title="eventlet.pools.Pool.create"><code class="xref py py-meth docutils literal"><span class="pre">create()</span></code></a>. If the first
caller calls <a class="reference internal" href="#eventlet.pools.Pool.put" title="eventlet.pools.Pool.put"><code class="xref py py-meth docutils literal"><span class="pre">put()</span></code></a> before some other caller calls <a class="reference internal" href="#eventlet.pools.Pool.get" title="eventlet.pools.Pool.get"><code class="xref py py-meth docutils literal"><span class="pre">get()</span></code></a>,
then the first item will be returned, and <a class="reference internal" href="#eventlet.pools.Pool.create" title="eventlet.pools.Pool.create"><code class="xref py py-meth docutils literal"><span class="pre">create()</span></code></a> will not be
called a second time.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.pools.Pool.free">
<code class="descname">free</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.pools.Pool.free" title="Permalink to this definition"></a></dt>
<dd><p>Return the number of free items in the pool. This corresponds
to the number of <a class="reference internal" href="#eventlet.pools.Pool.get" title="eventlet.pools.Pool.get"><code class="xref py py-meth docutils literal"><span class="pre">get()</span></code></a> calls needed to empty the pool.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.pools.Pool.get">
<code class="descname">get</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.pools.Pool.get" title="Permalink to this definition"></a></dt>
<dd><p>Return an item from the pool, when one is available. This may
cause the calling greenthread to block.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.pools.Pool.item">
<code class="descname">item</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.pools.Pool.item" title="Permalink to this definition"></a></dt>
<dd><p>Get an object out of the pool, for use with with statement.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">eventlet</span> <span class="k">import</span> <span class="n">pools</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pool</span> <span class="o">=</span> <span class="n">pools</span><span class="o">.</span><span class="n">TokenPool</span><span class="p">(</span><span class="n">max_size</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">pool</span><span class="o">.</span><span class="n">item</span><span class="p">()</span> <span class="k">as</span> <span class="n">obj</span><span class="p">:</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;got token&quot;</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">got token</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pool</span><span class="o">.</span><span class="n">free</span><span class="p">()</span>
<span class="go">4</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="eventlet.pools.Pool.put">
<code class="descname">put</code><span class="sig-paren">(</span><em>item</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.pools.Pool.put" title="Permalink to this definition"></a></dt>
<dd><p>Put an item back into the pool, when done. This may
cause the putting greenthread to block.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.pools.Pool.resize">
<code class="descname">resize</code><span class="sig-paren">(</span><em>new_size</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.pools.Pool.resize" title="Permalink to this definition"></a></dt>
<dd><p>Resize the pool to <em>new_size</em>.</p>
<p>Adjusting this number does not affect existing items checked out of
the pool, nor on any greenthreads who are waiting for an item to free
up. Some indeterminate number of <a class="reference internal" href="#eventlet.pools.Pool.get" title="eventlet.pools.Pool.get"><code class="xref py py-meth docutils literal"><span class="pre">get()</span></code></a>/<a class="reference internal" href="#eventlet.pools.Pool.put" title="eventlet.pools.Pool.put"><code class="xref py py-meth docutils literal"><span class="pre">put()</span></code></a>
cycles will be necessary before the new maximum size truly matches
the actual operation of the pool.</p>
</dd></dl>
<dl class="method">
<dt id="eventlet.pools.Pool.waiting">
<code class="descname">waiting</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.pools.Pool.waiting" title="Permalink to this definition"></a></dt>
<dd><p>Return the number of routines waiting for a pool item.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="eventlet.pools.TokenPool">
<em class="property">class </em><code class="descclassname">eventlet.pools.</code><code class="descname">TokenPool</code><span class="sig-paren">(</span><em>min_size=0</em>, <em>max_size=4</em>, <em>order_as_stack=False</em>, <em>create=None</em><span class="sig-paren">)</span><a class="headerlink" href="#eventlet.pools.TokenPool" title="Permalink to this definition"></a></dt>
<dd><p>A pool which gives out tokens (opaque unique objects), which indicate
that the coroutine which holds the token has a right to consume some
limited resource.</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="greenthread.html"
title="previous chapter"><code class="docutils literal"><span class="pre">greenthread</span></code> &#8211; Green Thread Implementation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="queue.html"
title="next chapter"><code class="docutils literal"><span class="pre">queue</span></code> &#8211; Queue class</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/modules/pools.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="queue.html" title="queue – Queue class"
>next</a> |</li>
<li class="right" >
<a href="greenthread.html" title="greenthread – Green Thread Implementation"
>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