CFFI 参考 ¶

ffi.buffer(), ffi.from_buffer() ¶

ffi.buffer(cdata, [size]) : return a buffer object that references the raw C data pointed to by the given ‘cdata’, of ‘size’ bytes. What Python calls “a buffer”, or more precisely “an object supporting the buffer interface”, is an object that represents some raw memory and that can be passed around to various built-in or extension functions; these built-in functions read from or write to the raw memory directly, without needing an extra copy.

The ‘cdata’ argument must be a pointer or an array. If unspecified, the size of the buffer is either the size of what cdata points to, or the whole size of the array.

Here are a few examples of where buffer() would be useful:

• 使用 file.write() and file.readinto() with such a buffer (for files opened in binary mode)
• overwrite the content of a struct: if p is a cdata pointing to it, use ffi.buffer(p)[:] = newcontent ，其中 newcontent is a bytes object ( str in Python 2).

Remember that like in C, you can use array + index to get the pointer to the index’th item of an array. (In C you might more naturally write &array[index] , but that is equivalent.)

The returned object’s type is not the builtin buffer nor memoryview types, because these types’ API changes too much across Python versions. Instead it has the following Python API (a subset of Python 2’s buffer ) in addition to supporting the buffer interface:

• buf[:] or bytes(buf) : copy data out of the buffer, returning a regular byte string (or buf[start:end] for a part)
• buf[:] = newstr : copy data into the buffer (or buf[start:end] = newstr )
• len(buf) , buf[index] , buf[index] = newchar : access as a sequence of characters.

The buffer object returned by ffi.buffer(cdata) keeps alive the cdata object: if it was originally an owning cdata, then its owned memory will not be freed as long as the buffer is alive.

Python 2/3 compatibility note: you should avoid using str(buf) , because it gives inconsistent results between Python 2 and Python 3. (This is similar to how str() gives inconsistent results on regular byte strings). Use buf[:] 代替。

New in version 1.10: ffi.buffer is now the type of the returned buffer objects; ffi.buffer() actually calls the constructor.

ffi.from_buffer([cdecl,] python_buffer, require_writable=False) : return an array cdata (by default a <cdata 'char[]'> ) that points to the data of the given Python object, which must support the buffer interface. Note that ffi.from_buffer() turns a generic Python buffer object into a cdata object, whereas ffi.buffer() does the opposite conversion. Both calls don’t actually copy any data.

ffi.from_buffer() is meant to be used on objects containing large quantities of raw data, like bytearrays or array.array or numpy arrays. It supports both the old buffer API (in Python 2.x) and the new memoryview API. Note that if you pass a read-only buffer object, you still get a regular <cdata 'char[]'> ; it is your responsibility not to write there if the original buffer doesn’t expect you to. In particular, never modify byte strings!

The original object is kept alive (and, in case of memoryview, locked) as long as the cdata object returned by ffi.from_buffer() is alive.

A common use case is calling a C function with some char * that points to the internal buffer of a Python object; for this case you can directly pass ffi.from_buffer(python_buffer) as argument to the call.

New in version 1.10: the python_buffer can be anything supporting the buffer/memoryview interface (except unicode strings). Previously, bytearray objects were supported in version 1.7 onwards (careful, if you resize the bytearray, the <cdata> object will point to freed memory); and byte strings were supported in version 1.8 onwards.

New in version 1.12: added the optional 第一 argument cdecl , and the keyword argument require_writable :

• cdecl 默认为 "char[]" , but a different array or (from version 1.13) pointer type can be specified for the result. A value like "int[]" will return an array of ints instead of chars, and its length will be set to the number of ints that fit in the buffer (rounded down if the division is not exact). Values like "int[42]" or "int[2][3]" will return an array of exactly 42 (resp. 2-by-3) ints, raising a ValueError if the buffer is too small. The difference between specifying "int[]" and using the older code p1 = ffi.from_buffer(x); p2 = ffi.cast("int *", p1) is that the older code needs to keep p1 alive as long as p2 is in use, because only p1 keeps the underlying Python object alive and locked. (In addition, ffi.from_buffer("int[]", x) gives better array bound checking.)

  New in version 1.13: cdecl can be a pointer type. If it points to a struct or union, you can, as usual, write p.field 而不是 p[0].field . You can also access p[n] ; note that CFFI does not perform any bounds checking in this case. Note also that p[0] cannot be used to keep the buffer alive (unlike what occurs with ffi.new() ).

