• 目标
• 注释和 Bug
• 新功能
• 安装和状态
• 概述
  • 主要使用模式
  • 其它 CFFI 模式
    • Simple example (ABI level, in-line)
    • Struct/Array Example (minimal, in-line)
    • API Mode, calling the C standard library
    • API Mode, calling C sources instead of a compiled library
    • Purely for performance (API level, out-of-line)
    • Out-of-line, ABI level
    • In-line, API level
  • 嵌入
  • 实际发生了什么？
  • ABI (应用程序二进制接口) vs API (应用程序接口)
• 使用 ffi/lib 对象
• CFFI 参考
• 准备和分发模块
• 使用 CFFI 进行嵌入

1. 首页
2. CFFI 1.15.1
3. 概述

概述 ¶

内容

• 概述
  • 主要使用模式
  • 其它 CFFI 模式
    • Simple example (ABI level, in-line)
    • Struct/Array Example (minimal, in-line)
    • API Mode, calling the C standard library
    • API Mode, calling C sources instead of a compiled library
    • Purely for performance (API level, out-of-line)
    • Out-of-line, ABI level
    • In-line, API level
  • 嵌入
  • 实际发生了什么？
  • ABI (应用程序二进制接口) vs API (应用程序接口)

The first section presents a simple working example of using CFFI to call a C function in a compiled shared object (DLL) from Python. CFFI is flexible and covers several other use cases presented in the second section. The third section shows how to export Python functions to a Python interpreter embedded in a C or C++ application. The last two sections delve deeper in the CFFI library.

Make sure you have cffi installed .

You can find these and some other complete demos in the demo directory of the repository .

主要使用模式 ¶

The main way to use CFFI is as an interface to some already-compiled shared object which is provided by other means. Imagine that you have a system-installed shared object called piapprox.dll (Windows) or libpiapprox.so (Linux and others) or libpiapprox.dylib (OS X), exporting a function float pi_approx(int n); that computes some approximation of pi given a number of iterations. You want to call this function from Python. Note this method works equally well with a static library piapprox.lib (Windows) or libpiapprox.a .

创建文件 piapprox_build.py :

from cffi import FFI
ffibuilder = FFI()
# cdef() expects a single string declaring the C types, functions and
# globals needed to use the shared object. It must be in valid C syntax.
ffibuilder.cdef("""
    float pi_approx(int n);
""")
# set_source() gives the name of the python extension module to
# produce, and some C source code as a string.  This C code needs
# to make the declarated functions, types and globals available,
# so it is often just the "#include".
ffibuilder.set_source("_pi_cffi",
"""
     #include "pi.h"   // the C header of the library
""",
     libraries=['piapprox'])   # library name, for the linker
if __name__ == "__main__":
    ffibuilder.compile(verbose=True)
					

Execute this script. If everything is OK, it should produce _pi_cffi.c , and then invoke the compiler on it. The produced _pi_cffi.c contains a copy of the string given in set_source() , in this example the #include "pi.h" . Afterwards, it contains glue code for all the functions, types and globals declared in the cdef() above.

At runtime, you use the extension module like this:

from _pi_cffi import ffi, lib
print(lib.pi_approx(5000))
					

That’s all! In the rest of this page, we describe some more advanced examples and other CFFI modes. In particular, there is a complete example if you don’t have an already-installed C library to call .

For more information about the cdef() and set_source() methods of the FFI class, see 准备和分发模块 .

When your example works, a common alternative to running the build script manually is to have it run as part of a setup.py . Here is an example using the Setuptools distribution:

from setuptools import setup
setup(
    ...
    setup_requires=["cffi>=1.0.0"],
    cffi_modules=["piapprox_build:ffibuilder"], # "filename:global"
    install_requires=["cffi>=1.0.0"],
)
					

其它 CFFI 模式 ¶

CFFI can be used in one of four modes: “ABI” versus “API” level, each with “in-line” or “out-of-line” preparation (or compilation).

The ABI mode accesses libraries at the binary level, whereas the faster API mode accesses them with a C compiler. We explain the difference in more details below .

在 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.

Simple example (ABI level, in-line) ¶

May look familiar to those who have used ctypes .

>>> from cffi import FFI
>>> ffi = FFI()
>>> ffi.cdef("""
...     int printf(const char *format, ...);   // copy-pasted from the man page
... """)
>>> C = ffi.dlopen(None)                     # loads the entire C namespace
>>> arg = ffi.new("char[]", b"world")        # equivalent to C code: char arg[] = "world";
>>> C.printf(b"hi there, %s.\n", arg)        # call printf
hi there, world.
17                                           # this is the return value
>>>
					

注意， char * arguments expect a bytes object. If you have a str (or a unicode on Python 2) you need to encode it explicitly with somestring.encode(myencoding) .

Python 3 on Windows: ffi.dlopen(None) does not work. This problem is messy and not really fixable. The problem does not occur if you try to call a function from a specific DLL that exists on your system: then you use ffi.dlopen("path.dll") .

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 instead. (It is also faster.)

Struct/Array Example (minimal, in-line) ¶

from cffi import FFI
ffi = FFI()
ffi.cdef("""
    typedef struct {
        unsigned char r, g, b;
    } pixel_t;
""")
image = ffi.new("pixel_t[]", 800*600)
f = open('data', 'rb')     # binary mode -- important
f.readinto(ffi.buffer(image))
f.close()
image[100].r = 255
image[100].g = 192
image[100].b = 128
f = open('data', 'wb')
f.write(ffi.buffer(image))
f.close()
					

