<!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>Built-in Utilities — PyOpenCL 2013.1 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/akdoc.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2013.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: false
};
</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="top" title="PyOpenCL 2013.1 documentation" href="index.html" />
<link rel="next" title="Installation" href="misc.html" />
<link rel="prev" title="Parallel Algorithms" href="algorithm.html" />
</head>
<body>
<div class="related">
<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="misc.html" title="Installation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="algorithm.html" title="Parallel Algorithms"
accesskey="P">previous</a> |</li>
<li><a href="index.html">PyOpenCL 2013.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-pyopencl.tools">
<span id="built-in-utilities"></span><h1>Built-in Utilities<a class="headerlink" href="#module-pyopencl.tools" title="Permalink to this headline">¶</a></h1>
<div class="section" id="memory-pools">
<span id="id1"></span><h2>Memory Pools<a class="headerlink" href="#memory-pools" title="Permalink to this headline">¶</a></h2>
<p>The constructor <a class="reference internal" href="runtime.html#pyopencl.Buffer" title="pyopencl.Buffer"><tt class="xref py py-func docutils literal"><span class="pre">pyopencl.Buffer()</span></tt></a> can consume a fairly large amount of
processing time if it is invoked very frequently. For example, code based on
<tt class="xref py py-class docutils literal"><span class="pre">pyopencl.array.Array</span></tt> can easily run into this issue because a
fresh memory area is allocated for each intermediate result. Memory pools are a
remedy for this problem based on the observation that often many of the block
allocations are of the same sizes as previously used ones.</p>
<p>Then, instead of fully returning the memory to the system and incurring the
associated reallocation overhead, the pool holds on to the memory and uses it
to satisfy future allocations of similarly-sized blocks. The pool reacts
appropriately to out-of-memory conditions as long as all memory allocations
are made through it. Allocations performed from outside of the pool may run
into spurious out-of-memory conditions due to the pool owning much or all of
the available memory.</p>
<dl class="class">
<dt id="pyopencl.tools.PooledBuffer">
<em class="property">class </em><tt class="descclassname">pyopencl.tools.</tt><tt class="descname">PooledBuffer</tt><a class="headerlink" href="#pyopencl.tools.PooledBuffer" title="Permalink to this definition">¶</a></dt>
<dd><p>An object representing a <a class="reference internal" href="#pyopencl.tools.MemoryPool" title="pyopencl.tools.MemoryPool"><tt class="xref py py-class docutils literal"><span class="pre">MemoryPool</span></tt></a>-based allocation of
device memory. Once this object is deleted, its associated device
memory is returned to the pool. This supports the same interface
as <a class="reference internal" href="runtime.html#pyopencl.Buffer" title="pyopencl.Buffer"><tt class="xref py py-class docutils literal"><span class="pre">pyopencl.Buffer</span></tt></a>.</p>
</dd></dl>
<dl class="class">
<dt id="pyopencl.tools.DeferredAllocator">
<em class="property">class </em><tt class="descclassname">pyopencl.tools.</tt><tt class="descname">DeferredAllocator</tt><big>(</big><em>context</em>, <em>mem_flags=pyopencl.mem_flags.READ_WRITE</em><big>)</big><a class="headerlink" href="#pyopencl.tools.DeferredAllocator" title="Permalink to this definition">¶</a></dt>
<dd><p><em>mem_flags</em> takes its values from <tt class="xref py py-class docutils literal"><span class="pre">pyopencl.mem_flags</span></tt> and corresponds
to the <em>flags</em> argument of <a class="reference internal" href="runtime.html#pyopencl.Buffer" title="pyopencl.Buffer"><tt class="xref py py-class docutils literal"><span class="pre">pyopencl.Buffer</span></tt></a>. DeferredAllocator
has the same semantics as regular OpenCL buffer allocation, i.e. it may
promise memory to be available that may (in any call to a buffer-using
CL function) turn out to not exist later on. (Allocations in CL are
bound to contexts, not devices, and memory availability depends on which
device the buffer is used with.)</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version In: </span>version 2013.1, <tt class="xref py py-class docutils literal"><span class="pre">CLAllocator</span></tt> was deprecated and replaced
by <a class="reference internal" href="#pyopencl.tools.DeferredAllocator" title="pyopencl.tools.DeferredAllocator"><tt class="xref py py-class docutils literal"><span class="pre">DeferredAllocator</span></tt></a>.</p>
</div>
<dl class="method">
<dt id="pyopencl.tools.DeferredAllocator.__call__">
<tt class="descname">__call__</tt><big>(</big><em>size</em><big>)</big><a class="headerlink" href="#pyopencl.tools.DeferredAllocator.__call__" title="Permalink to this definition">¶</a></dt>
<dd><p>Allocate a <a class="reference internal" href="runtime.html#pyopencl.Buffer" title="pyopencl.Buffer"><tt class="xref py py-class docutils literal"><span class="pre">pyopencl.Buffer</span></tt></a> of the given <em>size</em>.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="pyopencl.tools.ImmediateAllocator">
<em class="property">class </em><tt class="descclassname">pyopencl.tools.</tt><tt class="descname">ImmediateAllocator</tt><big>(</big><em>queue</em>, <em>mem_flags=pyopencl.mem_flags.READ_WRITE</em><big>)</big><a class="headerlink" href="#pyopencl.tools.ImmediateAllocator" title="Permalink to this definition">¶</a></dt>
<dd><p><em>mem_flags</em> takes its values from <tt class="xref py py-class docutils literal"><span class="pre">pyopencl.mem_flags</span></tt> and corresponds
to the <em>flags</em> argument of <a class="reference internal" href="runtime.html#pyopencl.Buffer" title="pyopencl.Buffer"><tt class="xref py py-class docutils literal"><span class="pre">pyopencl.Buffer</span></tt></a>. DeferredAllocator
has the same semantics as regular OpenCL buffer allocation, i.e. it may
promise memory to be available that later on (in any call to a buffer-using
CL function).</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2013.1.</span></p>
</div>
<dl class="method">
<dt id="pyopencl.tools.ImmediateAllocator.__call__">
<tt class="descname">__call__</tt><big>(</big><em>size</em><big>)</big><a class="headerlink" href="#pyopencl.tools.ImmediateAllocator.__call__" title="Permalink to this definition">¶</a></dt>
<dd><p>Allocate a <a class="reference internal" href="runtime.html#pyopencl.Buffer" title="pyopencl.Buffer"><tt class="xref py py-class docutils literal"><span class="pre">pyopencl.Buffer</span></tt></a> of the given <em>size</em>.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="pyopencl.tools.MemoryPool">
<em class="property">class </em><tt class="descclassname">pyopencl.tools.</tt><tt class="descname">MemoryPool</tt><big>(</big><em>allocator</em><big>)</big><a class="headerlink" href="#pyopencl.tools.MemoryPool" title="Permalink to this definition">¶</a></dt>
<dd><p>A memory pool for OpenCL device memory. <em>allocator</em> must be an instance of
one of the above classes, and should be an <a class="reference internal" href="#pyopencl.tools.ImmediateAllocator" title="pyopencl.tools.ImmediateAllocator"><tt class="xref py py-class docutils literal"><span class="pre">ImmediateAllocator</span></tt></a>.
The memory pool assumes that allocation failures are reported
by the allocator immediately, and not in the OpenCL-typical
deferred manner.</p>
<dl class="attribute">
<dt id="pyopencl.tools.MemoryPool.held_blocks">
<tt class="descname">held_blocks</tt><a class="headerlink" href="#pyopencl.tools.MemoryPool.held_blocks" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of unused blocks being held by this pool.</p>
</dd></dl>
<dl class="attribute">
<dt id="pyopencl.tools.MemoryPool.active_blocks">
<tt class="descname">active_blocks</tt><a class="headerlink" href="#pyopencl.tools.MemoryPool.active_blocks" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of blocks in active use that have been allocated
through this pool.</p>
</dd></dl>
<dl class="method">
<dt id="pyopencl.tools.MemoryPool.allocate">
<tt class="descname">allocate</tt><big>(</big><em>size</em><big>)</big><a class="headerlink" href="#pyopencl.tools.MemoryPool.allocate" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#pyopencl.tools.PooledBuffer" title="pyopencl.tools.PooledBuffer"><tt class="xref py py-class docutils literal"><span class="pre">PooledBuffer</span></tt></a> of the given <em>size</em>.</p>
</dd></dl>
<dl class="method">
<dt id="pyopencl.tools.MemoryPool.__call__">
<tt class="descname">__call__</tt><big>(</big><em>size</em><big>)</big><a class="headerlink" href="#pyopencl.tools.MemoryPool.__call__" title="Permalink to this definition">¶</a></dt>
<dd><p>Synoynm for <a class="reference internal" href="#pyopencl.tools.MemoryPool.allocate" title="pyopencl.tools.MemoryPool.allocate"><tt class="xref py py-meth docutils literal"><span class="pre">allocate()</span></tt></a> to match <tt class="xref py py-class docutils literal"><span class="pre">CLAllocator</span></tt> interface.</p>
</dd></dl>
<dl class="method">
<dt id="pyopencl.tools.MemoryPool.free_held">
<tt class="descname">free_held</tt><big>(</big><big>)</big><a class="headerlink" href="#pyopencl.tools.MemoryPool.free_held" title="Permalink to this definition">¶</a></dt>
<dd><p>Free all unused memory that the pool is currently holding.</p>
</dd></dl>
<dl class="method">
<dt id="pyopencl.tools.MemoryPool.stop_holding">
<tt class="descname">stop_holding</tt><big>(</big><big>)</big><a class="headerlink" href="#pyopencl.tools.MemoryPool.stop_holding" title="Permalink to this definition">¶</a></dt>
<dd><p>Instruct the memory to start immediately freeing memory returned
to it, instead of holding it for future allocations.
Implicitly calls <a class="reference internal" href="#pyopencl.tools.MemoryPool.free_held" title="pyopencl.tools.MemoryPool.free_held"><tt class="xref py py-meth docutils literal"><span class="pre">free_held()</span></tt></a>.
This is useful as a cleanup action when a memory pool falls out
of use.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="cl-object-dependent-caching">
<h2>CL-Object-dependent Caching<a class="headerlink" href="#cl-object-dependent-caching" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="testing">
<h2>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="pyopencl.tools.pytest_generate_tests_for_pyopencl">
<tt class="descclassname">pyopencl.tools.</tt><tt class="descname">pytest_generate_tests_for_pyopencl</tt><big>(</big><em>metafunc</em><big>)</big><a class="headerlink" href="#pyopencl.tools.pytest_generate_tests_for_pyopencl" title="Permalink to this definition">¶</a></dt>
<dd><p>Using the line:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">pyopencl.tools</span> <span class="kn">import</span> <span class="n">pytest_generate_tests_for_pyopencl</span> \
<span class="k">as</span> <span class="n">pytest_generate_tests</span>
</pre></div>
</div>
<p>in your <a class="reference external" href="http://pytest.org">pytest</a> test scripts allows you to use the
arguments <em>ctx_factory</em>, <em>device</em>, or <em>platform</em> in your test functions,
and they will automatically be run for each OpenCL device/platform in the
system, as appropriate.</p>
<p>The following two environment variables are also supported to control
device/platform choice:</p>
<div class="highlight-python"><div class="highlight"><pre>PYOPENCL_TEST=0:0,1;intel=i5,i7
</pre></div>
</div>
</dd></dl>
</div>
<div class="section" id="device-characterization">
<h2>Device Characterization<a class="headerlink" href="#device-characterization" title="Permalink to this headline">¶</a></h2>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Built-in Utilities</a><ul>
<li><a class="reference internal" href="#memory-pools">Memory Pools</a></li>
<li><a class="reference internal" href="#cl-object-dependent-caching">CL-Object-dependent Caching</a></li>
<li><a class="reference internal" href="#testing">Testing</a></li>
<li><a class="reference internal" href="#device-characterization">Device Characterization</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="algorithm.html"
title="previous chapter">Parallel Algorithms</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="misc.html"
title="next chapter">Installation</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input 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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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="misc.html" title="Installation"
>next</a> |</li>
<li class="right" >
<a href="algorithm.html" title="Parallel Algorithms"
>previous</a> |</li>
<li><a href="index.html">PyOpenCL 2013.1 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009, Andreas Kloeckner.
Last updated on Oct 15, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</body>
</html>
