EVOLUTION-MANAGER

Edit File: embedding.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>Using CFFI for embedding &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="prev" title="Preparing and Distributing modules" href="cdef.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="cdef.html" title="Preparing and Distributing modules"
 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="using-cffi-for-embedding">
<h1><a class="toc-backref" href="#id7">Using CFFI for embedding</a><a class="headerlink" href="#using-cffi-for-embedding" title="Permalink to this headline">¶</a></h1>
<div class="contents topic" id="contents">
Contents
<ul class="simple">
<li><a class="reference internal" href="#using-cffi-for-embedding" id="id7">Using CFFI for embedding</a><ul>
<li><a class="reference internal" href="#usage" id="id8">Usage</a></li>
<li><a class="reference internal" href="#more-reading" id="id9">More reading</a></li>
<li><a class="reference internal" href="#troubleshooting" id="id10">Troubleshooting</a></li>
<li><a class="reference internal" href="#issues-about-using-the-so" id="id11">Issues about using the .so</a></li>
<li><a class="reference internal" href="#using-multiple-cffi-made-dlls" id="id12">Using multiple CFFI-made DLLs</a></li>
<li><a class="reference internal" href="#multithreading" id="id13">Multithreading</a></li>
<li><a class="reference internal" href="#testing" id="id14">Testing</a></li>
<li><a class="reference internal" href="#embedding-and-extending" id="id15">Embedding and Extending</a></li>
</ul>
</li>
</ul>
</div>
You can use CFFI to generate a <tt class="docutils literal">.so/.dll/.dylib</tt> which exports the
API of your choice to any C application that wants to link with this
<tt class="docutils literal">.so/.dll/.dylib</tt>.
The general idea is as follows:
<ul class="simple">
<li>You write and execute a Python script, which produces a
<tt class="docutils literal">.so/.dll/.dylib</tt> file with the API of your choice. The script
also gives some Python code to be &#8220;frozen&#8221; inside the <tt class="docutils literal">.so</tt>.</li>
<li>At runtime, the C application loads this <tt class="docutils literal">.so/.dll/.dylib</tt> without
having to know that it was produced by Python and CFFI.</li>
<li>The first time a C function is called, Python is initialized and
the frozen Python code is executed.</li>
<li>The frozen Python code attaches Python functions that implement the
C functions of your API, which are then used for all subsequent C
function calls.</li>
</ul>
One of the goals of this approach is to be entirely independent from
the CPython C API: no <tt class="docutils literal">Py_Initialize()</tt> nor <tt class="docutils literal">PyRun_SimpleString()</tt>
nor even <tt class="docutils literal">PyObject</tt>. It works identically on CPython and PyPy.
This is entirely new in version 1.5. (PyPy contains CFFI 1.5 since
release 5.0.)
<div class="section" id="usage">
<h2><a class="toc-backref" href="#id8">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
See the <a class="reference external" href="overview.html#embedding">paragraph in the overview page</a> for a quick introduction.
In this section, we explain every step in more details. We will use
here this slightly expanded example:
<div class="highlight-c"><div class="highlight"><pre>/* file plugin.h */
typedef struct { int x, y; } point_t;
extern int do_stuff(point_t *);
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre># file plugin_build.py
import cffi
ffibuilder = cffi.FFI()

