[pypy-commit] cffi default: improve doc for the fix to ffi.new_handle()

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r2431:fff3a26ea892
Date: 2015-11-23 21:34 +0100
http://bitbucket.org/cffi/cffi/changeset/fff3a26ea892/

Log:	improve doc for the fix to ffi.new_handle()

diff --git a/doc/source/using.rst b/doc/source/using.rst
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -843,9 +843,7 @@
 * ``new_handle()`` returns cdata objects that contains references to
   the Python objects; we call them collectively the "handle" cdata
   objects.  The ``void *`` value in these handle cdata objects are
-  random but unique.  *New in version 1.4:* two calls to
-  ``new_handle(x)`` are guaranteed to return cdata objects with
-  different ``void *`` values, even with the same ``x``.
+  random but unique.
 
 * ``from_handle(p)`` searches all live "handle" cdata objects for the
   one that has the same value ``p`` as its ``void *`` value.  It then
@@ -858,6 +856,16 @@
 then the association ``void * -> python_object`` is dead and
 ``from_handle()`` will crash.
 
+*New in version 1.4:* two calls to ``new_handle(x)`` are guaranteed to
+return cdata objects with different ``void *`` values, even with the
+same ``x``.  This is a useful feature that avoids issues with unexpected
+duplicates in the following trick: if you need to keep alive the
+"handle" until explicitly asked to free it, but don't have a natural
+Python-side place to attach it to, then the easiest is to ``add()`` it
+to a global set.  It can later be removed from the set by
+``global_set.discard(p)``, with ``p`` any cdata object whose ``void *``
+value compares equal.
+
 
 .. _`ffi.addressof()`:
 
diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst
--- a/doc/source/whatsnew.rst
+++ b/doc/source/whatsnew.rst
@@ -8,9 +8,10 @@
 
 * ``ffi.new_handle()`` is now guaranteed to return unique ``void *``
   values, even if called twice on the same object.  Previously, in
-  that case, CPython (but not PyPy) would return different ``cdata``
-  objects with the same ``void *`` value.  This is useful to add and
-  remove handles from a global set without worrying about duplicates.
+  that case, CPython (but not PyPy) would return two ``cdata`` objects
+  with the same ``void *`` value.  This change is useful to add and
+  remove handles from a global dict or set without worrying about
+  duplicates.
 
 * ``ffi.init_once()`` XXX
   https://bitbucket.org/cffi/cffi/issues/233/