diff options
| -rw-r--r-- | README.md | 5 | ||||
| -rw-r--r-- | docs/gcinterface.md | 4 | ||||
| -rw-r--r-- | gc.man | 2 | ||||
| -rw-r--r-- | include/gc/gc.h | 14 | ||||
| -rw-r--r-- | include/gc/gc_gcj.h | 3 | ||||
| -rw-r--r-- | include/gc/gc_mark.h | 2 | ||||
| -rw-r--r-- | include/private/gc_priv.h | 12 | ||||
| -rw-r--r-- | malloc.c | 2 |
8 files changed, 23 insertions, 21 deletions
@@ -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 @@ -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, @@ -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; |