[pypy-commit] cffi default: Document some common mistakes of bad lifetime of ffi.new()

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r2738:f634d78ac712
Date: 2016-08-17 14:22 +0200
http://bitbucket.org/cffi/cffi/changeset/f634d78ac712/

Log:	Document some common mistakes of bad lifetime of ffi.new()

diff --git a/doc/source/using.rst b/doc/source/using.rst
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -81,6 +81,33 @@
         # away, then the weak dictionary entry will be removed.
         return s1
 
+Usually you don't need a weak dict: for example, to call a function with
+a ``char * *`` argument that contains a pointer to a ``char *`` pointer,
+it is enough to do this:
+
+.. code-block:: python
+
+    p = ffi.new("char[]", "hello, world")    # p is a 'char *'
+    q = ffi.new("char **", p)                # q is a 'char **'
+    lib.myfunction(q)
+    # p is alive at least until here, so that's fine
+
+However, this is always wrong (usage of freed memory):
+
+.. code-block:: python
+
+    p = ffi.new("char **", ffi.new("char[]", "hello, world"))
+    # WRONG!  as soon as p is built, the inner ffi.new() gets freed!
+
+This is wrong too, for the same reason:
+
+.. code-block:: python
+
+    p = ffi.new("struct my_stuff")
+    p.foo = ffi.new("char[]", "hello, world")
+    # WRONG!  as soon as p.foo is set, the ffi.new() gets freed!
+
+
 The cdata objects support mostly the same operations as in C: you can
 read or write from pointers, arrays and structures.  Dereferencing a
 pointer is done usually in C with the syntax ``*p``, which is not valid