[pypy-commit] cffi default: The API mode is faster. Put this forward more.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r2888:58b6002275b8
Date: 2017-02-09 12:29 +0100
http://bitbucket.org/cffi/cffi/changeset/58b6002275b8/

Log:	The API mode is faster. Put this forward more.

diff --git a/doc/source/cdef.rst b/doc/source/cdef.rst
--- a/doc/source/cdef.rst
+++ b/doc/source/cdef.rst
@@ -48,9 +48,9 @@
 
 .. _out-of-line-api:
 
-* The **"out-of-line", "API mode"** gives you the most flexibility to
-  access a C library at the level of C, instead of at the binary
-  level:
+* The **"out-of-line", "API mode"** gives you the most flexibility
+  and speed to access a C library at the level of C, instead of at the
+  binary level:
 
   .. code-block:: python
 
@@ -278,8 +278,10 @@
 
 ``ffi.dlopen(libpath, [flags])``: this function opens a shared library and
 returns a module-like library object.  Use this when you are fine with
-the limitations of ABI-level access to the system.  In case of doubt, read
-again `ABI versus API`_ in the overview.
+the limitations of ABI-level access to the system (dependency on ABI
+details, getting crashes instead of C compiler errors/warnings, and
+higher overhead to call the C functions).  In case of doubt, read again
+`ABI versus API`_ in the overview.
 
 .. _`ABI versus API`: overview.html#abi-versus-api
 
diff --git a/doc/source/overview.rst b/doc/source/overview.rst
--- a/doc/source/overview.rst
+++ b/doc/source/overview.rst
@@ -8,7 +8,7 @@
 each with "in-line" or "out-of-line" preparation (or compilation).
 
 The **ABI mode** accesses libraries at the binary level, whereas the
-**API mode** accesses them with a C compiler.  This is described in
+faster **API mode** accesses them with a C compiler.  This is described in
 detail below__.
 
 .. __: `abi-versus-api`_
@@ -51,7 +51,7 @@
 
 If using a C compiler to install your module is an option, it is highly
 recommended to use the API mode described in the next paragraph.  (It is
-also a bit faster at runtime.)
+also faster.)
 
 
 .. _out-of-line-api-level:
@@ -116,7 +116,8 @@
 portable than trying to get the details of the fields of ``struct
 passwd`` exactly right.  Similarly, we declared ``getpwuid()`` as
 taking an ``int`` argument.  On some platforms this might be slightly
-incorrect---but it does not matter.
+incorrect---but it does not matter.  It is also faster than the ABI
+mode.
 
 To integrate it inside a ``setup.py`` distribution with Setuptools:
 
@@ -391,17 +392,25 @@
 --------------
 
 Accessing the C library at the binary level ("ABI") is fraught
-with problems, particularly on non-Windows platforms.  You are not
-meant to access fields by guessing where they are in the structures.
-*The C libraries are typically meant to be used with a C compiler.*
+with problems, particularly on non-Windows platforms.
 
-The "real example" above shows how to do that: this example uses
-``set_source(..., "C source...")`` and never ``dlopen()``.
-When using this approach,
+The most immediate drawback of the ABI level is that calling functions
+needs to go through the very general *libffi* library, which is slow
+(and not always perfectly tested on non-standard platforms).  The API
+mode instead compiles a CPython C wrapper that directly invokes the
+target function.  It is, comparatively, massively faster (and works
+better than libffi ever can).
+
+The more fundamental reason to prefer the API mode is that *the C
+libraries are typically meant to be used with a C compiler.* You are not
+supposed to do things like guess where fields are in the structures.
+The "real example" above shows how CFFI uses a C compiler under the
+hood: this example uses ``set_source(..., "C source...")`` and never
+``dlopen()``.  When using this approach,
 we have the advantage that we can use literally "``...``" at various places in
 the ``cdef()``, and the missing information will be completed with the
-help of the C compiler.  Actually, a single C source file is produced,
-which contains first the "C source" part unmodified, followed by some
+help of the C compiler.  CFFI will turn this into a single C source file,
+which contains the "C source" part unmodified, followed by some
 "magic" C code and declarations derived from the ``cdef()``.  When
 this C file is compiled, the resulting C extension module will contain
 all the information we need---or the C compiler will give warnings or