[pypy-commit] cffi default: Document should_clear_after_alloc a bit more

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r2822:0782c203b090
Date: 2016-11-28 10:11 +0100
http://bitbucket.org/cffi/cffi/changeset/0782c203b090/

Log:	Document should_clear_after_alloc a bit more

diff --git a/doc/source/ref.rst b/doc/source/ref.rst
--- a/doc/source/ref.rst
+++ b/doc/source/ref.rst
@@ -44,6 +44,11 @@
 used for a longer time.  Be careful about that when copying the
 pointer to the memory somewhere else, e.g. into another structure.
 
+The returned memory is initially cleared (filled with zeroes), before
+the optional initializer is applied.  For performance, see
+`ffi.new_allocator()`_ for a way to allocate non-zero-initialized
+memory.
+
 
 ffi.cast()
 ++++++++++
@@ -471,7 +476,16 @@
 
 If ``should_clear_after_alloc`` is set to False, then the memory
 returned by ``alloc()`` is assumed to be already cleared (or you are
-fine with garbage); otherwise CFFI will clear it.
+fine with garbage); otherwise CFFI will clear it.  Example: for
+performance, if you are using ``ffi.new()`` to allocate large chunks of
+memory where the initial content can be left uninitialized, you can do::
+
+    # at module level
+    new_nonzero = ffi.new_allocator(should_clear_after_alloc)
+
+    # then replace `p = ffi.new("char[]", bigsize)` with:
+        p = new_nonzero("char[]", bigsize)
+        
 
 
 ffi.init_once()