| 1 |
/* |
| 2 |
* Copyright (c) 1991-1994 by Xerox Corporation. All rights reserved. |
| 3 |
* Copyright (c) 2001 by Hewlett-Packard Company. All rights reserved. |
| 4 |
* |
| 5 |
* THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED |
| 6 |
* OR IMPLIED. ANY USE IS AT YOUR OWN RISK. |
| 7 |
* |
| 8 |
* Permission is hereby granted to use or copy this program |
| 9 |
* for any purpose, provided the above notices are retained on all copies. |
| 10 |
* Permission to modify the code and to distribute modified code is granted, |
| 11 |
* provided the above notices are retained, and a notice that the code was |
| 12 |
* modified is included with the above copyright notice. |
| 13 |
* |
| 14 |
*/ |
| 15 |
|
| 16 |
/* |
| 17 |
* This contains interfaces to the GC marker that are likely to be useful to |
| 18 |
* clients that provide detailed heap layout information to the collector. |
| 19 |
* This interface should not be used by normal C or C++ clients. |
| 20 |
* It will be useful to runtimes for other languages. |
| 21 |
* |
| 22 |
* This is an experts-only interface! There are many ways to break the |
| 23 |
* collector in subtle ways by using this functionality. |
| 24 |
*/ |
| 25 |
#ifndef GC_MARK_H |
| 26 |
#define GC_MARK_H |
| 27 |
|
| 28 |
#ifndef GC_H |
| 29 |
# include "gc.h" |
| 30 |
#endif |
| 31 |
|
| 32 |
#ifdef __cplusplus |
| 33 |
extern "C" { |
| 34 |
#endif |
| 35 |
|
| 36 |
#define GC_PROC_BYTES 100 |
| 37 |
|
| 38 |
#if defined(GC_BUILD) || defined(NOT_GCBUILD) |
| 39 |
struct GC_ms_entry; |
| 40 |
#else |
| 41 |
struct GC_ms_entry { void *opaque; }; |
| 42 |
#endif |
| 43 |
|
| 44 |
/* A client supplied mark procedure. Returns new mark stack pointer. */ |
| 45 |
/* Primary effect should be to push new entries on the mark stack. */ |
| 46 |
/* Mark stack pointer values are passed and returned explicitly. */ |
| 47 |
/* Global variables describing mark stack are not necessarily valid. */ |
| 48 |
/* (This usually saves a few cycles by keeping things in registers.) */ |
| 49 |
/* Assumed to scan about GC_PROC_BYTES on average. If it needs to do */ |
| 50 |
/* much more work than that, it should do it in smaller pieces by */ |
| 51 |
/* pushing itself back on the mark stack. */ |
| 52 |
/* Note that it should always do some work (defined as marking some */ |
| 53 |
/* objects) before pushing more than one entry on the mark stack. */ |
| 54 |
/* This is required to ensure termination in the event of mark stack */ |
| 55 |
/* overflows. */ |
| 56 |
/* This procedure is always called with at least one empty entry on the */ |
| 57 |
/* mark stack. */ |
| 58 |
/* Currently we require that mark procedures look for pointers in a */ |
| 59 |
/* subset of the places the conservative marker would. It must be safe */ |
| 60 |
/* to invoke the normal mark procedure instead. */ |
| 61 |
/* WARNING: Such a mark procedure may be invoked on an unused object */ |
| 62 |
/* residing on a free list. Such objects are cleared, except for a */ |
| 63 |
/* free list link field in the first word. Thus mark procedures may */ |
| 64 |
/* not count on the presence of a type descriptor, and must handle this */ |
| 65 |
/* case correctly somehow. Also, a mark procedure should be prepared */ |
| 66 |
/* to be executed concurrently from the marker threads (the later ones */ |
| 67 |
/* are created only if the client has called GC_start_mark_threads() */ |
| 68 |
/* or started a user thread previously). */ |
| 69 |
typedef struct GC_ms_entry * (*GC_mark_proc)(GC_word * /* addr */, |
| 70 |
struct GC_ms_entry * /* mark_stack_ptr */, |
| 71 |
struct GC_ms_entry * /* mark_stack_limit */, |
| 72 |
GC_word /* env */); |
| 73 |
|
| 74 |
#define GC_LOG_MAX_MARK_PROCS 6 |
| 75 |
#define GC_MAX_MARK_PROCS (1 << GC_LOG_MAX_MARK_PROCS) |
| 76 |
|
| 77 |
/* In a few cases it's necessary to assign statically known indices to */ |
| 78 |
/* certain mark procs. Thus we reserve a few for well known clients. */ |
| 79 |
/* (This is necessary if mark descriptors are compiler generated.) */ |
| 80 |
#define GC_RESERVED_MARK_PROCS 8 |
| 81 |
#define GC_GCJ_RESERVED_MARK_PROC_INDEX 0 |
| 82 |
|
| 83 |
/* Object descriptors on mark stack or in objects. Low order two */ |
| 84 |
/* bits are tags distinguishing among the following 4 possibilities */ |
| 85 |
/* for the rest (high order) bits. */ |
| 86 |
#define GC_DS_TAG_BITS 2 |
| 87 |
#define GC_DS_TAGS ((1 << GC_DS_TAG_BITS) - 1) |
| 88 |
#define GC_DS_LENGTH 0 /* The entire word is a length in bytes that */ |
| 89 |
/* must be a multiple of 4. */ |
| 90 |
#define GC_DS_BITMAP 1 /* The high order bits are describing pointer */ |
| 91 |
/* fields. The most significant bit is set if */ |
| 92 |
/* the first word is a pointer. */ |
| 93 |
/* (This unconventional ordering sometimes */ |
| 94 |
/* makes the marker slightly faster.) */ |
| 95 |
/* Zeroes indicate definite nonpointers. Ones */ |
| 96 |
/* indicate possible pointers. */ |
| 97 |
/* Only usable if pointers are word aligned. */ |
| 98 |
#define GC_DS_PROC 2 |
| 99 |
/* The objects referenced by this object can be */ |
| 100 |
/* pushed on the mark stack by invoking */ |
| 101 |
/* PROC(descr). ENV(descr) is passed as the */ |
| 102 |
/* last argument. */ |
| 103 |
#define GC_MAKE_PROC(proc_index, env) \ |
| 104 |
((((((GC_word)(env)) << GC_LOG_MAX_MARK_PROCS) \ |
| 105 |
| (proc_index)) << GC_DS_TAG_BITS) | GC_DS_PROC) |
| 106 |
#define GC_DS_PER_OBJECT 3 /* The real descriptor is at the */ |
| 107 |
/* byte displacement from the beginning of the */ |
| 108 |
/* object given by descr & ~GC_DS_TAGS. */ |
| 109 |
/* If the descriptor is negative, the real */ |
| 110 |
/* descriptor is at (*<object_start>) - */ |
| 111 |
/* (descr&~GC_DS_TAGS) - GC_INDIR_PER_OBJ_BIAS */ |
| 112 |
/* The latter alternative can be used if each */ |
| 113 |
/* object contains a type descriptor in the */ |
| 114 |
/* first word. */ |
| 115 |
/* Note that in the multi-threaded environments */ |
| 116 |
/* per-object descriptors must be located in */ |
| 117 |
/* either the first two or last two words of */ |
| 118 |
/* the object, since only those are guaranteed */ |
| 119 |
/* to be cleared while the allocation lock is */ |
| 120 |
/* held. */ |
| 121 |
#define GC_INDIR_PER_OBJ_BIAS 0x10 |
| 122 |
|
| 123 |
GC_API void * GC_least_plausible_heap_addr; |
| 124 |
GC_API void * GC_greatest_plausible_heap_addr; |
| 125 |
/* Bounds on the heap. Guaranteed valid */ |
| 126 |
/* Likely to include future heap expansion. */ |
| 127 |
/* Hence usually includes not-yet-mapped */ |
| 128 |
/* memory, or might overlap with other data */ |
| 129 |
/* roots. */ |
| 130 |
|
| 131 |
/* Handle nested references in a custom mark procedure. */ |
| 132 |
/* Check if obj is a valid object. If so, ensure that it is marked. */ |
| 133 |
/* If it was not previously marked, push its contents onto the mark */ |
| 134 |
/* stack for future scanning. The object will then be scanned using */ |
| 135 |
/* its mark descriptor. */ |
| 136 |
/* Returns the new mark stack pointer. */ |
| 137 |
/* Handles mark stack overflows correctly. */ |
| 138 |
/* Since this marks first, it makes progress even if there are mark */ |
| 139 |
/* stack overflows. */ |
| 140 |
/* Src is the address of the pointer to obj, which is used only */ |
| 141 |
/* for back pointer-based heap debugging. */ |
| 142 |
/* It is strongly recommended that most objects be handled without mark */ |
| 143 |
/* procedures, e.g. with bitmap descriptors, and that mark procedures */ |
| 144 |
/* be reserved for exceptional cases. That will ensure that */ |
| 145 |
/* performance of this call is not extremely performance critical. */ |
| 146 |
/* (Otherwise we would need to inline GC_mark_and_push completely, */ |
| 147 |
/* which would tie the client code to a fixed collector version.) */ |
| 148 |
/* Note that mark procedures should explicitly call FIXUP_POINTER() */ |
| 149 |
/* if required. */ |
| 150 |
GC_API struct GC_ms_entry * GC_CALL GC_mark_and_push(void * /* obj */, |
| 151 |
struct GC_ms_entry * /* mark_stack_ptr */, |
| 152 |
struct GC_ms_entry * /* mark_stack_limit */, |
| 153 |
void ** /* src */); |
| 154 |
|
| 155 |
#define GC_MARK_AND_PUSH(obj, msp, lim, src) \ |
| 156 |
((GC_word)(obj) >= (GC_word)GC_least_plausible_heap_addr && \ |
| 157 |
(GC_word)(obj) <= (GC_word)GC_greatest_plausible_heap_addr ? \ |
| 158 |
GC_mark_and_push(obj, msp, lim, src) : (msp)) |
| 159 |
|
| 160 |
/* The size of the header added to objects allocated through the */ |
| 161 |
/* GC_debug routines. Defined as a function so that client mark */ |
| 162 |
/* procedures do not need to be recompiled for the collector library */ |
| 163 |
/* version changes. */ |
| 164 |
GC_API GC_ATTR_CONST size_t GC_CALL GC_get_debug_header_size(void); |
| 165 |
#define GC_USR_PTR_FROM_BASE(p) \ |
| 166 |
((void *)((char *)(p) + GC_get_debug_header_size())) |
| 167 |
|
| 168 |
/* The same but defined as a variable. Exists only for the backward */ |
| 169 |
/* compatibility. Some compilers do not accept "const" together with */ |
| 170 |
/* deprecated or dllimport attributes, so the symbol is exported as */ |
| 171 |
/* a non-constant one. */ |
| 172 |
GC_API GC_ATTR_DEPRECATED |
| 173 |
# ifdef GC_BUILD |
| 174 |
const |
| 175 |
# endif |
| 176 |
size_t GC_debug_header_size; |
| 177 |
|
| 178 |
/* And some routines to support creation of new "kinds", e.g. with */ |
| 179 |
/* custom mark procedures, by language runtimes. */ |
| 180 |
/* The _inner versions assume the caller holds the allocation lock. */ |
| 181 |
|
| 182 |
/* Return a new free list array. */ |
| 183 |
GC_API void ** GC_CALL GC_new_free_list(void); |
| 184 |
GC_API void ** GC_CALL GC_new_free_list_inner(void); |
| 185 |
|
| 186 |
/* Return a new kind, as specified. */ |
| 187 |
GC_API unsigned GC_CALL GC_new_kind(void ** /* free_list */, |
| 188 |
GC_word /* mark_descriptor_template */, |
| 189 |
int /* add_size_to_descriptor */, |
| 190 |
int /* clear_new_objects */) GC_ATTR_NONNULL(1); |
| 191 |
/* The last two parameters must be zero or one. */ |
| 192 |
GC_API unsigned GC_CALL GC_new_kind_inner(void ** /* free_list */, |
| 193 |
GC_word /* mark_descriptor_template */, |
| 194 |
int /* add_size_to_descriptor */, |
| 195 |
int /* clear_new_objects */) GC_ATTR_NONNULL(1); |
| 196 |
|
| 197 |
/* Return a new mark procedure identifier, suitable for use as */ |
| 198 |
/* the first argument in GC_MAKE_PROC. */ |
| 199 |
GC_API unsigned GC_CALL GC_new_proc(GC_mark_proc); |
| 200 |
GC_API unsigned GC_CALL GC_new_proc_inner(GC_mark_proc); |
| 201 |
|
| 202 |
/* Allocate an object of a given kind. By default, there are only */ |
| 203 |
/* a few kinds: composite (pointerful), atomic, uncollectible, etc. */ |
| 204 |
/* We claim it is possible for clever client code that understands the */ |
| 205 |
/* GC internals to add more, e.g. to communicate object layout */ |
| 206 |
/* information to the collector. Note that in the multi-threaded */ |
| 207 |
/* contexts, this is usually unsafe for kinds that have the descriptor */ |
| 208 |
/* in the object itself, since there is otherwise a window in which */ |
| 209 |
/* the descriptor is not correct. Even in the single-threaded case, */ |
| 210 |
/* we need to be sure that cleared objects on a free list don't */ |
| 211 |
/* cause a GC crash if they are accidentally traced. */ |
| 212 |
GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL GC_generic_malloc( |
| 213 |
size_t /* lb */, |
| 214 |
int /* knd */); |
| 215 |
|
| 216 |
GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL |
| 217 |
GC_generic_malloc_ignore_off_page( |
| 218 |
size_t /* lb */, int /* knd */); |
| 219 |
/* As above, but pointers to past the */ |
| 220 |
/* first hblk of the resulting object */ |
| 221 |
/* are ignored. */ |
| 222 |
|
| 223 |
/* Generalized version of GC_malloc_[atomic_]uncollectable. */ |
| 224 |
GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL |
| 225 |
GC_generic_malloc_uncollectable( |
| 226 |
size_t /* lb */, int /* knd */); |
| 227 |
|
| 228 |
/* Same as above but primary for allocating an object of the same kind */ |
| 229 |
/* as an existing one (kind obtained by GC_get_kind_and_size). */ |
| 230 |
/* Not suitable for GCJ and typed-malloc kinds. */ |
| 231 |
GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL |
| 232 |
GC_generic_or_special_malloc( |
| 233 |
size_t /* size */, int /* knd */); |
| 234 |
GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL |
| 235 |
GC_debug_generic_or_special_malloc( |
| 236 |
size_t /* size */, int /* knd */, |
| 237 |
GC_EXTRA_PARAMS); |
| 238 |
|
| 239 |
#ifdef GC_DEBUG |
| 240 |
# define GC_GENERIC_OR_SPECIAL_MALLOC(sz, knd) \ |
| 241 |
GC_debug_generic_or_special_malloc(sz, knd, GC_EXTRAS) |
| 242 |
#else |
| 243 |
# define GC_GENERIC_OR_SPECIAL_MALLOC(sz, knd) \ |
| 244 |
GC_generic_or_special_malloc(sz, knd) |
| 245 |
#endif /* !GC_DEBUG */ |
| 246 |
|
| 247 |
/* Similar to GC_size but returns object kind. Size is returned too */ |
| 248 |
/* if psize is not NULL. The object pointer should not be NULL. */ |
| 249 |
GC_API int GC_CALL GC_get_kind_and_size(const void *, size_t * /* psize */) |
| 250 |
GC_ATTR_NONNULL(1); |
| 251 |
|
| 252 |
typedef void (GC_CALLBACK * GC_describe_type_fn)(void * /* p */, |
| 253 |
char * /* out_buf */); |
| 254 |
/* A procedure which */ |
| 255 |
/* produces a human-readable */ |
| 256 |
/* description of the "type" of object */ |
| 257 |
/* p into the buffer out_buf of length */ |
| 258 |
/* GC_TYPE_DESCR_LEN. This is used by */ |
| 259 |
/* the debug support when printing */ |
| 260 |
/* objects. */ |
| 261 |
/* These functions should be as robust */ |
| 262 |
/* as possible, though we do avoid */ |
| 263 |
/* invoking them on objects on the */ |
| 264 |
/* global free list. */ |
| 265 |
#define GC_TYPE_DESCR_LEN 40 |
| 266 |
|
| 267 |
GC_API void GC_CALL GC_register_describe_type_fn(int /* kind */, |
| 268 |
GC_describe_type_fn); |
| 269 |
/* Register a describe_type function */ |
| 270 |
/* to be used when printing objects */ |
| 271 |
/* of a particular kind. */ |
| 272 |
|
| 273 |
/* Clear some of the inaccessible part of the stack. Returns its */ |
| 274 |
/* argument, so it can be used in a tail call position, hence clearing */ |
| 275 |
/* another frame. Argument may be NULL. */ |
| 276 |
GC_API void * GC_CALL GC_clear_stack(void *); |
| 277 |
|
| 278 |
/* Set and get the client notifier on collections. The client function */ |
| 279 |
/* is called at the start of every full GC (called with the allocation */ |
| 280 |
/* lock held). May be 0. This is a really tricky interface to use */ |
| 281 |
/* correctly. Unless you really understand the collector internals, */ |
| 282 |
/* the callback should not, directly or indirectly, make any GC_ or */ |
| 283 |
/* potentially blocking calls. In particular, it is not safe to */ |
| 284 |
/* allocate memory using the garbage collector from within the callback */ |
| 285 |
/* function. Both the setter and getter acquire the GC lock. */ |
| 286 |
typedef void (GC_CALLBACK * GC_start_callback_proc)(void); |
| 287 |
GC_API void GC_CALL GC_set_start_callback(GC_start_callback_proc); |
| 288 |
GC_API GC_start_callback_proc GC_CALL GC_get_start_callback(void); |
| 289 |
|
| 290 |
/* Slow/general mark bit manipulation. The caller must hold the */ |
| 291 |
/* allocation lock. GC_is_marked returns 1 (TRUE) or 0. */ |
| 292 |
GC_API int GC_CALL GC_is_marked(const void *) GC_ATTR_NONNULL(1); |
| 293 |
GC_API void GC_CALL GC_clear_mark_bit(const void *) GC_ATTR_NONNULL(1); |
| 294 |
GC_API void GC_CALL GC_set_mark_bit(const void *) GC_ATTR_NONNULL(1); |
| 295 |
|
| 296 |
/* Push everything in the given range onto the mark stack. */ |
| 297 |
/* (GC_push_conditional pushes either all or only dirty pages depending */ |
| 298 |
/* on the third argument.) GC_push_all_eager also ensures that stack */ |
| 299 |
/* is scanned immediately, not just scheduled for scanning. */ |
| 300 |
GC_API void GC_CALL GC_push_all(void * /* bottom */, void * /* top */); |
| 301 |
GC_API void GC_CALL GC_push_all_eager(void * /* bottom */, void * /* top */); |
| 302 |
GC_API void GC_CALL GC_push_conditional(void * /* bottom */, void * /* top */, |
| 303 |
int /* bool all */); |
| 304 |
GC_API void GC_CALL GC_push_finalizer_structures(void); |
| 305 |
|
| 306 |
/* Set and get the client push-other-roots procedure. A client */ |
| 307 |
/* supplied procedure should also call the original procedure. */ |
| 308 |
/* Note that both the setter and getter require some external */ |
| 309 |
/* synchronization to avoid data race. */ |
| 310 |
typedef void (GC_CALLBACK * GC_push_other_roots_proc)(void); |
| 311 |
GC_API void GC_CALL GC_set_push_other_roots(GC_push_other_roots_proc); |
| 312 |
GC_API GC_push_other_roots_proc GC_CALL GC_get_push_other_roots(void); |
| 313 |
|
| 314 |
/* Walk the GC heap visiting all reachable objects. Assume the caller */ |
| 315 |
/* holds the allocation lock. Object base pointer, object size and */ |
| 316 |
/* client custom data are passed to the callback (holding the lock). */ |
| 317 |
typedef void (GC_CALLBACK *GC_reachable_object_proc)(void * /* obj */, |
| 318 |
size_t /* bytes */, |
| 319 |
void * /* client_data */); |
| 320 |
GC_API void GC_CALL GC_enumerate_reachable_objects_inner( |
| 321 |
GC_reachable_object_proc, |
| 322 |
void * /* client_data */) GC_ATTR_NONNULL(1); |
| 323 |
|
| 324 |
GC_API int GC_CALL GC_is_tmp_root(void *); |
| 325 |
|
| 326 |
GC_API void GC_CALL GC_print_trace(GC_word /* gc_no */); |
| 327 |
GC_API void GC_CALL GC_print_trace_inner(GC_word /* gc_no */); |
| 328 |
|
| 329 |
#ifdef __cplusplus |
| 330 |
} /* extern "C" */ |
| 331 |
#endif |
| 332 |
|
| 333 |
#endif /* GC_MARK_H */ |