Fix description of client promise for IGNORE_OFF_PAGE allocated objects

(a cherry-pick of commit d1aa5274a from 'release-8_2')

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).
* doc/gcinterface.md (GC_MALLOC_IGNORE_OFF_PAGE): Likewise.
* doc/gc.man (GC_malloc_atomic_ignore_off_page): Likewise.
* include/gc.h (GC_malloc_ignore_off_page): Likewise.
* include/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_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 c210f2a4..ee1e92a4 100644
--- a/README.md
+++ b/README.md
@@ -316,8 +316,9 @@ all of the following, plus many others.
 
  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 declared volatile to prevent
+       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 Kbytes
        or so.  (`GC_malloc` may result in failure to reclaim such objects.)
diff --git a/doc/gc.man b/doc/gc.man
index aca1fbff..40325b57 100644
--- a/doc/gc.man
+++ b/doc/gc.man
@@ -63,7 +63,7 @@ GC_malloc_ignore_off_page
 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 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 larger than about 100KBytes should be allocated this way.)
+inform the collector that the client code will always maintain a pointer to 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 larger than about 100KBytes should be allocated this way.)
 .LP
 It is also possible to use the collector to find storage leaks in programs destined to be run with standard malloc/free.  The collector can be compiled for thread-safe operation.  Unlike standard malloc, it is safe to call malloc after a previous malloc call was interrupted by a signal, provided the original malloc call is not resumed.
 .LP
diff --git a/doc/gcinterface.md b/doc/gcinterface.md
index fbada004..dd1ecd24 100644
--- a/doc/gcinterface.md
+++ b/doc/gcinterface.md
@@ -69,8 +69,8 @@ Typically not useful for small collectible objects.
 **void * `GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE`(size_t _nbytes_)** - 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/include/gc.h b/include/gc.h
index 5804067e..45968100 100644
--- a/include/gc.h
+++ b/include/gc.h
@@ -851,13 +851,13 @@ GC_API int GC_CALL GC_incremental_protection_needs(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_gcj.h b/include/gc_gcj.h
index 476db221..4dbf0220 100644
--- a/include/gc_gcj.h
+++ b/include/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_mark.h b/include/gc_mark.h
index 5aed0beb..5e94c920 100644
--- a/include/gc_mark.h
+++ b/include/gc_mark.h
@@ -205,7 +205,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 7e3d0bd8..d03de0e3 100644
--- a/include/private/gc_priv.h
+++ b/include/private/gc_priv.h
@@ -1032,7 +1032,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       */
@@ -1986,11 +1986,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 ace047ff..e958b83a 100644
--- a/malloc.c
+++ b/malloc.c
@@ -210,7 +210,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;