Permalink
Browse files

Updated doc release: dev

  • Loading branch information...
1 parent 3086834 commit 2d644dba74df2b0971e1509f6e0b300feb94ee65 @markflorisson markflorisson committed Apr 4, 2013
Showing with 361 additions and 206 deletions.
  1. +1 −1 dev/.buildinfo
  2. +53 −0 dev/_sources/doc/interface_c.txt
  3. +4 −1 dev/_sources/doc/roadmap.txt
  4. +5 −5 dev/doc/architecture.html
  5. +5 −5 dev/doc/arrays.html
  6. +5 −5 dev/doc/doctest.html
  7. +5 −5 dev/doc/examples.html
  8. +66 −5 dev/doc/interface_c.html
  9. +5 −5 dev/doc/ir.html
  10. +5 −5 dev/doc/modules/ast_constant_folding.html
  11. +5 −5 dev/doc/modules/ast_translate.html
  12. +5 −5 dev/doc/modules/ast_type_inference.html
  13. +5 −5 dev/doc/modules/cfg.html
  14. +5 −5 dev/doc/modules/closure.html
  15. +5 −5 dev/doc/modules/decorators.html
  16. +5 −5 dev/doc/modules/functions.html
  17. +5 −5 dev/doc/modules/llvm_types.html
  18. +5 −5 dev/doc/modules/minivect.html
  19. +5 −5 dev/doc/modules/multiarray_api.html
  20. +5 −5 dev/doc/modules/naming.html
  21. +5 −5 dev/doc/modules/ndarray_helpers.html
  22. +5 −5 dev/doc/modules/nodes.html
  23. +27 −5 dev/doc/modules/numba.html
  24. +5 −5 dev/doc/modules/pipeline.html
  25. +5 −5 dev/doc/modules/pycc.html
  26. +5 −5 dev/doc/modules/stdio_util.html
  27. +5 −5 dev/doc/modules/symtab.html
  28. +5 −5 dev/doc/modules/transforms.html
  29. +5 −5 dev/doc/modules/translate.html
  30. +5 −5 dev/doc/modules/utils.html
  31. +5 −5 dev/doc/modules/visitors.html
  32. +5 −5 dev/doc/pycc.html
  33. +5 −5 dev/doc/pythonstuff.html
  34. +5 −5 dev/doc/reference.html
  35. +5 −5 dev/doc/releases.html
  36. +11 −6 dev/doc/roadmap.html
  37. +5 −5 dev/doc/type_inference.html
  38. +5 −5 dev/doc/types.html
  39. +5 −5 dev/doc/userguide.html
  40. +17 −7 dev/genindex.html
  41. +6 −5 dev/index.html
  42. BIN dev/objects.inv
  43. +5 −5 dev/py-modindex.html
  44. +5 −5 dev/search.html
  45. +1 −1 dev/searchindex.js
