Author: Armin Rigo <[email protected]> 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/ _______________________________________________ pypy-commit mailing list [email protected] https://mail.python.org/mailman/listinfo/pypy-commit
