[pypy-commit] cffi default: Add an example of using a WeakKeyDictionary to keep alive

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r790:4c2779d70326
Date: 2012-08-08 12:05 +0200
http://bitbucket.org/cffi/cffi/changeset/4c2779d70326/

Log:	Add an example of using a WeakKeyDictionary to keep alive more
	objects as long as some root object is alive.

diff --git a/doc/source/index.rst b/doc/source/index.rst
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -538,7 +538,20 @@
 long as needed.  (This also applies if you immediately cast the returned
 pointer to a pointer of a different type: only the original object has
 ownership, so you must keep it alive.  As soon as you forget it, then
-the casted pointer will point to garbage.)
+the casted pointer will point to garbage.)  Example::
+
+    global_weakkeydict = weakref.WeakKeyDictionary()
+
+    s1   = ffi.new("struct foo *")
+    fld1 = ffi.new("struct bar *")
+    fld2 = ffi.new("struct bar *")
+    s1.thefield1 = fld1
+    s1.thefield2 = fld2
+    # here the 'fld1' and 'fld2' object must not go away,
+    # otherwise 's1.thefield1/2' will point to garbage!
+    global_weakkeydict[s1] = (fld1, fld2)
+    # now 's1' keeps alive 'fld1' and 'fld2'.  When 's1' goes
+    # away, then the weak dictionary entry will be removed.
 
 The cdata objects support mostly the same operations as in C: you can
 read or write from pointers, arrays and structures.  Dereferencing a