CFFI - ABI模式与API模式

CFFI可以在四种模式中使用:“ABI”和“API”级别，每种模式都有 in-line 或 out- line 准备(或编译)

ABI模式从二进制级别访问库，而更快的API模式通过C编译器访问库

在 in-line 模式中，每次导入Python代码时都会设置所有内容

在 out- line 模式中，有一个单独的准备步骤(可能还有C编译)，它生成一个模块，主程序可以导入该模块

| 版权声明：itisyang，未经博主允许不得转载。

简单例子（ABI, in-line）

>>> 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[]", "world")         # equivalent to C code: char arg[] = "world";
>>> C.printf("hi there, %s.\n", arg)         # call printf
hi there, world.
17                                           # this is the return value
>>>
复制代码

注意，在Python 3中，需要将byte strings传递给char *参数，在上面的示例中，它将是b“world”和b“hi there， %s!\n”，通常也可以这样 somestring.encode(myencoding)

Windows上的Python 3: ffi.dlopen(None)无法工作。这个问题很混乱，而且无法真正解决。如果尝试从系统上存在的特定DLL调用函数，则不会出现问题： 使用ffi.dlopen(“path.dll”)。

这个例子不调用任何C编译器。它在所谓的ABI模式下工作，这意味着如果您调用某个函数或访问某个在cdef()中稍有错误声明的结构的某些字段，它就会崩溃。

如果使用C编译器安装模块是一个选项，那么强烈建议使用API模式。(它也更快。)

结构/数组的例子(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()
复制代码

您可以调用ffi.new(“pixel_t[600][800]”)获得一个二维数组。

API模式，调用C标准库

# 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)
复制代码

您需要运行example_build.py脚本一次生成“source code”到文件_example.c中。并将其编译为一个常规的c扩展模块。(CFFI根据set_source()的第二个参数是否为None，选择生成Python或C模块。)

这一步需要一个C编译器。它生成一个名为 _example.so 或 _example.pyd 的文件。如果需要，它可以像其他扩展模块一样以预编译的形式发布。

在主程序中使用：

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'
复制代码

注意，passwd 结构体是独立精确的C布局结构（它是“API级别”，而不是“ABI级别”），需要一个C编译器才能运行 example_build.py 。

还要注意，在运行时，API模式比ABI模式快。

把这个模块使用Setuptools集成到setup.py中：

from setuptools import setup

setup(
    ...
    setup_requires=["cffi>=1.0.0"],
    cffi_modules=["example_build.py:ffibuilder"],
    install_requires=["cffi>=1.0.0"],
)
复制代码

API模式，调用C源代码而不是编译库

如果您想调用一些没有预编译的库，但是有C源代码的库，那么最简单的解决方案是创建一个单独的扩展模块，该模块由这个库的C源代码和额外的CFFI包装器编译而成。例如，假设您从文件 pi.c 和 pi.h 开始:

/* 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);
复制代码

创建一个名为 pi_extension_build.py 的脚本，构建C扩展:

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
复制代码

可以发现，在工作目录中，生成的输出文件: _pi.c, _pi.o 和编译后的C扩展(例如Linux上生成 _pi.so )。它可以从Python调用:

from _pi.lib import pi_approx

approx = pi_approx(10)
assert str(pi_approximation).startswith("3.")

approx = pi_approx(10000)
assert str(approx).startswith("3.1")
复制代码

Out-of-line, ABI level

out-of-line ABI 模式是 常规(API)out-of-line模式和in-line ABI 的混合，优点是不需要C编译器)，缺点是更容易崩溃。

这种混合模式可以大大减少导入时间，因为解析大型C头文件很慢。它还允许您在构建时进行更详细的检查，而不必担心性能。

# file "simple_example_build.py"

from cffi import FFI

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

if __name__ == "__main__":
    ffibuilder.compile(verbose=True)
复制代码

运行一次会产生_simple_example.py，你的主程序只导入生成的模块，而不再需要 simple_example_build.py

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))
复制代码

注意，ffi.dlopen()不会调用任何额外的方法来定位库，这意味着 ffi.dlopen(“libfoo.so”)是可以的，但是ffi.dlopen(“foo”)不行。 在后一种情况下，您可以将其替换为ffi.dlopen(ctypes.util.find_library(“foo”))。并且，None 只能在Unix打开C标准库。

为了便于分发，你可以把它静态地包含在你的项目的源文件中，使用Setuptools在setup.py这样编写：

from setuptools import setup

setup(
    ...
    setup_requires=["cffi>=1.0.0"],
    cffi_modules=["simple_example_build.py:ffibuilder"],
    install_requires=["cffi>=1.0.0"],
)
复制代码

ABI 与 API

在二进制级别 (“ABI”) 访问C库充满了问题，尤其是在非 windows 平台上。

ABI 级别最直接的缺点是，调用函数需要经过非常通用的 libffi 库，它很慢（而且总是不能在非标准平台上完美通过测试）。API模式编译一个直接调用目标函数的 CPython C 包装器。相对而言，它的速度要快得多(而且运行得比 libffi 更好)。

选择API模式的更基本原因是，C库通常与C编译器一起使用。你不应该做诸如猜测结构中字段的位置之类的事情。上面的“真实示例”展示了CFFI如何在底层使用C编译器:示例使用 set_source(..., "C source...") 而不是 dlopen()。当使用这种方法时，我们有一个优势，我们可以在 cdef() 的不同地方使用字面上的 “……” ，缺失的信息将在C编译器的帮助下完成。CFFI 将把它转换为单个C源文件，其中包含未修改的 “C source” 部分，后面跟随着一些特殊C代码和 cdef() 派生的声明。当编译这个C文件时，生成的C扩展模块将包含我们需要的所有信息。就像往常一样，如果我们错误地声明了某个函数的签名，C编译器将给出警告或错误。

注意，set_source()中的 “C source” 部分可以包含任意的C代码。您可以使用它来声明一些用c语言编写的辅助函数。（你可以在“C source”部分，使用static C关键字）

例如，这可以用来将宏包装成更标准的C函数。额外的C层在其他方面也很有用，比如调用函数，这些函数需要一些复杂的参数结构，您更喜欢在C中构建而不是在Python中。(另一方面，如果您需要调用 “function-like” 宏，那么您可以直接在cdef()中声明它们，就好像它们是函数一样。)