Author: Armin Rigo <ar...@tunes.org> Branch: Changeset: r2712:e2f143d0e9b4 Date: 2016-06-06 14:53 +0200 http://bitbucket.org/cffi/cffi/changeset/e2f143d0e9b4/
Log: Write down a typical ffi.new_handle() usage example diff --git a/doc/source/ref.rst b/doc/source/ref.rst --- a/doc/source/ref.rst +++ b/doc/source/ref.rst @@ -359,6 +359,8 @@ *Calling ffi.from_handle(p) is invalid and will likely crash if the cdata object returned by new_handle() is not kept alive!* +See a `typical usage example`_ below. + (In case you are wondering, this ``void *`` is not the ``PyObject *`` pointer. This wouldn't make sense on PyPy anyway.) @@ -391,6 +393,33 @@ ``global_set.discard(p)``, with ``p`` any cdata object whose ``void *`` value compares equal. +.. _`typical usage example`: + +Usage example: suppose you have a C library where you must call a +``lib.process_document()`` function which invokes some callback. The +``process_document()`` function receives a pointer to a callback and a +``void *`` argument. The callback is then invoked with the ``void +*data`` argument that is equal to the provided value. In this typical +case, you can implement it like this (out-of-line API mode):: + + class MyDocument: + ... + + def process(self): + lib.process_document(lib.my_callback, # the callback + ffi.new_handle(self), # 'void *data' + args...) + # 'self' stay alive at least until here, which means that + # the ffi.from_handle() done in my_callback() are 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) + .. _ffi-dlopen: .. _ffi-dlclose: _______________________________________________ pypy-commit mailing list pypy-commit@python.org https://mail.python.org/mailman/listinfo/pypy-commit
