EVOLUTION-MANAGER

Edit File: overview.html

<!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>Overview &mdash; CFFI 1.9.1 documentation</title>
 
 <link rel="stylesheet" href="_static/default.css" type="text/css" />
 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 
 <script type="text/javascript">
 var DOCUMENTATION_OPTIONS = {
 URL_ROOT: '',
 VERSION: '1.9.1',
 COLLAPSE_INDEX: false,
 FILE_SUFFIX: '.html',
 HAS_SOURCE: true
 };
 </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="CFFI 1.9.1 documentation" href="index.html" />
 <link rel="next" title="Using the ffi/lib objects" href="using.html" />
 <link rel="prev" title="Installation and Status" href="installation.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="using.html" title="Using the ffi/lib objects"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="installation.html" title="Installation and Status"
 accesskey="P">previous</a> |</li>
 <li><a href="index.html">CFFI 1.9.1 documentation</a> &raquo;</li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body">
 
 <div class="section" id="overview">
<h1><a class="toc-backref" href="#id10">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h1>
<div class="contents topic" id="contents">
Contents
<ul class="simple">
<li><a class="reference internal" href="#overview" id="id10">Overview</a><ul>
<li><a class="reference internal" href="#simple-example-abi-level-in-line" id="id11">Simple example (ABI level, in-line)</a></li>
<li><a class="reference internal" href="#real-example-api-level-out-of-line" id="id12">Real example (API level, out-of-line)</a></li>
<li><a class="reference internal" href="#struct-array-example-minimal-in-line" id="id13">Struct/Array Example (minimal, in-line)</a></li>
<li><a class="reference internal" href="#purely-for-performance-api-level-out-of-line" id="id14">Purely for performance (API level, out-of-line)</a></li>
<li><a class="reference internal" href="#out-of-line-abi-level" id="id15">Out-of-line, ABI level</a></li>
<li><a class="reference internal" href="#embedding" id="id16">Embedding</a></li>
<li><a class="reference internal" href="#what-actually-happened" id="id17">What actually happened?</a></li>
<li><a class="reference internal" href="#abi-versus-api" id="id18">ABI versus API</a></li>
</ul>
</li>
</ul>
</div>
CFFI can be used in one of four modes: &#8220;ABI&#8221; versus &#8220;API&#8221; level,
each with &#8220;in-line&#8221; or &#8220;out-of-line&#8221; preparation (or compilation).
The ABI mode accesses libraries at the binary level, whereas the
API mode accesses them with a C compiler. This is described in
detail <a class="reference internal" href="#abi-versus-api">below</a>.
In the in-line mode, everything is set up every time you import
your Python code. In the out-of-line mode, you have a separate
step of preparation (and possibly C compilation) that produces a
module which your main program can then import.
(The examples below assume that you have <a class="reference external" href="installation.html">installed CFFI</a>.)
<div class="section" id="simple-example-abi-level-in-line">
<h2><a class="toc-backref" href="#id11">Simple example (ABI level, in-line)</a><a class="headerlink" href="#simple-example-abi-level-in-line" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; from cffi import FFI
&gt;&gt;&gt; ffi = FFI()
&gt;&gt;&gt; ffi.cdef(&quot;&quot;&quot;
... int printf(const char *format, ...); // copy-pasted from the man page
... &quot;&quot;&quot;)
&gt;&gt;&gt; C = ffi.dlopen(None) # loads the entire C namespace
&gt;&gt;&gt; arg = ffi.new(&quot;char[]&quot;, &quot;world&quot;) # equivalent to C code: char arg[] = &quot;world&quot;;
&gt;&gt;&gt; C.printf(&quot;hi there, %s.\n&quot;, arg) # call printf
hi there, world.
17 # this is the return value
&gt;&gt;&gt;
</pre></div>
</div>
Note that on Python 3 you need to pass byte strings to <tt class="docutils literal">char *</tt>
arguments. In the above example it would be <tt class="docutils literal">b&quot;world&quot;</tt> and <tt class="docutils literal">b&quot;hi
there, %s!\n&quot;</tt>. In general it is <tt class="docutils literal">somestring.encode(myencoding)</tt>.
This example does not call any C compiler. It works in the so-called
ABI mode, which means that it will crash if you call some function or
access some fields of a structure that was slightly misdeclared in the
cdef().
If using a C compiler to install your module is an option, it is highly
recommended to use the API mode described in the next paragraph. (It is
also a bit faster at runtime.)
</div>
<div class="section" id="real-example-api-level-out-of-line">
<h2><a class="toc-backref" href="#id12">Real example (API level, out-of-line)</a><a class="headerlink" href="#real-example-api-level-out-of-line" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre># file &quot;example_build.py&quot;

