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.

8 files changed, 23 insertions, 21 deletions

diff --git a/README.md b/README.md
index 8c7e2c48..e1a66e53 100644
--- a/README.md
+++ b/README.md
@@ -341,8 +341,9 @@ others.
   frequent collections at program startup.)
 
   6. `GC_malloc_ignore_off_page(bytes)` - Identical to `GC_malloc`, but the
-  client promises to keep a pointer to the somewhere within the first 256
-  bytes of the object while it is live.  (This pointer should normally be
+  client promises to keep a pointer to the somewhere within the first GC
+  heap block (512 .. 4096 bytes or even more, depending on the configuration)
+  of the object while it is live.  (This pointer should normally be
   declared volatile to prevent interference from compiler optimizations.)
   This is the recommended way to allocate anything that is likely to be
   larger than 100 KB or so.  (`GC_malloc` may result in a failure to reclaim
diff --git a/docs/gcinterface.md b/docs/gcinterface.md
index fb764b0d..c0406fd4 100644
--- a/docs/gcinterface.md
+++ b/docs/gcinterface.md
@@ -70,8 +70,8 @@ Typically not useful for small collectible objects.
 `void * GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(size_t _bytes_)` - Analogous
 to `GC_MALLOC` and `GC_MALLOC_ATOMIC`, respectively, except that the client
 guarantees that as long as the resulting object is of use, a pointer
-is maintained to someplace inside the first 512 bytes of the object. This
-pointer should be declared volatile to avoid interference from compiler
+is maintained to someplace inside the first heap block (hblk) of the object.
+This pointer should be declared volatile to avoid interference from compiler
 optimizations. (Other nonvolatile pointers to the object may exist as well.)
 This is the preferred way to allocate objects that are likely to be
 more than 100 KB in size. It greatly reduces the risk that such objects will
diff --git a/gc.man b/gc.man
index 640bd511..6725d889 100644
--- a/gc.man
+++ b/gc.man
@@ -90,7 +90,7 @@ and
 .I
 GC_malloc_atomic_ignore_off_page
 inform the collector that the client code will always maintain a pointer to
-near the beginning of the object (within the first 512 bytes), and that
+near the beginning (i.e. within the first heap block) of the object, and that
 pointers beyond that can be ignored by the collector.  This makes it much
 easier for the collector to place large objects.  These are recommended for
 large object allocation.  (Objects expected to be > ~100 KB should be
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,
diff --git a/malloc.c b/malloc.c
index 82c97e8a..6de6902f 100644
--- a/malloc.c
+++ b/malloc.c
@@ -207,7 +207,7 @@ 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)
   /* Allocate a composite object of size n bytes.  The caller           */
-  /* guarantees that pointers past the first page are not relevant.     */
+  /* guarantees that pointers past the first hblk are not relevant.     */
   GC_INNER void * GC_generic_malloc_inner_ignore_off_page(size_t lb, int k)
   {
     size_t lb_adjusted;