Author: Armin Rigo <ar...@tunes.org>
Branch: static-callback-embedding
Changeset: r2575:084db6ef07fc
Date: 2016-01-13 13:30 +0100
http://bitbucket.org/cffi/cffi/changeset/084db6ef07fc/
Log: more doc
diff --git a/doc/source/cdef.rst b/doc/source/cdef.rst
--- a/doc/source/cdef.rst
+++ b/doc/source/cdef.rst
@@ -138,6 +138,8 @@
for ``lib.__class__`` before version 1.4.
+.. _cdef:
+
ffi.cdef(): declaring types and functions
-----------------------------------------
diff --git a/doc/source/embedding.rst b/doc/source/embedding.rst
--- a/doc/source/embedding.rst
+++ b/doc/source/embedding.rst
@@ -77,3 +77,93 @@
standard library ``distutils`` package, which is really developed
and tested for the purpose of making CPython extension modules, not
other DLLs.
+
+
+More reading
+------------
+
+(XXX should point to a few places in the rest of the CFFI docs where
+people starting from embedding would like to go next)
+
+XXX copy the content of ffi.embedding() to a .h
+
+
+Embedding and Extending
+-----------------------
+
+The embedding mode is not incompatible with the non-embedding mode of
+CFFI. The Python code can import not only ``ffi`` but also ``lib``
+from the module you define. This ``lib`` contains all the C symbols
+that are available to Python. This includes all functions and global
+variables declared in ``ffi.embedding_api()`` (it is how you should
+read/write the global variables from Python).
+
+But you can use ``ffi.cdef()`` *in addition to*
+``ffi.embedding_api()`` to exchange more C functions and global
+variables between C and Python, without also making them exports of
+the DLL. See `here for more about cdef.`__
+
+.. __: cdef.html#cdef
+
+``ffi.cdef()`` is used to access functions and variables that you can,
+and should, define as ``static`` in ``set_source()``. On the other
+hand, the C functions declared with ``ffi.embedding_api()`` work
+similarly to ``extern "Python"`` functions from ``ffi.cdef()``.
+See `here for more about extern "Python".`__ See `here for details
+about @ffi.def_extern().`__
+
+.. __: using.html#extern-python
+.. __: using.html#extern-python-ref
+
+In some cases, you want to write a DLL-exported C function in C
+directly, maybe to handle some cases before calling Python functions.
+To do that, you must *not* write the function's signature in
+``ffi.embedding_api()``. You must only write the custom function
+definition in ``ffi.set_source()``, and prefix it with the macro
+CFFI_DLLEXPORT:
+
+.. code-block:: c
+
+ CFFI_DLLEXPORT int myfunc(int a, int b)
+ {
+ /* implementation here */
+ }
+
+This function can, if it wants, invoke Python functions using the
+general mechanism of "callbacks" (technically a call from C to Python,
+although in this case it is not calling anything back): you need a
+``ffi.cdef()`` with "``extern "Python" int mycb(int);``", and then you
+can write this in ``ffi.set_source()``:
+
+.. code-block:: c
+
+ 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);
+ }
+
+and then the Python initialization code needs to contain the lines:
+
+.. code-block:: python
+
+ @ffi.def_extern()
+ def mycb(x):
+ print "hi, I'm called with x =", x
+ return x * 10
+
+This ``@ffi.def_extern`` is attaching a Python function to the C
+callback ``mycb``, which in this case is not exported from the DLL.
+Nevertheless, the automatic initialization of Python occurs at this
+time, if it happens that ``mycb()`` is the first function called
+from C. (It does not happen when ``myfunc()`` is called: this is just
+a C function, with no extra code magically inserted around it. It
+only happens when ``myfunc()`` calls ``mycb()``.)
+
+As the above explanation hints, this is how ``ffi.embedding_api()``
+actually implements function calls that directly invoke Python code;
+we have merely decomposed it explicitly, in order to add some custom C
+code in the middle.
diff --git a/doc/source/using.rst b/doc/source/using.rst
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -603,6 +603,9 @@
}
""")
+
+.. _extern-python-ref:
+
Extern "Python": reference
~~~~~~~~~~~~~~~~~~~~~~~~~~
_______________________________________________
pypy-commit mailing list
pypy-commit@python.org
https://mail.python.org/mailman/listinfo/pypy-commit