# Note: we instantiate the same &#39;cffi.FFI&#39; class as in the previous
# example, but call the result &#39;ffibuilder&#39; now instead of &#39;ffi&#39;;
# this is to avoid confusion with the other &#39;ffi&#39; object you get below

from cffi import FFI
ffibuilder = FFI()

ffibuilder.set_source(&quot;_example&quot;,
 r&quot;&quot;&quot; // passed to the real C compiler
 #include &lt;sys/types.h&gt;
 #include &lt;pwd.h&gt;
 &quot;&quot;&quot;,
 libraries=[]) # or a list of libraries to link with
 # (more arguments like setup.py&#39;s Extension class:
 # include_dirs=[..], extra_objects=[..], and so on)

ffibuilder.cdef(&quot;&quot;&quot; // some declarations from the man page
 struct passwd {
 char *pw_name;
 ...; // literally dot-dot-dot
 };
 struct passwd *getpwuid(int uid);
&quot;&quot;&quot;)

if __name__ == &quot;__main__&quot;:
 ffibuilder.compile(verbose=True)
</pre></div>
</div>
You need to run the <tt class="docutils literal">example_build.py</tt> script once to generate
&#8220;source code&#8221; into the file <tt class="docutils literal">_example.c</tt> and compile this to a
regular C extension module. (CFFI selects either Python or C for the
module to generate based on whether the second argument to
<tt class="docutils literal">set_source()</tt> is <tt class="docutils literal">None</tt> or not.)
You need a C compiler for this single step. It produces a file called
e.g. _example.so or _example.pyd. If needed, it can be distributed in
precompiled form like any other extension module.
Then, in your main program, you use:
<div class="highlight-python"><div class="highlight"><pre>from _example import ffi, lib