View
@@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 436c99319d897513a51f7107c1a0c5a5
+config: f4a331eda80038ffc6933d7f110cfd4c
tags: fbb0d17656682115ca4d033fb2f83ba1
@@ -144,6 +144,59 @@ as a Python object. We can verify that our modulo function works in pure Python:
and intrinsics. This is the responsibility of the user. Fortunately,
the validity can be quickly verified :)
+Using Numba Functions in External Code
+======================================
+
+Users can take the address of a numba compiled function using ``numba.addressof``:
+
+.. function:: addressof(jit_func, propagate=True)
+
+ Take the address of ``jit_func`` as a ctypes function. ``propagate`` indicates
+ whether uncaught exceptions propogate or are written to stderr.
+
+::
+
+ @jit(int32(int32, int32))
+ def mul(a, b):
+ return a * b
+
+ cmul = numba.addressof(mul)
+ print cmul(5, 2)
+
+ # Get the address as an Python int
+ addr_int = ctypes.cast(cmul, ctypes.c_void_p).value
+ print hex(addr_int)
+
+Callers can currently check for exceptions (where appropriate) using
+``PyErr_Occurred()`` (which requires the GIL).
+
+``nopython`` functions
+which do not directly or indirectly call functions requiring the GIL or
+use the ``with python`` construct can be called without the GIL. Numba
+does not check whether this is valid, nor does it currently acquire the GIL.
+
+Currently supported bad values for return types:
+
+================= =============
+Return Type Bad Value
+================= =============
+``object_`` ``NULL``
+``floating`` ``NaN``
+================= =============
+
+These can be checked as follows:
+
+.. code-block:: c
+
+ float ret = my_numba_func(...);
+ if (ret != ret && PyErr_Occurred()) {
+ // Handle error
+ }
+
+The error indicator for integer values is currently undecided, since
+constants in LLVM bitcode are printed in decimal form, but hex codes
+can be a better choice for other scenarios.
+
References
==========
.. [#] http://llvm.org/docs/LangRef.html#srem-instruction
@@ -198,7 +198,7 @@ function::
We can allow specifying an exception model:
- * ``write_unraisable=True``: This does not propagate, but uses
+ * ``propagate=False``: This does not propagate, but uses
PyErr_WriteUnraisable
* ``propagate=True``: Implies ``write_unraisable=False``. Callers
@@ -208,6 +208,9 @@ We can allow specifying an exception model:
- int -> 0xdeadbeef (``ret == 0xdeadbeef && NumbaErr_Occurred()``)
- float -> float('nan') (``ret != ret && NumbaErr_Occurred()``)
+.. NOTE:: We have ``numba.addressof()``, but we don't have ``NumbaErr_Occurred()``
+ yet.
+
Debug info
----------
GDB Backtraces!
View
@@ -8,7 +8,7 @@
<head>
<meta charset="utf-8" />
- <title>Numba Architecture &mdash; numba 0.7.2-278-ga8a2104-dirty documentation</title>
+ <title>Numba Architecture &mdash; numba 0.7.2-283-gc4ecc2c-dirty documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
@@ -35,7 +35,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '0.7.2-278-ga8a2104-dirty',
+ VERSION: '0.7.2-283-gc4ecc2c-dirty',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
@@ -59,7 +59,7 @@
});
});
</script>
- <link rel="top" title="numba 0.7.2-278-ga8a2104-dirty documentation" href="../index.html" />
+ <link rel="top" title="numba 0.7.2-283-gc4ecc2c-dirty documentation" href="../index.html" />
<link rel="next" title="Numba IR Stages" href="ir.html" />
<link rel="prev" title="Release Notes" href="releases.html" />
</head>
@@ -72,7 +72,7 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
- <a class="brand" href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a>
+ <a class="brand" href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a>
<div class="nav-collapse collapse">
<ul class="nav pull-right">
@@ -442,7 +442,7 @@ <h2><a class="toc-backref" href="#id15">Appendix</a><a class="headerlink" href="
<li><a href="../py-modindex.html" title="Python Module Index" >modules</a></li>
<li><a href="ir.html" title="Numba IR Stages" >next</a></li>
<li><a href="releases.html" title="Release Notes" >previous</a></li>
- <li><a href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a></li>
+ <li><a href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a></li>
</ul>
</div>
View
@@ -8,7 +8,7 @@
<head>
<meta charset="utf-8" />
- <title>Arrays &mdash; numba 0.7.2-278-ga8a2104-dirty documentation</title>
+ <title>Arrays &mdash; numba 0.7.2-283-gc4ecc2c-dirty documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
@@ -35,7 +35,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '0.7.2-278-ga8a2104-dirty',
+ VERSION: '0.7.2-283-gc4ecc2c-dirty',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
@@ -59,7 +59,7 @@
});
});
</script>
- <link rel="top" title="numba 0.7.2-278-ga8a2104-dirty documentation" href="../index.html" />
+ <link rel="top" title="numba 0.7.2-283-gc4ecc2c-dirty documentation" href="../index.html" />
<link rel="next" title="Interfacing with C" href="interface_c.html" />
<link rel="prev" title="Python Functionality" href="pythonstuff.html" />
</head>
@@ -72,7 +72,7 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
- <a class="brand" href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a>
+ <a class="brand" href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a>
<div class="nav-collapse collapse">
<ul class="nav pull-right">
@@ -446,7 +446,7 @@ <h3>Building ufuncs using &#64;vectorize<a class="headerlink" href="#building-uf
<li><a href="../py-modindex.html" title="Python Module Index" >modules</a></li>
<li><a href="interface_c.html" title="Interfacing with C" >next</a></li>
<li><a href="pythonstuff.html" title="Python Functionality" >previous</a></li>
- <li><a href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a></li>
+ <li><a href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a></li>
</ul>
</div>
View
@@ -8,7 +8,7 @@
<head>
<meta charset="utf-8" />
- <title>Using doctest with Numba &mdash; numba 0.7.2-278-ga8a2104-dirty documentation</title>
+ <title>Using doctest with Numba &mdash; numba 0.7.2-283-gc4ecc2c-dirty documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
@@ -35,7 +35,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '0.7.2-278-ga8a2104-dirty',
+ VERSION: '0.7.2-283-gc4ecc2c-dirty',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
@@ -59,7 +59,7 @@
});
});
</script>
- <link rel="top" title="numba 0.7.2-278-ga8a2104-dirty documentation" href="../index.html" />
+ <link rel="top" title="numba 0.7.2-283-gc4ecc2c-dirty documentation" href="../index.html" />
<link rel="next" title="Examples" href="examples.html" />
<link rel="prev" title="Adding Type Inference for External Code" href="type_inference.html" />
</head>
@@ -72,7 +72,7 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
- <a class="brand" href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a>
+ <a class="brand" href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a>
<div class="nav-collapse collapse">
<ul class="nav pull-right">
@@ -216,7 +216,7 @@ <h3>Quick search</h3>
<li><a href="../py-modindex.html" title="Python Module Index" >modules</a></li>
<li><a href="examples.html" title="Examples" >next</a></li>
<li><a href="type_inference.html" title="Adding Type Inference for External Code" >previous</a></li>
- <li><a href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a></li>
+ <li><a href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a></li>
</ul>
</div>
View
@@ -8,7 +8,7 @@
<head>
<meta charset="utf-8" />
- <title>Examples &mdash; numba 0.7.2-278-ga8a2104-dirty documentation</title>
+ <title>Examples &mdash; numba 0.7.2-283-gc4ecc2c-dirty documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
@@ -35,7 +35,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '0.7.2-278-ga8a2104-dirty',
+ VERSION: '0.7.2-283-gc4ecc2c-dirty',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
@@ -59,7 +59,7 @@
});
});
</script>
- <link rel="top" title="numba 0.7.2-278-ga8a2104-dirty documentation" href="../index.html" />
+ <link rel="top" title="numba 0.7.2-283-gc4ecc2c-dirty documentation" href="../index.html" />
<link rel="next" title="Release Notes" href="releases.html" />
<link rel="prev" title="Using doctest with Numba" href="doctest.html" />
</head>
@@ -72,7 +72,7 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
- <a class="brand" href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a>
+ <a class="brand" href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a>
<div class="nav-collapse collapse">
<ul class="nav pull-right">
@@ -563,7 +563,7 @@ <h2>Filterbank Correlation<a class="headerlink" href="#filterbank-correlation" t
<li><a href="../py-modindex.html" title="Python Module Index" >modules</a></li>
<li><a href="releases.html" title="Release Notes" >next</a></li>
<li><a href="doctest.html" title="Using doctest with Numba" >previous</a></li>
- <li><a href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a></li>
+ <li><a href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a></li>
</ul>
</div>
View
@@ -8,7 +8,7 @@
<head>
<meta charset="utf-8" />
- <title>Interfacing with C &mdash; numba 0.7.2-278-ga8a2104-dirty documentation</title>
+ <title>Interfacing with C &mdash; numba 0.7.2-283-gc4ecc2c-dirty documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
@@ -35,7 +35,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '0.7.2-278-ga8a2104-dirty',
+ VERSION: '0.7.2-283-gc4ecc2c-dirty',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
@@ -59,7 +59,7 @@
});
});
</script>
- <link rel="top" title="numba 0.7.2-278-ga8a2104-dirty documentation" href="../index.html" />
+ <link rel="top" title="numba 0.7.2-283-gc4ecc2c-dirty documentation" href="../index.html" />
<link rel="next" title="Static Compilation (pycc)" href="pycc.html" />
<link rel="prev" title="Arrays" href="arrays.html" />
</head>
@@ -72,7 +72,7 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
- <a class="brand" href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a>
+ <a class="brand" href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a>
<div class="nav-collapse collapse">
<ul class="nav pull-right">
@@ -116,6 +116,7 @@ <h3><a href="../index.html">Table Of Contents</a></h3>
</ul>
</li>
<li><a class="reference internal" href="#using-intrinsics">Using Intrinsics</a></li>
+<li><a class="reference internal" href="#using-numba-functions-in-external-code">Using Numba Functions in External Code</a></li>
<li><a class="reference internal" href="#references">References</a></li>
</ul>
</li>
@@ -166,6 +167,7 @@ <h3><a href="../index.html">Table Of Contents</a></h3>
</ul>
</li>
<li><a class="reference internal" href="#using-intrinsics">Using Intrinsics</a></li>
+<li><a class="reference internal" href="#using-numba-functions-in-external-code">Using Numba Functions in External Code</a></li>
<li><a class="reference internal" href="#references">References</a></li>
</ul>
</li>
@@ -424,6 +426,65 @@ <h2>Using Intrinsics<a class="headerlink" href="#using-intrinsics" title="Permal
the validity can be quickly verified :)</p>
</div>
</div>
+<div class="section" id="using-numba-functions-in-external-code">
+<h2>Using Numba Functions in External Code<a class="headerlink" href="#using-numba-functions-in-external-code" title="Permalink to this headline">¶</a></h2>
+<p>Users can take the address of a numba compiled function using <tt class="docutils literal"><span class="pre">numba.addressof</span></tt>:</p>
+<dl class="function">
+<dt id="addressof">
+<tt class="descname">addressof</tt><big>(</big><em>jit_func</em>, <em>propagate=True</em><big>)</big><a class="headerlink" href="#addressof" title="Permalink to this definition">¶</a></dt>
+<dd><p>Take the address of <tt class="docutils literal"><span class="pre">jit_func</span></tt> as a ctypes function. <tt class="docutils literal"><span class="pre">propagate</span></tt> indicates
+whether uncaught exceptions propogate or are written to stderr.</p>
+</dd></dl>
+
+<div class="highlight-python"><div class="highlight"><pre><span class="nd">@jit</span><span class="p">(</span><span class="n">int32</span><span class="p">(</span><span class="n">int32</span><span class="p">,</span> <span class="n">int32</span><span class="p">))</span>
+<span class="k">def</span> <span class="nf">mul</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
+ <span class="k">return</span> <span class="n">a</span> <span class="o">*</span> <span class="n">b</span>
+
+<span class="n">cmul</span> <span class="o">=</span> <span class="n">numba</span><span class="o">.</span><span class="n">addressof</span><span class="p">(</span><span class="n">mul</span><span class="p">)</span>
+<span class="k">print</span> <span class="n">cmul</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
+
+<span class="c"># Get the address as an Python int</span>
+<span class="n">addr_int</span> <span class="o">=</span> <span class="n">ctypes</span><span class="o">.</span><span class="n">cast</span><span class="p">(</span><span class="n">cmul</span><span class="p">,</span> <span class="n">ctypes</span><span class="o">.</span><span class="n">c_void_p</span><span class="p">)</span><span class="o">.</span><span class="n">value</span>
+<span class="k">print</span> <span class="nb">hex</span><span class="p">(</span><span class="n">addr_int</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Callers can currently check for exceptions (where appropriate) using
+<tt class="docutils literal"><span class="pre">PyErr_Occurred()</span></tt> (which requires the GIL).</p>
+<p><tt class="docutils literal"><span class="pre">nopython</span></tt> functions
+which do not directly or indirectly call functions requiring the GIL or
+use the <tt class="docutils literal"><span class="pre">with</span> <span class="pre">python</span></tt> construct can be called without the GIL. Numba
+does not check whether this is valid, nor does it currently acquire the GIL.</p>
+<p>Currently supported bad values for return types:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="57%" />
+<col width="43%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Return Type</th>
+<th class="head">Bad Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">object_</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">NULL</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">floating</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">NaN</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p>These can be checked as follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">float</span> <span class="n">ret</span> <span class="o">=</span> <span class="n">my_numba_func</span><span class="p">(...);</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">ret</span> <span class="o">!=</span> <span class="n">ret</span> <span class="o">&amp;&amp;</span> <span class="n">PyErr_Occurred</span><span class="p">())</span> <span class="p">{</span>
+ <span class="c1">// Handle error</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The error indicator for integer values is currently undecided, since
+constants in LLVM bitcode are printed in decimal form, but hex codes
+can be a better choice for other scenarios.</p>
+</div>
<div class="section" id="references">
<h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
<table class="docutils footnote" frame="void" id="id4" rules="none">
@@ -467,7 +528,7 @@ <h2>References<a class="headerlink" href="#references" title="Permalink to this
<li><a href="../py-modindex.html" title="Python Module Index" >modules</a></li>
<li><a href="pycc.html" title="Static Compilation (pycc)" >next</a></li>
<li><a href="arrays.html" title="Arrays" >previous</a></li>
- <li><a href="../index.html">numba 0.7.2-278-ga8a2104-dirty documentation</a></li>
+ <li><a href="../index.html">numba 0.7.2-283-gc4ecc2c-dirty documentation</a></li>
</ul>
</div>
Oops, something went wrong.

0 comments on commit 2d644db

Please sign in to comment.