[pypy-commit] cffi default: Document ffi.gc(..., size)

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r2999:5b1214633c90
Date: 2017-08-02 16:13 +0200
http://bitbucket.org/cffi/cffi/changeset/5b1214633c90/

Log:	Document ffi.gc(..., size)

diff --git a/doc/source/ref.rst b/doc/source/ref.rst
--- a/doc/source/ref.rst
+++ b/doc/source/ref.rst
@@ -352,10 +352,13 @@
 .. __: #ffi-buffer
 
 
+.. _ffi-gc:
+
 ffi.gc()
 ++++++++
 
-**ffi.gc(cdata, destructor)**: return a new cdata object that points to the
+**ffi.gc(cdata, destructor, size=0)**:
+return a new cdata object that points to the
 same data.  Later, when this new cdata object is garbage-collected,
 ``destructor(old_cdata_object)`` will be called.  Example of usage:
 ``ptr = ffi.gc(lib.custom_malloc(42), lib.custom_free)``.
@@ -364,21 +367,38 @@
 which means the destructor is called as soon as *this* exact returned
 object is garbage-collected.
 
-**ffi.gc(ptr, None)**: removes the ownership on a object returned by a
+**ffi.gc(ptr, None, size=0)**:
+removes the ownership on a object returned by a
 regular call to ``ffi.gc``, and no destructor will be called when it
 is garbage-collected.  The object is modified in-place, and the
 function returns ``None``.  *New in version 1.7: ffi.gc(ptr, None)*
 
-Note that ``ffi.gc()`` should be avoided for large memory allocations or
-for limited resources.  This is particularly true on PyPy: its GC does
-not know how much memory or how many resources the returned ``ptr``
-holds.  It will only run its GC when enough memory it knows about has
-been allocated (and thus run the destructor possibly later than you
-would expect).  Moreover, the destructor is called in whatever thread
-PyPy is at that moment, which might be a problem for some C libraries.
-In these cases, consider writing a wrapper class with custom ``__enter__()``
-and ``__exit__()`` methods, allocating and freeing the C data at known
-points in time, and using it in a ``with`` statement.
+Note that ``ffi.gc()`` should be avoided for limited resources, or (with
+cffi below 1.11) for large memory allocations.  This is particularly
+true on PyPy: its GC does not know how much memory or how many resources
+the returned ``ptr`` holds.  It will only run its GC when enough memory
+it knows about has been allocated (and thus run the destructor possibly
+later than you would expect).  Moreover, the destructor is called in
+whatever thread PyPy is at that moment, which might be a problem for
+some C libraries.  In these cases, consider writing a wrapper class with
+custom ``__enter__()`` and ``__exit__()`` methods, allocating and
+freeing the C data at known points in time, and using it in a ``with``
+statement.
+
+*New in version 1.11:* the ``size`` argument.  If given, this should be
+an estimate of the size (in bytes) that ``ptr`` keeps alive.  This
+information is passed on to the garbage collector, fixing part of the
+problem described above.  The ``size`` argument is most important on
+PyPy; on CPython, it is ignored so far, but in the future it could be
+used to trigger more eagerly the cyclic reference GC, too (see CPython
+`issue 31105`__).
+
+The form ``ffi.gc(ptr, None, size=0)`` can be called with a negative
+``size``, to cancel the estimate.  It is not mandatory, though:
+nothing gets out of sync if the size estimates do not match.  It only
+makes the next GC start more or less early.
+
+.. __: http://bugs.python.org/issue31105
 
 
 .. _ffi-new-handle:
diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst
--- a/doc/source/whatsnew.rst
+++ b/doc/source/whatsnew.rst
@@ -43,7 +43,16 @@
 * Functions returning booleans would in some case still return 0 or 1
   instead of False or True.  Fixed.
 
+* `ffi.gc()`__ now takes an optional third parameter, which gives an
+  estimate of the size (in bytes) of the object.  So far, this is only
+  used by PyPy, to make the next GC occur more quickly (`issue #320`__).
+  In the future, this might have an effect on CPython too (provided
+  the CPython `issue 31105`__ is addressed).
+
 .. __: https://bitbucket.org/cffi/cffi/issues/321/cffi-191-segmentation-fault-during-self
+.. __: ref.html#ffi-gc
+.. __: https://bitbucket.org/cffi/cffi/issues/320/improve-memory_pressure-management
+.. __: http://bugs.python.org/issue31105
 
 
 v1.10.1