p = lib.getpwuid(0)
assert ffi.string(p.pw_name) == b&#39;root&#39;
</pre></div>
</div>
Note that this works independently of the exact C layout of <tt class="docutils literal">struct
passwd</tt> (it is &#8220;API level&#8221;, as opposed to &#8220;ABI level&#8221;). It requires
a C compiler in order to run <tt class="docutils literal">example_build.py</tt>, but it is much more
portable than trying to get the details of the fields of <tt class="docutils literal">struct
passwd</tt> exactly right. Similarly, we declared <tt class="docutils literal">getpwuid()</tt> as
taking an <tt class="docutils literal">int</tt> argument. On some platforms this might be slightly
incorrect&#8212;but it does not matter.
To integrate it inside a <tt class="docutils literal">setup.py</tt> distribution with Setuptools:
<div class="highlight-python"><div class="highlight"><pre>from setuptools import setup

setup(
 ...
 setup_requires=[&quot;cffi&gt;=1.0.0&quot;],
 cffi_modules=[&quot;example_build.py:ffibuilder&quot;],
 install_requires=[&quot;cffi&gt;=1.0.0&quot;],
)
</pre></div>
</div>
</div>
<div class="section" id="struct-array-example-minimal-in-line">
<h2><a class="toc-backref" href="#id13">Struct/Array Example (minimal, in-line)</a><a class="headerlink" href="#struct-array-example-minimal-in-line" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>from cffi import FFI
ffi = FFI()
ffi.cdef(&quot;&quot;&quot;
 typedef struct {
 unsigned char r, g, b;
 } pixel_t;
&quot;&quot;&quot;)
image = ffi.new(&quot;pixel_t[]&quot;, 800*600)

image[100].r = 255
image[100].g = 192
image[100].b = 128

f = open(&#39;data&#39;, &#39;wb&#39;)
f.write(ffi.buffer(image))
f.close()
</pre></div>
</div>
This can be used as a more flexible replacement of the <a class="reference external" href="http://docs.python.org/library/struct.html">struct</a> and
<a class="reference external" href="http://docs.python.org/library/array.html">array</a> modules. You could also call <tt class="docutils literal">ffi.new(&quot;pixel_t[600][800]&quot;)</tt>
and get a two-dimensional array.
This example does not call any C compiler.
This example also admits an out-of-line equivalent. It is similar to
<a class="reference internal" href="#real-example-api-level-out-of-line">Real example (API level, out-of-line)</a> above, but passing <tt class="docutils literal">None</tt> as
the second argument to <tt class="docutils literal">ffibuilder.set_source()</tt>. Then in the main
program you write <tt class="docutils literal">from _simple_example import ffi</tt> and then the same
content as the in-line example above starting from the line <tt class="docutils literal">image =
ffi.new(&quot;pixel_t[]&quot;, 800*600)</tt>.
</div>
<div class="section" id="purely-for-performance-api-level-out-of-line">
<h2><a class="toc-backref" href="#id14">Purely for performance (API level, out-of-line)</a><a class="headerlink" href="#purely-for-performance-api-level-out-of-line" title="Permalink to this headline">¶</a></h2>
A variant of the <a class="reference internal" href="#real-example">section above</a> where the goal is not to call an
existing C library, but to compile and call some C function written
directly in the build script:
<div class="highlight-python"><div class="highlight"><pre># file &quot;example_build.py&quot;

ffibuilder.cdef(&quot;int foo(int *, int *, int);&quot;)

ffibuilder.set_source(&quot;_example&quot;,
r&quot;&quot;&quot;
 static int foo(int *buffer_in, int *buffer_out, int x)
 {
 /* some algorithm that is seriously faster in C than in Python */
 }
&quot;&quot;&quot;)

from _example import ffi, lib

buffer_in = ffi.new(&quot;int[]&quot;, 1000)
# initialize buffer_in here...

# easier to do all buffer allocations in Python and pass them to C,
# even for output-only arguments
buffer_out = ffi.new(&quot;int[]&quot;, 1000)

result = lib.foo(buffer_in, buffer_out, 1000)
</pre></div>
</div>
You need a C compiler to run example_build.py, once. It produces a
file called e.g. _example.so or _example.pyd. If needed, it can be
distributed in precompiled form like any other extension module.
</div>
<div class="section" id="out-of-line-abi-level">
<h2><a class="toc-backref" href="#id15">Out-of-line, ABI level</a><a class="headerlink" href="#out-of-line-abi-level" title="Permalink to this headline">¶</a></h2>
The out-of-line ABI mode is a mixture of the regular (API) out-of-line
mode and the in-line ABI mode. It lets you use the ABI mode, with its
advantages (not requiring a C compiler) and problems (crashes more
easily).
This mixture mode lets you massively reduces the import times, because
it is slow to parse a large C header. It also allows you to do more
detailed checkings during build-time without worrying about performance
(e.g. calling <tt class="docutils literal">cdef()</tt> many times with small pieces of declarations,
based on the version of libraries detected on the system).
<div class="highlight-python"><div class="highlight"><pre># file &quot;simple_example_build.py&quot;

from cffi import FFI

ffibuilder = FFI()
ffibuilder.set_source(&quot;_simple_example&quot;, None)
ffibuilder.cdef(&quot;&quot;&quot;
 int printf(const char *format, ...);
&quot;&quot;&quot;)

lib = ffi.dlopen(None) # Unix: open the standard C library
#import ctypes.util # or, try this on Windows:
#lib = ffi.dlopen(ctypes.util.find_library(&quot;c&quot;))

lib.printf(b&quot;hi there, number %d\n&quot;, ffi.cast(&quot;int&quot;, 2))
</pre></div>
</div>
Note that this <tt class="docutils literal">ffi.dlopen()</tt>, unlike the one from in-line mode,
does not invoke any additional magic to locate the library: it must be
a path name (with or without a directory), as required by the C
<tt class="docutils literal">dlopen()</tt> or <tt class="docutils literal">LoadLibrary()</tt> functions. This means that
<tt class="docutils literal">ffi.dlopen(&quot;libfoo.so&quot;)</tt> is ok, but <tt class="docutils literal">ffi.dlopen(&quot;foo&quot;)</tt> is not.
In the latter case, you could replace it with
<tt class="docutils literal">ffi.dlopen(ctypes.util.find_library(&quot;foo&quot;))</tt>. Also, None is only
recognized on Unix to open the standard C library.
For distribution purposes, remember that there is a new
<tt class="docutils literal">_simple_example.py</tt> file generated. You can either include it
statically within your project&#8217;s source files, or, with Setuptools,
you can say in the <tt class="docutils literal">setup.py</tt>:
<div class="highlight-python"><div class="highlight"><pre>from setuptools import setup

setup(
 ...
 setup_requires=[&quot;cffi&gt;=1.0.0&quot;],
 cffi_modules=[&quot;simple_example_build.py:ffibuilder&quot;],
 install_requires=[&quot;cffi&gt;=1.0.0&quot;],
)
</pre></div>
</div>
</div>
<div class="section" id="embedding">
<h2><a class="toc-backref" href="#id16">Embedding</a><a class="headerlink" href="#embedding" title="Permalink to this headline">¶</a></h2>
New in version 1.5.
CFFI can be used for <a class="reference external" href="embedding.html">embedding</a>: creating a standard
dynamically-linked library (<tt class="docutils literal">.dll</tt> under Windows, <tt class="docutils literal">.so</tt> elsewhere)
which can be used from a C application.
<div class="highlight-python"><div class="highlight"><pre>import cffi
ffibuilder = cffi.FFI()

ffibuilder.embedding_api(&quot;&quot;&quot;
 int do_stuff(int, int);
&quot;&quot;&quot;)

ffibuilder.set_source(&quot;my_plugin&quot;, &quot;&quot;)

ffibuilder.embedding_init_code(&quot;&quot;&quot;
 from my_plugin import ffi

@ffi.def_extern()
 def do_stuff(x, y):
 print(&quot;adding %d and %d&quot; % (x, y))
 return x + y
&quot;&quot;&quot;)

ffibuilder.compile(target=&quot;plugin-1.5.*&quot;, verbose=True)
</pre></div>
</div>
This simple example creates <tt class="docutils literal">plugin-1.5.dll</tt> or <tt class="docutils literal">plugin-1.5.so</tt> as
a DLL with a single exported function, <tt class="docutils literal">do_stuff()</tt>. You execute
the script above once, with the interpreter you want to have
internally used; it can be CPython 2.x or 3.x or PyPy. This DLL can
then be used &#8220;as usual&#8221; from an application; the application doesn&#8217;t
need to know that it is talking with a library made with Python and
CFFI. At runtime, when the application calls <tt class="docutils literal">int do_stuff(int,
int)</tt>, the Python interpreter is automatically initialized and <tt class="docutils literal">def
do_stuff(x, y):</tt> gets called. <a class="reference external" href="embedding.html">See the details in the documentation
about embedding.</a>
</div>
<div class="section" id="what-actually-happened">
<h2><a class="toc-backref" href="#id17">What actually happened?</a><a class="headerlink" href="#what-actually-happened" title="Permalink to this headline">¶</a></h2>
The CFFI interface operates on the same level as C - you declare types
and functions using the same syntax as you would define them in C. This
means that most of the documentation or examples can be copied straight
from the man pages.
The declarations can contain types, functions, constants
and global variables. What you pass to the <tt class="docutils literal">cdef()</tt> must not
contain more than that; in particular, <tt class="docutils literal">#ifdef</tt> or <tt class="docutils literal">#include</tt>
directives are not supported. The cdef in the above examples are just
that - they declared &#8220;there is a function in the C level with this
given signature&#8221;, or &#8220;there is a struct type with this shape&#8221;.
In the ABI examples, the <tt class="docutils literal">dlopen()</tt> calls load libraries manually.
At the binary level, a program is split into multiple namespaces&#8212;a
global one (on some platforms), plus one namespace per library. So
<tt class="docutils literal">dlopen()</tt> returns a <tt class="docutils literal">&lt;FFILibrary&gt;</tt> object, and this object has
got as attributes all function, constant and variable symbols that are
coming from this library and that have been declared in the
<tt class="docutils literal">cdef()</tt>. If you have several interdependent libraries to load,
you would call <tt class="docutils literal">cdef()</tt> only once but <tt class="docutils literal">dlopen()</tt> several times.
By opposition, the API mode works more closely like a C program: the C
linker (static or dynamic) is responsible for finding any symbol used.
You name the libraries in the <tt class="docutils literal">libraries</tt> keyword argument to
<tt class="docutils literal">set_source()</tt>, but never need to say which symbol comes
from which library.
Other common arguments to <tt class="docutils literal">set_source()</tt> include <tt class="docutils literal">library_dirs</tt> and
<tt class="docutils literal">include_dirs</tt>; all these arguments are passed to the standard
distutils/setuptools.
The <tt class="docutils literal">ffi.new()</tt> lines allocate C objects. They are filled
with zeroes initially, unless the optional second argument is used.
If specified, this argument gives an &#8220;initializer&#8221;, like you can use
with C code to initialize global variables.
The actual <tt class="docutils literal">lib.*()</tt> function calls should be obvious: it&#8217;s like C.
</div>
<div class="section" id="abi-versus-api">
<h2><a class="toc-backref" href="#id18">ABI versus API</a><a class="headerlink" href="#abi-versus-api" title="Permalink to this headline">¶</a></h2>
Accessing the C library at the binary level (&#8220;ABI&#8221;) is fraught
with problems, particularly on non-Windows platforms. You are not
meant to access fields by guessing where they are in the structures.
The C libraries are typically meant to be used with a C compiler.
The &#8220;real example&#8221; above shows how to do that: this example uses
<tt class="docutils literal">set_source(..., &quot;C source...&quot;)</tt> and never <tt class="docutils literal">dlopen()</tt>.
When using this approach,
we have the advantage that we can use literally &#8220;<tt class="docutils literal">...</tt>&#8221; at various places in
the <tt class="docutils literal">cdef()</tt>, and the missing information will be completed with the
help of the C compiler. Actually, a single C source file is produced,
which contains first the &#8220;C source&#8221; part unmodified, followed by some
&#8220;magic&#8221; C code and declarations derived from the <tt class="docutils literal">cdef()</tt>. When
this C file is compiled, the resulting C extension module will contain
all the information we need&#8212;or the C compiler will give warnings or
errors, as usual e.g. if we misdeclare some function&#8217;s signature.
Note that the &#8220;C source&#8221; part from <tt class="docutils literal">set_source()</tt> can contain
arbitrary C code. You can use this to declare some
more helper functions written in C. To export
these helpers to Python, put their signature in the <tt class="docutils literal">cdef()</tt> too.
(You can use the <tt class="docutils literal">static</tt> C keyword in the &#8220;C source&#8221; part,
as in <tt class="docutils literal">static int myhelper(int x) { return x * 42; }</tt>,
because these helpers are only
referenced from the &#8220;magic&#8221; C code that is generated afterwards in the
same C file.)
This can be used for example to wrap &#8220;crazy&#8221; macros into more standard
C functions. The extra layer of C can be useful for other reasons
too, like calling functions that expect some complicated argument
structures that you prefer to build in C rather than in Python. (On
the other hand, if all you need is to call &#8220;function-like&#8221; macros,
then you can directly declare them in the <tt class="docutils literal">cdef()</tt> as if they were
functions.)
The generated piece of C code should be the same independently on the
platform on which you run it (or the Python version), so in simple cases
you can directly distribute the pre-generated C code and treat it as a
regular C extension module (which depends on the <tt class="docutils literal">_cffi_backend</tt>
module, on CPython). The special Setuptools lines in the <a class="reference internal" href="#real-example">example
above</a> are meant for the more complicated cases where we need to
regenerate the C sources as well&#8212;e.g. because the Python script that
regenerates this file will itself look around the system to know what it
should include or not.
Note that the &#8220;API level + in-line&#8221; mode combination exists but is long
deprecated. It used to be done with <tt class="docutils literal">lib = ffi.verify(&quot;C header&quot;)</tt>.
The out-of-line variant with <tt class="docutils literal">set_source(&quot;modname&quot;, &quot;C header&quot;)</tt> is
preferred.
</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="#">Overview</a><ul>
<li><a class="reference internal" href="#simple-example-abi-level-in-line">Simple example (ABI level, in-line)</a></li>
<li><a class="reference internal" href="#real-example-api-level-out-of-line">Real example (API level, out-of-line)</a></li>
<li><a class="reference internal" href="#struct-array-example-minimal-in-line">Struct/Array Example (minimal, in-line)</a></li>
<li><a class="reference internal" href="#purely-for-performance-api-level-out-of-line">Purely for performance (API level, out-of-line)</a></li>
<li><a class="reference internal" href="#out-of-line-abi-level">Out-of-line, ABI level</a></li>
<li><a class="reference internal" href="#embedding">Embedding</a></li>
<li><a class="reference internal" href="#what-actually-happened">What actually happened?</a></li>
<li><a class="reference internal" href="#abi-versus-api">ABI versus API</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="installation.html"
 title="previous chapter">Installation and Status</a>
 <h4>Next topic</h4>
 <a href="using.html"
 title="next chapter">Using the ffi/lib objects</a>
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="_sources/overview.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
<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>
 
 Enter search terms or a module, class or function name.
 
</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="using.html" title="Using the ffi/lib objects"
 >next</a> |</li>
 <li class="right" >
 <a href="installation.html" title="Installation and Status"
 >previous</a> |</li>
 <li><a href="index.html">CFFI 1.9.1 documentation</a> &raquo;</li> 
 </ul>
 </div>
 <div class="footer">
 &copy; Copyright 2012-2015, Armin Rigo, Maciej Fijalkowski.
 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
 </div>
 </body>
</html>