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