This can be used as a more flexible replacement of the struct and array modules, and replaces ctypes . You could also call ffi.new(“pixel_t[600][800]”) 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 the first example 主要使用模式 above, but passing None as the second argument to ffibuilder.set_source() . Then in the main program you write from _simple_example import ffi and then the same content as the in-line example above starting from the line image = ffi.new("pixel_t[]", 800*600) .

API Mode, calling the C standard library ¶

# file "example_build.py"
# Note: we instantiate the same 'cffi.FFI' class as in the previous
# example, but call the result 'ffibuilder' now instead of 'ffi';
# this is to avoid confusion with the other 'ffi' object you get below
from cffi import FFI
ffibuilder = FFI()
ffibuilder.set_source("_example",
   r""" // passed to the real C compiler,
        // contains implementation of things declared in cdef()
        #include <sys/types.h>
        #include <pwd.h>
        // We can also define custom wrappers or other functions
        // here (this is an example only):
        static struct passwd *get_pw_for_root(void) {
            return getpwuid(0);
        }
    """,
    libraries=[])   # or a list of libraries to link with
    # (more arguments like setup.py's Extension class:
    # include_dirs=[..], extra_objects=[..], and so on)
ffibuilder.cdef("""
    // declarations that are shared between Python and C
    struct passwd {
        char *pw_name;
        ...;     // literally dot-dot-dot
    };
    struct passwd *getpwuid(int uid);     // defined in <pwd.h>
    struct passwd *get_pw_for_root(void); // defined in set_source()
""")
if __name__ == "__main__":
    ffibuilder.compile(verbose=True)
					

You need to run the example_build.py script once to generate “source code” into the file _example.c 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 set_source() is None 或不。)

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:

from _example import ffi, lib
p = lib.getpwuid(0)
assert ffi.string(p.pw_name) == b'root'
p = lib.get_pw_for_root()
assert ffi.string(p.pw_name) == b'root'
					

Note that this works independently of the exact C layout of struct passwd (it is “API level”, as opposed to “ABI level”). It requires a C compiler in order to run example_build.py , but it is much more portable than trying to get the details of the fields of struct passwd exactly right. Similarly, in the cdef() we declared getpwuid() as taking an int argument; on some platforms this might be slightly incorrect—but it does not matter.

Note also that at runtime, the API mode is faster than the ABI mode.

To integrate it inside a setup.py distribution with Setuptools:

from setuptools import setup
setup(
    ...
    setup_requires=["cffi>=1.0.0"],
    cffi_modules=["example_build.py:ffibuilder"],
    install_requires=["cffi>=1.0.0"],
)
					

/* filename: pi.c*/
# include <stdlib.h>
# include <math.h>
/* Returns a very crude approximation of Pi
   given a int: a number of iteration */
float pi_approx(int n){
  double i,x,y,sum=0;
  for(i=0;i<n;i++){
    x=rand();
    y=rand();
    if (sqrt(x*x+y*y) < sqrt((double)RAND_MAX*RAND_MAX))
      sum++; }
  return 4*(float)sum/(float)n; }
							

/* filename: pi.h*/
float pi_approx(int n);
								

from cffi import FFI
ffibuilder = FFI()
ffibuilder.cdef("float pi_approx(int n);")
ffibuilder.set_source("_pi",  # name of the output C extension
"""
    #include "pi.h"
""",
    sources=['pi.c'],   # includes pi.c as additional sources
    libraries=['m'])    # on Unix, link with the math library
if __name__ == "__main__":
    ffibuilder.compile(verbose=True)
								

python pi_extension_build.py
									

from _pi.lib import pi_approx
approx = pi_approx(10)
assert str(approx).startswith("3.")
approx = pi_approx(10000)
assert str(approx).startswith("3.1")
									

# file "example_build.py"
from cffi import FFI
ffibuilder = FFI()
ffibuilder.cdef("int foo(int *, int *, int);")
ffibuilder.set_source("_example",
r"""
    static int foo(int *buffer_in, int *buffer_out, int x)
    {
        /* some algorithm that is seriously faster in C than in Python */
    }
""")
if __name__ == "__main__":
    ffibuilder.compile(verbose=True)
										

# file "example.py"
from _example import ffi, lib
buffer_in = ffi.new("int[]", 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("int[]", 1000)
result = lib.foo(buffer_in, buffer_out, 1000)
										

# file "simple_example_build.py"
from cffi import FFI
ffibuilder = FFI()
# Note that the actual source is None
ffibuilder.set_source("_simple_example", None)
ffibuilder.cdef("""
    int printf(const char *format, ...);
""")
if __name__ == "__main__":
    ffibuilder.compile(verbose=True)
											

from _simple_example import ffi
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("c"))
lib.printf(b"hi there, number %d\n", ffi.cast("int", 2))
											

from setuptools import setup
setup(
    ...
    setup_requires=["cffi>=1.0.0"],
    cffi_modules=["simple_example_build.py:ffibuilder"],
    install_requires=["cffi>=1.0.0"],
)
											

import cffi
ffibuilder = cffi.FFI()
ffibuilder.embedding_api("""
    int do_stuff(int, int);
""")
ffibuilder.set_source("my_plugin", "")
ffibuilder.embedding_init_code("""
    from my_plugin import ffi
    @ffi.def_extern()
    def do_stuff(x, y):
        print("adding %d and %d" % (x, y))
        return x + y
""")
ffibuilder.compile(target="plugin-1.5.*", verbose=True)