[pypy-commit] cffi release-0.8: Document some limitations of ffi.gc(), particularly on PyPy.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: release-0.8
Changeset: r1434:e11a35d1fa1a
Date: 2013-11-29 23:55 +0100
http://bitbucket.org/cffi/cffi/changeset/e11a35d1fa1a/

Log:	Document some limitations of ffi.gc(), particularly on PyPy.
	(transplanted from 4480f85a1279b0f13803821265a096b35b40cefa)

diff --git a/doc/source/index.rst b/doc/source/index.rst
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1240,6 +1240,17 @@
 object is garbage-collected.  *New in version 0.3* (together
 with the fact that any cdata object can be weakly referenced).
 
+Note that this 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 that allocate and free the C data at known
+points in time, and using it in a ``with`` statement.
+
 .. "versionadded:: 0.3" --- inlined in the previous paragraph
 
 ``ffi.new_handle(python_object)``: return a non-NULL cdata of type