[pypy-commit] pypy default: Documentation for ll_nonmovable_raw_ptr_for_resizable_list()

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r84934:6aeeb58ecd40
Date: 2016-06-05 14:21 +0200
http://bitbucket.org/pypy/pypy/changeset/6aeeb58ecd40/

Log:	Documentation for ll_nonmovable_raw_ptr_for_resizable_list()

diff --git a/rpython/rlib/rgc.py b/rpython/rlib/rgc.py
--- a/rpython/rlib/rgc.py
+++ b/rpython/rlib/rgc.py
@@ -1242,6 +1242,19 @@
                                  v_list)
 
 def ll_nonmovable_raw_ptr_for_resizable_list(ll_list):
+    """
+    WARNING: dragons ahead.
+    Return the address of the internal char* buffer of 'll_list', which
+    must be a resizable list of chars.
+
+    This makes sure that the list items are non-moving, if necessary by
+    first copying the GcArray inside 'll_list.items' outside the GC
+    nursery.  The returned 'char *' pointer is guaranteed to be valid
+    until one of these occurs:
+
+       * 'll_list' gets garbage-collected; or
+       * you do an operation on 'll_list' that changes its size.
+    """
     from rpython.rtyper.lltypesystem import lltype, rffi
     array = ll_list.items
     if can_move(array):