with open(&#39;plugin.h&#39;) as f:
 ffibuilder.embedding_api(f.read())

ffibuilder.set_source(&quot;my_plugin&quot;, r&#39;&#39;&#39;
 #include &quot;plugin.h&quot;
&#39;&#39;&#39;)

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

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

ffibuilder.compile(target=&quot;plugin-1.5.*&quot;, verbose=True)
</pre></div>
</div>
Running the code above produces a DLL, i,e, a dynamically-loadable
library. It is a file with the extension <tt class="docutils literal">.dll</tt> on Windows,
<tt class="docutils literal">.dylib</tt> on Mac OS/X, or <tt class="docutils literal">.so</tt> on other platforms. As usual, it
is produced by generating some intermediate <tt class="docutils literal">.c</tt> code and then
calling the regular platform-specific C compiler. See <a class="reference internal" href="#issues-about-using-the-so">below</a> for
some pointers to C-level issues with using the produced library.
Here are some details about the methods used above:
<ul>
<li>ffibuilder.embedding_api(source): parses the given C source, which
declares functions that you want to be exported by the DLL. It can
also declare types, constants and global variables that are part of
the C-level API of your DLL.
The functions that are found in <tt class="docutils literal">source</tt> will be automatically
defined in the <tt class="docutils literal">.c</tt> file: they will contain code that initializes
the Python interpreter the first time any of them is called,
followed by code to call the attached Python function (with
<tt class="docutils literal">&#64;ffi.def_extern()</tt>, see next point).
The global variables, on the other hand, are not automatically
produced. You have to write their definition explicitly in
<tt class="docutils literal">ffibuilder.set_source()</tt>, as regular C code (see the point after next).
</li>
<li>ffibuilder.embedding_init_code(python_code): this gives
initialization-time Python source code. This code is copied
(&#8220;frozen&#8221;) inside the DLL. At runtime, the code is executed when
the DLL is first initialized, just after Python itself is
initialized. This newly initialized Python interpreter has got an
extra &#8220;built-in&#8221; module that can be loaded magically without
accessing any files, with a line like &#8220;<tt class="docutils literal">from my_plugin import ffi,
lib</tt>&#8221;. The name <tt class="docutils literal">my_plugin</tt> comes from the first argument to
<tt class="docutils literal">ffibuilder.set_source()</tt>. This module represents &#8220;the caller&#8217;s C world&#8221;
from the point of view of Python.
The initialization-time Python code can import other modules or
packages as usual. You may have typical Python issues like needing
to set up <tt class="docutils literal">sys.path</tt> somehow manually first.
For every function declared within <tt class="docutils literal">ffibuilder.embedding_api()</tt>, the
initialization-time Python code or one of the modules it imports
should use the decorator <tt class="docutils literal">&#64;ffi.def_extern()</tt> to attach a
corresponding Python function to it.
If the initialization-time Python code fails with an exception, then
you get a traceback printed to stderr, along with more information
to help you identify problems like wrong <tt class="docutils literal">sys.path</tt>. If some
function remains unattached at the time where the C code tries to
call it, an error message is also printed to stderr and the function
returns zero/null.
Note that the CFFI module never calls <tt class="docutils literal">exit()</tt>, but CPython itself
contains code that calls <tt class="docutils literal">exit()</tt>, for example if importing
<tt class="docutils literal">site</tt> fails. This may be worked around in the future.
</li>
<li>ffibuilder.set_source(c_module_name, c_code): set the name of the
module from Python&#8217;s point of view. It also gives more C code which
will be included in the generated C code. In trivial examples it
can be an empty string. It is where you would <tt class="docutils literal">#include</tt> some
other files, define global variables, and so on. The macro
<tt class="docutils literal">CFFI_DLLEXPORT</tt> is available to this C code: it expands to the
platform-specific way of saying &#8220;the following declaration should be
exported from the DLL&#8221;. For example, you would put &#8220;<tt class="docutils literal">extern int
my_glob;</tt>&#8221; in <tt class="docutils literal">ffibuilder.embedding_api()</tt> and &#8220;<tt class="docutils literal">CFFI_DLLEXPORT int
my_glob = 42;</tt>&#8221; in <tt class="docutils literal">ffibuilder.set_source()</tt>.
Currently, any type declared in <tt class="docutils literal">ffibuilder.embedding_api()</tt> must also
be present in the <tt class="docutils literal">c_code</tt>. This is automatic if this code
contains a line like <tt class="docutils literal">#include &quot;plugin.h&quot;</tt> in the example above.
</li>
<li>ffibuilder.compile([target=...] [, verbose=True]): make the C code and
compile it. By default, it produces a file called
<tt class="docutils literal">c_module_name.dll</tt>, <tt class="docutils literal">c_module_name.dylib</tt> or
<tt class="docutils literal">c_module_name.so</tt>, but the default can be changed with the
optional <tt class="docutils literal">target</tt> keyword argument. You can use
<tt class="docutils literal">target=&quot;foo.*&quot;</tt> with a literal <tt class="docutils literal">*</tt> to ask for a file called
<tt class="docutils literal">foo.dll</tt> on Windows, <tt class="docutils literal">foo.dylib</tt> on OS/X and <tt class="docutils literal">foo.so</tt>
elsewhere. One reason for specifying an alternate <tt class="docutils literal">target</tt> is to
include characters not usually allowed in Python module names, like
&#8220;<tt class="docutils literal">plugin-1.5.*</tt>&#8221;.
For more complicated cases, you can call instead
<tt class="docutils literal">ffibuilder.emit_c_code(&quot;foo.c&quot;)</tt> and compile the resulting <tt class="docutils literal">foo.c</tt>
file using other means. CFFI&#8217;s compilation logic is based on the
standard library <tt class="docutils literal">distutils</tt> package, which is really developed
and tested for the purpose of making CPython extension modules, not
other DLLs.
</li>
</ul>
</div>
<div class="section" id="more-reading">
<h2><a class="toc-backref" href="#id9">More reading</a><a class="headerlink" href="#more-reading" title="Permalink to this headline">¶</a></h2>
If you&#8217;re reading this page about embedding and you are not familiar
with CFFI already, here are a few pointers to what you could read
next:
<ul>
<li>For the <tt class="docutils literal">&#64;ffi.def_extern()</tt> functions, integer C types are passed
simply as Python integers; and simple pointers-to-struct and basic
arrays are all straightforward enough. However, sooner or later you
will need to read about this topic in more details <a class="reference external" href="using.html#working">here</a>.
</li>
<li><tt class="docutils literal">&#64;ffi.def_extern()</tt>: see <a class="reference external" href="using.html#def-extern">documentation here,</a> notably on what
happens if the Python function raises an exception.
</li>
<li>To create Python objects attached to C data, one common solution is
to use <tt class="docutils literal">ffi.new_handle()</tt>. See documentation <a class="reference external" href="ref.html#ffi-new-handle">here</a>.
</li>
<li>In embedding mode, the major direction is C code that calls Python
functions. This is the opposite of the regular extending mode of
CFFI, in which the major direction is Python code calling C. That&#8217;s
why the page <a class="reference external" href="using.html">Using the ffi/lib objects</a> talks first about the
latter, and why the direction &#8220;C code that calls Python&#8221; is
generally referred to as &#8220;callbacks&#8221; in that page. If you also
need to have your Python code call C code, read more about
<a class="reference internal" href="#embedding-and-extending">Embedding and Extending</a> below.
</li>
<li><tt class="docutils literal">ffibuilder.embedding_api(source)</tt>: follows the same syntax as
<tt class="docutils literal">ffibuilder.cdef()</tt>, <a class="reference external" href="cdef.html#cdef">documented here.</a> You can use the &#8220;<tt class="docutils literal">...</tt>&#8221;
syntax as well, although in practice it may be less useful than it
is for <tt class="docutils literal">cdef()</tt>. On the other hand, it is expected that often the
C sources that you need to give to <tt class="docutils literal">ffibuilder.embedding_api()</tt> would be
exactly the same as the content of some <tt class="docutils literal">.h</tt> file that you want to
give to users of your DLL. That&#8217;s why the example above does this:
<div class="highlight-python"><div class="highlight"><pre>with open(&#39;foo.h&#39;) as f:
 ffibuilder.embedding_api(f.read())
</pre></div>
</div>
Note that a drawback of this approach is that <tt class="docutils literal">ffibuilder.embedding_api()</tt>
doesn&#8217;t support <tt class="docutils literal">#ifdef</tt> directives. You may have to use a more
convoluted expression like:
<div class="highlight-python"><div class="highlight"><pre>with open(&#39;foo.h&#39;) as f:
 lines = [line for line in f if not line.startswith(&#39;#&#39;)]
 ffibuilder.embedding_api(&#39;&#39;.join(lines))
</pre></div>
</div>
As in the example above, you can also use the same <tt class="docutils literal">foo.h</tt> from
<tt class="docutils literal">ffibuilder.set_source()</tt>:
<div class="highlight-python"><div class="highlight"><pre>ffibuilder.set_source(&#39;module_name&#39;, r&#39;&#39;&#39;
 #include &quot;foo.h&quot;
&#39;&#39;&#39;)
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="troubleshooting">
<h2><a class="toc-backref" href="#id10">Troubleshooting</a><a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2>
The error message
<blockquote>
<div>cffi extension module &#8216;c_module_name&#8217; has unknown version 0x2701</div></blockquote>
means that the running Python interpreter located a CFFI version older
than 1.5. CFFI 1.5 or newer must be installed in the running Python.
</div>
<div class="section" id="issues-about-using-the-so">
<h2><a class="toc-backref" href="#id11">Issues about using the .so</a><a class="headerlink" href="#issues-about-using-the-so" title="Permalink to this headline">¶</a></h2>
This paragraph describes issues that are not necessarily specific to
CFFI. It assumes that you have obtained the <tt class="docutils literal">.so/.dylib/.dll</tt> file as
described above, but that you have troubles using it. (In summary: it
is a mess. This is my own experience, slowly built by using Google and
by listening to reports from various platforms. Please report any
inaccuracies in this paragraph or better ways to do things.)
<ul>
<li>The file produced by CFFI should follow this naming pattern:
<tt class="docutils literal">libmy_plugin.so</tt> on Linux, <tt class="docutils literal">libmy_plugin.dylib</tt> on Mac, or
<tt class="docutils literal">my_plugin.dll</tt> on Windows (no <tt class="docutils literal">lib</tt> prefix on Windows).
</li>
<li>First note that this file does not contain the Python interpreter
nor the standard library of Python. You still need it to be
somewhere. There are ways to compact it to a smaller number of files,
but this is outside the scope of CFFI (please report if you used some
of these ways successfully so that I can add some links here).
</li>
<li>In what we&#8217;ll call the &#8220;main program&#8221;, the <tt class="docutils literal">.so</tt> can be either
used dynamically (e.g. by calling <tt class="docutils literal">dlopen()</tt> or <tt class="docutils literal">LoadLibrary()</tt>
inside the main program), or at compile-time (e.g. by compiling it
with <tt class="docutils literal">gcc -lmy_plugin</tt>). The former case is always used if you&#8217;re
building a plugin for a program, and the program itself doesn&#8217;t need
to be recompiled. The latter case is for making a CFFI library that
is more tightly integrated inside the main program.
</li>
<li>In the case of compile-time usage: you can add the gcc
option <tt class="docutils literal">-Lsome/path/</tt> before <tt class="docutils literal">-lmy_plugin</tt> to describe where the
<tt class="docutils literal">libmy_plugin.so</tt> is. On some platforms, notably Linux, <tt class="docutils literal">gcc</tt>
will complain if it can find <tt class="docutils literal">libmy_plugin.so</tt> but not
<tt class="docutils literal">libpython27.so</tt> or <tt class="docutils literal">libpypy-c.so</tt>. To fix it, you need to call
<tt class="docutils literal">LD_LIBRARY_PATH=/some/path/to/libpypy gcc</tt>.
</li>
<li>When actually executing the main program, it needs to find the
<tt class="docutils literal">libmy_plugin.so</tt> but also <tt class="docutils literal">libpython27.so</tt> or <tt class="docutils literal">libpypy-c.so</tt>.
For PyPy, unpack a PyPy distribution and you get a full directory
structure with <tt class="docutils literal">libpypy-c.so</tt> inside a <tt class="docutils literal">bin</tt> subdirectory, or on
Windows <tt class="docutils literal">pypy-c.dll</tt> inside the top directory; you must not move
this file around, but just point to it. One way to point to it is by
running the main program with some environment variable:
<tt class="docutils literal">LD_LIBRARY_PATH=/some/path/to/libpypy</tt> on Linux,
<tt class="docutils literal">DYLD_LIBRARY_PATH=/some/path/to/libpypy</tt> on OS/X.
</li>
<li>You can avoid the <tt class="docutils literal">LD_LIBRARY_PATH</tt> issue if you compile
<tt class="docutils literal">libmy_plugin.so</tt> with the path hard-coded inside in the first
place. On Linux, this is done by <tt class="docutils literal">gcc -Wl,-rpath=/some/path</tt>. You
would put this option in <tt class="docutils literal">ffibuilder.set_source(&quot;my_plugin&quot;, ...,
extra_link_args=['-Wl,-rpath=/some/path/to/libpypy'])</tt>. The path can
start with <tt class="docutils literal">$ORIGIN</tt> to mean &#8220;the directory where
<tt class="docutils literal">libmy_plugin.so</tt> is&#8221;. You can then specify a path relative to that
place, like <tt class="docutils literal">extra_link_args=['-Wl,-rpath=$ORIGIN/../venv/bin']</tt>.
Use <tt class="docutils literal">ldd libmy_plugin.so</tt> to look at what path is currently compiled
in after the expansion of <tt class="docutils literal">$ORIGIN</tt>.)
After this, you don&#8217;t need <tt class="docutils literal">LD_LIBRARY_PATH</tt> any more to locate
<tt class="docutils literal">libpython27.so</tt> or <tt class="docutils literal">libpypy-c.so</tt> at runtime. In theory it
should also cover the call to <tt class="docutils literal">gcc</tt> for the main program. I wasn&#8217;t
able to make <tt class="docutils literal">gcc</tt> happy without <tt class="docutils literal">LD_LIBRARY_PATH</tt> on Linux if
the rpath starts with <tt class="docutils literal">$ORIGIN</tt>, though.
</li>
<li>The same rpath trick might be used to let the main program find
<tt class="docutils literal">libmy_plugin.so</tt> in the first place without <tt class="docutils literal">LD_LIBRARY_PATH</tt>.
(This doesn&#8217;t apply if the main program uses <tt class="docutils literal">dlopen()</tt> to load it
as a dynamic plugin.) You&#8217;d make the main program with <tt class="docutils literal">gcc
-Wl,-rpath=/path/to/libmyplugin</tt>, possibly with <tt class="docutils literal">$ORIGIN</tt>. The
<tt class="docutils literal">$</tt> in <tt class="docutils literal">$ORIGIN</tt> causes various shell problems on its own: if
using a common shell you need to say <tt class="docutils literal">gcc
-Wl,-rpath=\$ORIGIN</tt>. From a Makefile, you need to say
something like <tt class="docutils literal">gcc -Wl,-rpath=\$$ORIGIN</tt>.
</li>
</ul>
</div>
<div class="section" id="using-multiple-cffi-made-dlls">
<h2><a class="toc-backref" href="#id12">Using multiple CFFI-made DLLs</a><a class="headerlink" href="#using-multiple-cffi-made-dlls" title="Permalink to this headline">¶</a></h2>
Multiple CFFI-made DLLs can be used by the same process.
Note that all CFFI-made DLLs in a process share a single Python
interpreter. The effect is the same as the one you get by trying to
build a large Python application by assembling a lot of unrelated
packages. Some of these might be libraries that monkey-patch some
functions from the standard library, for example, which might be
unexpected from other parts.
</div>
<div class="section" id="multithreading">
<h2><a class="toc-backref" href="#id13">Multithreading</a><a class="headerlink" href="#multithreading" title="Permalink to this headline">¶</a></h2>
Multithreading should work transparently, based on Python&#8217;s standard
Global Interpreter Lock.
If two threads both try to call a C function when Python is not yet
initialized, then locking occurs. One thread proceeds with
initialization and blocks the other thread. The other thread will be
allowed to continue only when the execution of the initialization-time
Python code is done.
If the two threads call two different CFFI-made DLLs, the Python
initialization itself will still be serialized, but the two pieces of
initialization-time Python code will not. The idea is that there is a
priori no reason for one DLL to wait for initialization of the other
DLL to be complete.
After initialization, Python&#8217;s standard Global Interpreter Lock kicks
in. The end result is that when one CPU progresses on executing
Python code, no other CPU can progress on executing more Python code
from another thread of the same process. At regular intervals, the
lock switches to a different thread, so that no single thread should
appear to block indefinitely.
</div>
<div class="section" id="testing">
<h2><a class="toc-backref" href="#id14">Testing</a><a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2>
For testing purposes, a CFFI-made DLL can be imported in a running
Python interpreter instead of being loaded like a C shared library.
You might have some issues with the file name: for example, on
Windows, Python expects the file to be called <tt class="docutils literal">c_module_name.pyd</tt>,
but the CFFI-made DLL is called <tt class="docutils literal">target.dll</tt> instead. The base name
<tt class="docutils literal">target</tt> is the one specified in <tt class="docutils literal">ffibuilder.compile()</tt>, and on Windows
the extension is <tt class="docutils literal">.dll</tt> instead of <tt class="docutils literal">.pyd</tt>. You have to rename or
copy the file, or on POSIX use a symlink.
The module then works like a regular CFFI extension module. It is
imported with &#8220;<tt class="docutils literal">from c_module_name import ffi, lib</tt>&#8221; and exposes on
the <tt class="docutils literal">lib</tt> object all C functions. You can test it by calling these
C functions. The initialization-time Python code frozen inside the
DLL is executed the first time such a call is done.
</div>
<div class="section" id="embedding-and-extending">
<h2><a class="toc-backref" href="#id15">Embedding and Extending</a><a class="headerlink" href="#embedding-and-extending" title="Permalink to this headline">¶</a></h2>
The embedding mode is not incompatible with the non-embedding mode of
CFFI.
You can use both <tt class="docutils literal">ffibuilder.embedding_api()</tt> and
<tt class="docutils literal">ffibuilder.cdef()</tt> in the
same build script. You put in the former the declarations you want to
be exported by the DLL; you put in the latter only the C functions and
types that you want to share between C and Python, but not export from
the DLL.
As an example of that, consider the case where you would like to have
a DLL-exported C function written in C directly, maybe to handle some
cases before calling Python functions. To do that, you must not put
the function&#8217;s signature in <tt class="docutils literal">ffibuilder.embedding_api()</tt>. (Note that this
requires more hacks if you use <tt class="docutils literal">ffibuilder.embedding_api(f.read())</tt>.)
You must only write the custom function definition in
<tt class="docutils literal">ffibuilder.set_source()</tt>, and prefix it with the macro CFFI_DLLEXPORT:
<div class="highlight-c"><div class="highlight"><pre>CFFI_DLLEXPORT int myfunc(int a, int b)
{
 /* implementation here */
}
</pre></div>
</div>
This function can, if it wants, invoke Python functions using the
general mechanism of &#8220;callbacks&#8221;&#8212;called this way because it is a
call from C to Python, although in this case it is not calling
anything back:
<div class="highlight-python"><div class="highlight"><pre>ffibuilder.cdef(&quot;&quot;&quot;
 extern &quot;Python&quot; int mycb(int);
&quot;&quot;&quot;)

static int mycb(int); /* the callback: forward declaration, to make
 it accessible from the C code that follows */

CFFI_DLLEXPORT int myfunc(int a, int b)
 {
 int product = a * b; /* some custom C code */
 return mycb(product);
 }
&quot;&quot;&quot;)
</pre></div>
</div>
and then the Python initialization code needs to contain the lines:
<div class="highlight-python"><div class="highlight"><pre>@ffi.def_extern()
def mycb(x):
 print &quot;hi, I&#39;m called with x =&quot;, x
 return x * 10
</pre></div>
</div>
This <tt class="docutils literal">&#64;ffi.def_extern</tt> is attaching a Python function to the C
callback <tt class="docutils literal">mycb()</tt>, which in this case is not exported from the DLL.
Nevertheless, the automatic initialization of Python occurs when
<tt class="docutils literal">mycb()</tt> is called, if it happens to be the first function called
from C. More precisely, it does not happen when <tt class="docutils literal">myfunc()</tt> is
called: this is just a C function, with no extra code magically
inserted around it. It only happens when <tt class="docutils literal">myfunc()</tt> calls
<tt class="docutils literal">mycb()</tt>.
As the above explanation hints, this is how <tt class="docutils literal">ffibuilder.embedding_api()</tt>
actually implements function calls that directly invoke Python code;
here, we have merely decomposed it explicitly, in order to add some
custom C code in the middle.
In case you need to force, from C code, Python to be initialized
before the first <tt class="docutils literal">&#64;ffi.def_extern()</tt> is called, you can do so by
calling the C function <tt class="docutils literal">cffi_start_python()</tt> with no argument. It
returns an integer, 0 or -1, to tell if the initialization succeeded
or not. Currently there is no way to prevent a failing initialization
from also dumping a traceback and more information to stderr.
</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="#">Using CFFI for embedding</a><ul>
<li><a class="reference internal" href="#usage">Usage</a></li>
<li><a class="reference internal" href="#more-reading">More reading</a></li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a></li>
<li><a class="reference internal" href="#issues-about-using-the-so">Issues about using the .so</a></li>
<li><a class="reference internal" href="#using-multiple-cffi-made-dlls">Using multiple CFFI-made DLLs</a></li>
<li><a class="reference internal" href="#multithreading">Multithreading</a></li>
<li><a class="reference internal" href="#testing">Testing</a></li>
<li><a class="reference internal" href="#embedding-and-extending">Embedding and Extending</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="cdef.html"
 title="previous chapter">Preparing and Distributing modules</a>
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="_sources/embedding.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="cdef.html" title="Preparing and Distributing modules"
 >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>