Fix description of client promise for IGNORE_OFF_PAGE allocated objects

(documentation)

The client should keep a pointer within the first heap block for such
an allocated object.  Previously, it was mentioned in the documentation
and comments that such a pointer should be within the first 256 or 512
bytes.

* README.md (The C Interface to the Allocator): Fix the description
(comment) of GC_malloc_ignore_off_page (the client promises to keep
a pointer within the first hblk of the object instead of 256 or 512
bytes, or a page).
* docs/gcinterface.md (GC_MALLOC_IGNORE_OFF_PAGE): Likewise.
* gc.man (GC_malloc_atomic_ignore_off_page): Likewise.
* include/gc/gc.h (GC_malloc_ignore_off_page): Likewise.
* include/gc/gc_mark.h (GC_generic_malloc_ignore_off_page): Likewise.
* include/private/gc_priv.h (IGNORE_OFF_PAGE): Likewise.
* include/private/gc_priv.h [DBG_HDRS_ALL || GC_GCJ_SUPPORT
|| !GC_NO_FINALIZATION] (GC_generic_malloc_inner_ignore_off_page):
Likewise.
* malloc.c [DBG_HDRS_ALL || GC_GCJ_SUPPORT || !GC_NO_FINALIZATION]
(GC_generic_malloc_inner_ignore_off_page): Likewise.
* include/gc/gc_gcj.h (GC_gcj_malloc_ignore_off_page): Refine comment.

4 files changed, 16 insertions, 15 deletions

diff --git a/include/gc/gc.h b/include/gc/gc.h
index 6bf37930..d4c8f2da 100644
--- a/include/gc/gc.h
+++ b/include/gc/gc.h
@@ -955,13 +955,13 @@ GC_API void GC_CALL GC_start_incremental_collection(void);
 /* until it returns 0.                                          */
 GC_API int GC_CALL GC_collect_a_little(void);
 
-/* Allocate an object of size lb bytes.  The client guarantees that     */
-/* as long as the object is live, it will be referenced by a pointer    */
-/* that points to somewhere within the first 256 bytes of the object.   */
-/* (This should normally be declared volatile to prevent the compiler   */
-/* from invalidating this assertion.)  This routine is only useful      */
-/* if a large array is being allocated.  It reduces the chance of       */
-/* accidentally retaining such an array as a result of scanning an      */
+/* Allocate an object of size lb bytes.  The client guarantees that as  */
+/* long as the object is live, it will be referenced by a pointer that  */
+/* points to somewhere within the first GC heap block (hblk) of the     */
+/* object.  (This should normally be declared volatile to prevent the   */
+/* compiler from invalidating this assertion.)  This routine is only    */
+/* useful if a large array is being allocated.  It reduces the chance   */
+/* of accidentally retaining such an array as a result of scanning an   */
 /* integer that happens to be an address inside the array.  (Actually,  */
 /* it reduces the chance of the allocator not finding space for such    */
 /* an array, since it will try hard to avoid introducing such a false   */
diff --git a/include/gc/gc_gcj.h b/include/gc/gc_gcj.h
index 0520fba1..63e4d803 100644
--- a/include/gc/gc_gcj.h
+++ b/include/gc/gc_gcj.h
@@ -84,7 +84,8 @@ GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL
                             GC_EXTRA_PARAMS);
 
 /* Similar to GC_gcj_malloc, but assumes that a pointer to near the     */
-/* beginning of the resulting object is always maintained.              */
+/* beginning (i.e. within the first heap block) of the allocated object */
+/* is always maintained.                                                */
 GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL
         GC_gcj_malloc_ignore_off_page(size_t /* lb */,
                                 void * /* ptr_to_struct_containing_descr */);
diff --git a/include/gc/gc_mark.h b/include/gc/gc_mark.h
index adbc28ab..8291b1a4 100644
--- a/include/gc/gc_mark.h
+++ b/include/gc/gc_mark.h
@@ -256,7 +256,7 @@ GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL
                                         GC_generic_malloc_ignore_off_page(
                                             size_t /* lb */, int /* knd */);
                                 /* As above, but pointers to past the   */
-                                /* first page of the resulting object   */
+                                /* first hblk of the resulting object   */
                                 /* are ignored.                         */
 
 /* Generalized version of GC_malloc_[atomic_]uncollectable.     */
diff --git a/include/private/gc_priv.h b/include/private/gc_priv.h
index ab61a614..d3857664 100644
--- a/include/private/gc_priv.h
+++ b/include/private/gc_priv.h
@@ -1132,7 +1132,7 @@ struct hblkhdr {
                          /* list headers.  Sometimes called regions.    */
     unsigned char hb_flags;
 #       define IGNORE_OFF_PAGE  1       /* Ignore pointers that do not  */
-                                        /* point to the first page of   */
+                                        /* point to the first hblk of   */
                                         /* this object.                 */
 #       define WAS_UNMAPPED 2   /* This is a free block, which has      */
                                 /* been unmapped from the address       */
@@ -2346,11 +2346,11 @@ GC_INNER void * GC_generic_malloc_inner(size_t lb, int k);
 #if defined(DBG_HDRS_ALL) || defined(GC_GCJ_SUPPORT) \
     || !defined(GC_NO_FINALIZATION)
   GC_INNER void * GC_generic_malloc_inner_ignore_off_page(size_t lb, int k);
-                                /* Allocate an object, where            */
-                                /* the client guarantees that there     */
-                                /* will always be a pointer to the      */
-                                /* beginning of the object while the    */
-                                /* object is live.                      */
+                                /* Allocate an object, where the client */
+                                /* guarantees that there will always be */
+                                /* a pointer to the beginning (i.e.     */
+                                /* within the first hblk) of the object */
+                                /* while it is live.                    */
 #endif
 
 GC_INNER GC_bool GC_collect_or_expand(word needed_blocks,