[pypy-commit] cffi default: merge heads

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r3013:7417b70e5b1a
Date: 2017-09-16 15:43 +0200
http://bitbucket.org/cffi/cffi/changeset/7417b70e5b1a/

Log:	merge heads

diff --git a/doc/source/using.rst b/doc/source/using.rst
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -128,10 +128,37 @@
 
 There is no general equivalent to the ``&`` operator in C (because it
 would not fit nicely in the model, and it does not seem to be needed
-here).  But see `ffi.addressof()`__.
+here).  There is `ffi.addressof()`__, but only for some cases.  You
+cannot take the "address" of a number in Python, for example; similarly,
+you cannot take the address of a CFFI pointer.  If you have this kind
+of C code::
+
+    int x, y;
+    fetch_size(&x, &y);
+
+    opaque_t *handle;      // some opaque pointer
+    init_stuff(&handle);   // initializes the variable 'handle'
+    more_stuff(handle);    // pass the handle around to more functions
+
+then you need to rewrite it like this, replacing the variables in C
+with what is logically pointers to the variables:
+
+.. code-block:: python
+
+    px = ffi.new("int *")
+    py = ffi.new("int *")              arr = ffi.new("int[2]")
+    lib.fetch_size(px, py)    -OR-     lib.fetch_size(arr, arr + 1)
+    x = px[0]                          x = arr[0]
+    y = py[0]                          y = arr[1]
+
+    p_handle = ffi.new("opaque_t **")
+    lib.init_stuff(p_handle)   # pass the pointer to the 'handle' pointer
+    handle = p_handle[0]       # now we can read 'handle' out of 'p_handle'
+    lib.more_stuff(handle)
 
 .. __: ref.html#ffi-addressof
 
+
 Any operation that would in C return a pointer or array or struct type
 gives you a fresh cdata object.  Unlike the "original" one, these fresh
 cdata objects don't have ownership: they are merely references to
@@ -208,7 +235,7 @@
 string stored in the source array (adding surrogates if necessary).
 See the `Unicode character types`__ section for more details.
 
-__: ref.html#unichar
+.. __: ref.html#unichar
 
 Note that unlike Python lists or tuples, but like C, you *cannot* index in
 a C array from the end using negative numbers.
diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst
--- a/doc/source/whatsnew.rst
+++ b/doc/source/whatsnew.rst
@@ -11,7 +11,7 @@
   when used as ``charN_t *`` or ``charN_t[]`` they represent a unicode
   string.  The difference with ``wchar_t`` is that they have a known,
   fixed size.  They should work at all places that used to work with
-  ``wchar_t`` (please report an issue if I missing something).  Note
+  ``wchar_t`` (please report an issue if I missed something).  Note
   that with ``set_source()``, you need to make sure that these types are
   actually defined by the C source you provide (if used in ``cdef()``).