Author: Armin Rigo <ar...@tunes.org>
Branch:
Changeset: r2327:35fb1f6a0eac
Date: 2015-10-07 08:54 +0200
http://bitbucket.org/cffi/cffi/changeset/35fb1f6a0eac/
Log: Document __stdcall.
diff --git a/doc/source/using.rst b/doc/source/using.rst
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -494,11 +494,6 @@
return 0
lib.python_callback = python_callback
-Windows: you can't yet specify the calling convention of callbacks.
-(For regular calls, the correct calling convention should be
-automatically inferred by the C backend.) Use an indirection, like
-in the example just above.
-
Be careful when writing the Python callback function: if it returns an
object of the wrong type, or more generally raises an exception, then
the exception cannot be propagated. Instead, it is printed to stderr
@@ -547,6 +542,47 @@
that frame by reading ``traceback.tb_frame.f_locals['argname']``.
+Windows: calling conventions
+----------------------------
+
+On Win32, functions can have two main calling conventions: either
+"cdecl" (the default), or "stdcall" (also known as "WINAPI"). There
+are also other, rare calling conventions; these are not supported.
+
+When you issue calls from Python to C, the implementation is such that
+it works with any of these two main calling conventions; you don't
+have to specify it. However, if you manipulate variables of type
+"function pointer" or declare callbacks, then the calling convention
+must be correct. This is done by writing ``__cdecl`` or ``__stdcall``
+in the type, like in C::
+
+ @ffi.callback("int __stdcall(int, int)")
+ def AddNumbers(x, y):
+ return x + y
+
+or::
+
+ ffi.cdef("""
+ struct foo_s {
+ int (__stdcall *MyFuncPtr)(int, int);
+ };
+ """)
+
+``__cdecl`` is supported but is always the default so it can be left
+out. In the ``cdef()``, you can also use ``WINAPI`` as equivalent to
+``__stdcall``. As mentioned above, it is not needed (but doesn't
+hurt) to say ``WINAPI`` or ``__stdcall`` when declaring a plain
+function in the ``cdef()``.
+
+These calling convention specifiers are accepted but ignored on any
+platform other than 32-bit Windows.
+
+*New in version 1.3:* the calling convention specifiers are not
+recognized in previous versions. In API mode, you could work around
+it by using an indirection, like in the example in the section about
+Callbacks_. There was no way to use stdcall callbacks in ABI mode.
+
+
FFI Interface
-------------
diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst
--- a/doc/source/whatsnew.rst
+++ b/doc/source/whatsnew.rst
@@ -19,7 +19,12 @@
It also fixes corner cases like ``typedef const int T; T a;``
which would previously not consider ``a`` as a constant.
-* XXX __stdcall
+* Win32: support for ``__stdcall``. For callbacks and function
+ pointers; regular C functions don't need to have their `calling
+ convention`_ declared.
+
+
+.. _`calling convention`: using.html#windows-calling-conventions
v1.2.1
_______________________________________________
pypy-commit mailing list
pypy-commit@python.org
https://mail.python.org/mailman/listinfo/pypy-commit