• if require_writable is set to True, the function fails if the buffer obtained from python_buffer is read-only (e.g. if python_buffer is a byte string). The exact exception is raised by the object itself, and for things like bytes it varies with the Python version, so don’t rely on it. (Before version 1.12, the same effect can be achieved with a hack: call ffi.memmove(python_buffer, b"", 0) . This has no effect if the object is writable, but fails if it is read-only.) Please keep in mind that CFFI does not implement the C keyword const : even if you set require_writable to False explicitly, you still get a regular read-write cdata pointer.

New in version 1.12: see also ffi.release() .

ffi.memmove() ¶

ffi.memmove(dest, src, n) : copy n bytes from memory area src to memory area dest . See examples below. Inspired by the C functions memcpy() and memmove() —like the latter, the areas can overlap. Each of dest and src can be either a cdata pointer or a Python object supporting the buffer/memoryview interface. In the case of dest , the buffer/memoryview must be writable. New in version 1.3. 范例：

• ffi.memmove(myptr, b"hello", 5) copies the 5 bytes of b"hello" to the area that myptr points to.
• ba = bytearray(100); ffi.memmove(ba, myptr, 100) copies 100 字节来自 myptr into the bytearray ba .
• ffi.memmove(myptr + 1, myptr, 100) shifts 100 bytes from the memory at myptr to the memory at myptr + 1 .

In versions before 1.10, ffi.from_buffer() had restrictions on the type of buffer, which made ffi.memmove() more general.

def myfunction(ptr):
    assert ffi.typeof(ptr) is ffi.typeof("foo_t*")
    ...
										

class MyDocument:
    ...
    def process(self):
        h = ffi.new_handle(self)
        lib.process_document(lib.my_callback,   # the callback
                             h,                 # 'void *data'
                             args...)
        # 'h' stays alive until here, which means that the
        # ffi.from_handle() done in my_callback() during
        # the call to process_document() is safe
    def callback(self, arg1, arg2):
        ...
# the actual callback is this one-liner global function:
@ffi.def_extern()
def my_callback(arg1, arg2, data):
    return ffi.from_handle(data).callback(arg1, arg2)
														

# at module level
new_nonzero = ffi.new_allocator(should_clear_after_alloc=False)
# then replace `p = ffi.new("char[]", bigsize)` with:
    p = new_nonzero("char[]", bigsize)
															

void *malloc(size_t size);
void free(void *ptr);
															

p = lib.malloc(n * ffi.sizeof("int"))
try:
    my_array = ffi.cast("int *", p)
    ...
finally:
    lib.free(p)
															

my_new = ffi.new_allocator(lib.malloc, lib.free)  # at global level
...
with my_new("int[]", n) as my_array:
    ...
															

with ffi.from_buffer(...) as p:
    do something with p
																

from _xyz_cffi import ffi, lib
def initlib():
    lib.init_my_library()
def make_new_foo():
    ffi.init_once(initlib, "init")
    return lib.make_foo()
																

def init_get_max():
    return lib.initialize_once_and_get_some_maximum_number()
def process(i):
    if i > ffi.init_once(init_get_max, "max"):
        raise IndexError("index too large!")
    ...
																

ffi.cdef('''
    FILE *fdopen(int, const char *);   // from the C <stdio.h>
    int fclose(FILE *);
''')
myfile.flush()                    # make sure the file is flushed
newfd = os.dup(myfile.fileno())   # make a copy of the file descriptor
fp = lib.fdopen(newfd, "w")       # make a cdata 'FILE *' around newfd
lib.write_stuff_to_file(fp)       # invoke the external function
lib.fclose(fp)                    # when you're done, close fp (and newfd)