src/mm/boehm-gc/include/gc.h

   1 /*
   2  * Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
   3  * Copyright (c) 1991-1995 by Xerox Corporation.  All rights reserved.
   4  * Copyright 1996-1999 by Silicon Graphics.  All rights reserved.
   5  * Copyright 1999 by Hewlett-Packard Company.  All rights reserved.
   6  * Copyright (C) 2007 Free Software Foundation, Inc
   7  *
   8  * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
   9  * OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
  10  *
  11  * Permission is hereby granted to use or copy this program
  12  * for any purpose,  provided the above notices are retained on all copies.
  13  * Permission to modify the code and to distribute modified code is granted,
  14  * provided the above notices are retained, and a notice that the code was
  15  * modified is included with the above copyright notice.
  16  */
  17
  18 /*
  19  * Note that this defines a large number of tuning hooks, which can
  20  * safely be ignored in nearly all cases.  For normal use it suffices
  21  * to call only GC_MALLOC and perhaps GC_REALLOC.
  22  * For better performance, also look at GC_MALLOC_ATOMIC, and
  23  * GC_enable_incremental.  If you need an action to be performed
  24  * immediately before an object is collected, look at GC_register_finalizer.
  25  * If you are using Solaris threads, look at the end of this file.
  26  * Everything else is best ignored unless you encounter performance
  27  * problems.
  28  */
  29
  30 #ifndef GC_H
  31 #define GC_H
  32
  33 #include "gc_version.h"
  34         /* Define version numbers here to allow test on build machine   */
  35         /* for cross-builds.  Note that this defines the header         */
  36         /* version number, which may or may not match that of the       */
  37         /* dynamic library.  GC_get_version() can be used to obtain     */
  38         /* the latter.                                                  */
  39
  40 #include "gc_config_macros.h"
  41
  42 #ifdef __cplusplus
  43   extern "C" {
  44 #endif
  45
  46
  47 /* Define word and signed_word to be unsigned and signed types of the   */
  48 /* size as char * or void *.  There seems to be no way to do this       */
  49 /* even semi-portably.  The following is probably no better/worse       */
  50 /* than almost anything else.                                           */
  51 /* The ANSI standard suggests that size_t and ptrdiff_t might be        */
  52 /* better choices.  But those had incorrect definitions on some older   */
  53 /* systems.  Notably "typedef int size_t" is WRONG.                     */
  54 #ifdef _WIN64
  55 # ifdef __int64
  56     typedef unsigned __int64 GC_word;
  57     typedef __int64 GC_signed_word;
  58 # else
  59     typedef unsigned long long GC_word;
  60     typedef long long GC_signed_word;
  61 # endif
  62 #else
  63   typedef unsigned long GC_word;
  64   typedef long GC_signed_word;
  65 #endif
  66
  67 /* Get the GC library version. The returned value is in the form:       */
  68 /* ((version_major<<16) | (version_minor<<8) | alpha_version).          */
  69 GC_API unsigned GC_CALL GC_get_version(void);
  70
  71 /* Public read-only variables */
  72 /* The supplied getter functions are preferred for new code.            */
  73
  74 GC_API GC_word GC_gc_no;/* Counter incremented per collection.          */
  75                         /* Includes empty GCs at startup.               */
  76 GC_API GC_word GC_CALL GC_get_gc_no(void);
  77                         /* GC_get_gc_no() uses no synchronization, so   */
  78                         /* it requires GC_call_with_alloc_lock() to     */
  79                         /* avoid data races on multiprocessors.         */
  80
  81 GC_API int GC_parallel; /* GC is parallelized for performance on        */
  82                         /* multiprocessors.  Currently set only         */
  83                         /* implicitly if collector is built with        */
  84                         /* PARALLEL_MARK defined and if either:         */
  85                         /*  Env variable GC_NPROC is set to > 1, or     */
  86                         /*  GC_NPROC is not set and this is an MP.      */
  87                         /* If GC_parallel is set, incremental           */
  88                         /* collection is only partially functional,     */
  89                         /* and may not be desirable.                    */
  90 GC_API int GC_CALL GC_get_parallel(void);
  91
  92
  93 /* Public R/W variables */
  94 /* The supplied setter and getter functions are preferred for new code. */
  95
  96 typedef void * (GC_CALLBACK * GC_oom_func)(size_t /* bytes_requested */);
  97 GC_API GC_oom_func GC_oom_fn;
  98                         /* When there is insufficient memory to satisfy */
  99                         /* an allocation request, we return             */
 100                         /* (*GC_oom_fn)(size).  By default this just    */
 101                         /* returns NULL.                                */
 102                         /* If it returns, it must return 0 or a valid   */
 103                         /* pointer to a previously allocated heap       */
 104                         /* object.  GC_oom_fn must not be 0.            */
 105                         /* Both the supplied setter and the getter      */
 106                         /* acquire the GC lock (to avoid data races).   */
 107 GC_API void GC_CALL GC_set_oom_fn(GC_oom_func);
 108 GC_API GC_oom_func GC_CALL GC_get_oom_fn(void);
 109
 110 GC_API int GC_find_leak;
 111                         /* Do not actually garbage collect, but simply  */
 112                         /* report inaccessible memory that was not      */
 113                         /* deallocated with GC_free.  Initial value     */
 114                         /* is determined by FIND_LEAK macro.            */
 115                         /* The setter and getter are unsynchronized, so */
 116                         /* GC_call_with_alloc_lock() is required to     */
 117                         /* avoid data races (if the value is modified   */
 118                         /* after the GC is put to multi-threaded mode). */
 119 GC_API void GC_CALL GC_set_find_leak(int);
 120 GC_API int GC_CALL GC_get_find_leak(void);
 121
 122 GC_API int GC_all_interior_pointers;
 123                         /* Arrange for pointers to object interiors to  */
 124                         /* be recognized as valid.  May not be changed  */
 125                         /* after GC initialization.  The initial value  */
 126                         /* depends on whether the GC is built with      */
 127                         /* ALL_INTERIOR_POINTERS macro defined or not.  */
 128                         /* Unless DONT_ADD_BYTE_AT_END is defined, this */
 129                         /* also affects whether sizes are increased by  */
 130                         /* at least a byte to allow "off the end"       */
 131                         /* pointer recognition.                         */
 132                         /* MUST BE 0 or 1.                              */
 133 GC_API void GC_CALL GC_set_all_interior_pointers(int);
 134 GC_API int GC_CALL GC_get_all_interior_pointers(void);
 135
 136 GC_API int GC_finalize_on_demand;
 137                         /* If nonzero, finalizers will only be run in   */
 138                         /* response to an explicit GC_invoke_finalizers */
 139                         /* call.  The default is determined by whether  */
 140                         /* the FINALIZE_ON_DEMAND macro is defined      */
 141                         /* when the collector is built.                 */
 142                         /* The setter and getter are unsynchronized, so */
 143                         /* GC_call_with_alloc_lock() is required to     */
 144                         /* avoid data races (if the value is modified   */
 145                         /* after the GC is put to multi-threaded mode). */
 146 GC_API void GC_CALL GC_set_finalize_on_demand(int);
 147 GC_API int GC_CALL GC_get_finalize_on_demand(void);
 148
 149 GC_API int GC_java_finalization;
 150                         /* Mark objects reachable from finalizable      */
 151                         /* objects in a separate post-pass.  This makes */
 152                         /* it a bit safer to use non-topologically-     */
 153                         /* ordered finalization.  Default value is      */
 154                         /* determined by JAVA_FINALIZATION macro.       */
 155                         /* Enables register_finalizer_unreachable to    */
 156                         /* work correctly.                              */
 157                         /* The setter and getter are unsynchronized, so */
 158                         /* GC_call_with_alloc_lock() is required to     */
 159                         /* avoid data races (if the value is modified   */
 160                         /* after the GC is put to multi-threaded mode). */
 161 GC_API void GC_CALL GC_set_java_finalization(int);
 162 GC_API int GC_CALL GC_get_java_finalization(void);
 163
 164 typedef void (GC_CALLBACK * GC_finalizer_notifier_proc)(void);
 165 GC_API GC_finalizer_notifier_proc GC_finalizer_notifier;
 166                         /* Invoked by the collector when there are      */
 167                         /* objects to be finalized.  Invoked at most    */
 168                         /* once per GC cycle.  Never invoked unless     */
 169                         /* GC_finalize_on_demand is set.                */
 170                         /* Typically this will notify a finalization    */
 171                         /* thread, which will call GC_invoke_finalizers */
 172                         /* in response.  May be 0 (means no notifier).  */
 173                         /* Both the supplied setter and the getter      */
 174                         /* acquire the GC lock (to avoid data races).   */
 175 GC_API void GC_CALL GC_set_finalizer_notifier(GC_finalizer_notifier_proc);
 176 GC_API GC_finalizer_notifier_proc GC_CALL GC_get_finalizer_notifier(void);
 177
 178 GC_API int GC_dont_gc;  /* != 0 ==> Don't collect.  In versions 6.2a1+, */
 179                         /* this overrides explicit GC_gcollect() calls. */
 180                         /* Used as a counter, so that nested enabling   */
 181                         /* and disabling work correctly.  Should        */
 182                         /* normally be updated with GC_enable() and     */
 183                         /* GC_disable() calls.                          */
 184                         /* Direct assignment to GC_dont_gc is           */
 185                         /* deprecated.                                  */
 186
 187 GC_API int GC_dont_expand;
 188                         /* Don't expand the heap unless explicitly      */
 189                         /* requested or forced to.  The setter and      */
 190                         /* getter are unsynchronized, so                */
 191                         /* GC_call_with_alloc_lock() is required to     */
 192                         /* avoid data races (if the value is modified   */
 193                         /* after the GC is put to multi-threaded mode). */
 194 GC_API void GC_CALL GC_set_dont_expand(int);
 195 GC_API int GC_CALL GC_get_dont_expand(void);
 196
 197 GC_API int GC_use_entire_heap;
 198                 /* Causes the non-incremental collector to use the      */
 199                 /* entire heap before collecting.  This was the only    */
 200                 /* option for GC versions < 5.0.  This sometimes        */
 201                 /* results in more large block fragmentation, since     */
 202                 /* very large blocks will tend to get broken up         */
 203                 /* during each GC cycle.  It is likely to result in a   */
 204                 /* larger working set, but lower collection             */
 205                 /* frequencies, and hence fewer instructions executed   */
 206                 /* in the collector.                                    */
 207
 208 GC_API int GC_full_freq;    /* Number of partial collections between    */
 209                             /* full collections.  Matters only if       */
 210                             /* GC_incremental is set.                   */
 211                             /* Full collections are also triggered if   */
 212                             /* the collector detects a substantial      */
 213                             /* increase in the number of in-use heap    */
 214                             /* blocks.  Values in the tens are now      */
 215                             /* perfectly reasonable, unlike for         */
 216                             /* earlier GC versions.                     */
 217                         /* The setter and getter are unsynchronized, so */
 218                         /* GC_call_with_alloc_lock() is required to     */
 219                         /* avoid data races (if the value is modified   */
 220                         /* after the GC is put to multi-threaded mode). */
 221 GC_API void GC_CALL GC_set_full_freq(int);
 222 GC_API int GC_CALL GC_get_full_freq(void);
 223
 224 GC_API GC_word GC_non_gc_bytes;
 225                         /* Bytes not considered candidates for          */
 226                         /* collection.  Used only to control scheduling */
 227                         /* of collections.  Updated by                  */
 228                         /* GC_malloc_uncollectable and GC_free.         */
 229                         /* Wizards only.                                */
 230                         /* The setter and getter are unsynchronized, so */
 231                         /* GC_call_with_alloc_lock() is required to     */
 232                         /* avoid data races (if the value is modified   */
 233                         /* after the GC is put to multi-threaded mode). */
 234 GC_API void GC_CALL GC_set_non_gc_bytes(GC_word);
 235 GC_API GC_word GC_CALL GC_get_non_gc_bytes(void);
 236
 237 GC_API int GC_no_dls;
 238                         /* Don't register dynamic library data segments. */
 239                         /* Wizards only.  Should be used only if the     */
 240                         /* application explicitly registers all roots.   */
 241                         /* In Microsoft Windows environments, this will  */
 242                         /* usually also prevent registration of the      */
 243                         /* main data segment as part of the root set.    */
 244                         /* The setter and getter are unsynchronized, so  */
 245                         /* GC_call_with_alloc_lock() is required to      */
 246                         /* avoid data races (if the value is modified    */
 247                         /* after the GC is put to multi-threaded mode).  */
 248 GC_API void GC_CALL GC_set_no_dls(int);
 249 GC_API int GC_CALL GC_get_no_dls(void);
 250
 251 GC_API GC_word GC_free_space_divisor;
 252                         /* We try to make sure that we allocate at      */
 253                         /* least N/GC_free_space_divisor bytes between  */
 254                         /* collections, where N is twice the number     */
 255                         /* of traced bytes, plus the number of untraced */
 256                         /* bytes (bytes in "atomic" objects), plus      */
 257                         /* a rough estimate of the root set size.       */
 258                         /* N approximates GC tracing work per GC.       */
 259                         /* Initially, GC_free_space_divisor = 3.        */
 260                         /* Increasing its value will use less space     */
 261                         /* but more collection time.  Decreasing it     */
 262                         /* will appreciably decrease collection time    */
 263                         /* at the expense of space.                     */
 264                         /* The setter and getter are unsynchronized, so */
 265                         /* GC_call_with_alloc_lock() is required to     */
 266                         /* avoid data races (if the value is modified   */
 267                         /* after the GC is put to multi-threaded mode). */
 268 GC_API void GC_CALL GC_set_free_space_divisor(GC_word);
 269 GC_API GC_word GC_CALL GC_get_free_space_divisor(void);
 270
 271 GC_API GC_word GC_max_retries;
 272                         /* The maximum number of GCs attempted before   */
 273                         /* reporting out of memory after heap           */
 274                         /* expansion fails.  Initially 0.               */
 275                         /* The setter and getter are unsynchronized, so */
 276                         /* GC_call_with_alloc_lock() is required to     */
 277                         /* avoid data races (if the value is modified   */
 278                         /* after the GC is put to multi-threaded mode). */
 279 GC_API void GC_CALL GC_set_max_retries(GC_word);
 280 GC_API GC_word GC_CALL GC_get_max_retries(void);
 281
 282
 283 GC_API char *GC_stackbottom;    /* Cool end of user stack.              */
 284                                 /* May be set in the client prior to    */
 285                                 /* calling any GC_ routines.  This      */
 286                                 /* avoids some overhead, and            */
 287                                 /* potentially some signals that can    */
 288                                 /* confuse debuggers.  Otherwise the    */
 289                                 /* collector attempts to set it         */
 290                                 /* automatically.                       */
 291                                 /* For multithreaded code, this is the  */
 292                                 /* cold end of the stack for the        */
 293                                 /* primordial thread.                   */
 294
 295 GC_API int GC_dont_precollect;  /* Don't collect as part of             */
 296                                 /* initialization.  Should be set only  */
 297                                 /* if the client wants a chance to      */
 298                                 /* manually initialize the root set     */
 299                                 /* before the first collection.         */
 300                                 /* Interferes with blacklisting.        */
 301                                 /* Wizards only.                        */
 302                         /* The setter and getter are unsynchronized, so */
 303                         /* GC_call_with_alloc_lock() is required to     */
 304                         /* avoid data races (if the value is modified   */
 305                         /* after the GC is put to multi-threaded mode). */
 306 GC_API void GC_CALL GC_set_dont_precollect(int);
 307 GC_API int GC_CALL GC_get_dont_precollect(void);
 308
 309 GC_API unsigned long GC_time_limit;
 310                                /* If incremental collection is enabled, */
 311                                /* We try to terminate collections       */
 312                                /* after this many milliseconds.  Not a  */
 313                                /* hard time bound.  Setting this to     */
 314                                /* GC_TIME_UNLIMITED will essentially    */
 315                                /* disable incremental collection while  */
 316                                /* leaving generational collection       */
 317                                /* enabled.                              */
 318 #define GC_TIME_UNLIMITED 999999
 319                                /* Setting GC_time_limit to this value   */
 320                                /* will disable the "pause time exceeded"*/
 321                                /* tests.                                */
 322                         /* The setter and getter are unsynchronized, so */
 323                         /* GC_call_with_alloc_lock() is required to     */
 324                         /* avoid data races (if the value is modified   */
 325                         /* after the GC is put to multi-threaded mode). */
 326 GC_API void GC_CALL GC_set_time_limit(unsigned long);
 327 GC_API unsigned long GC_CALL GC_get_time_limit(void);
 328
 329 /* Public procedures */
 330
 331 /* Initialize the collector.  Portable clients should call GC_INIT()    */
 332 /* from the main program instead.                                       */
 333 GC_API void GC_CALL GC_init(void);
 334
 335 /* General purpose allocation routines, with roughly malloc calling     */
 336 /* conv.  The atomic versions promise that no relevant pointers are     */
 337 /* contained in the object.  The non-atomic versions guarantee that the */
 338 /* new object is cleared.  GC_malloc_stubborn promises that no changes  */
 339 /* to the object will occur after GC_end_stubborn_change has been       */
 340 /* called on the result of GC_malloc_stubborn.  GC_malloc_uncollectable */
 341 /* allocates an object that is scanned for pointers to collectable      */
 342 /* objects, but is not itself collectable.  The object is scanned even  */
 343 /* if it does not appear to be reachable.  GC_malloc_uncollectable and  */
 344 /* GC_free called on the resulting object implicitly update             */
 345 /* GC_non_gc_bytes appropriately.                                       */
 346 /* Note that the GC_malloc_stubborn support doesn't really exist        */
 347 /* anymore.  MANUAL_VDB provides comparable functionality.              */
 348 GC_API void * GC_CALL GC_malloc(size_t /* size_in_bytes */)
 349                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 350 GC_API void * GC_CALL GC_malloc_atomic(size_t /* size_in_bytes */)
 351                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 352 GC_API char * GC_CALL GC_strdup(const char *) GC_ATTR_MALLOC;
 353 GC_API void * GC_CALL GC_malloc_uncollectable(size_t /* size_in_bytes */)
 354                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 355 GC_API void * GC_CALL GC_malloc_stubborn(size_t /* size_in_bytes */)
 356                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 357
 358 /* GC_memalign() is not well tested.                                    */
 359 GC_API void * GC_CALL GC_memalign(size_t /* align */, size_t /* lb */)
 360                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(2);
 361
 362 /* The following is only defined if the library has been suitably       */
 363 /* compiled:                                                            */
 364 GC_API void * GC_CALL GC_malloc_atomic_uncollectable(
 365                                                 size_t /* size_in_bytes */)
 366                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 367
 368 /* Explicitly deallocate an object.  Dangerous if used incorrectly.     */
 369 /* Requires a pointer to the base of an object.                         */
 370 /* If the argument is stubborn, it should not be changeable when freed. */
 371 /* An object should not be enabled for finalization when it is          */
 372 /* explicitly deallocated.                                              */
 373 /* GC_free(0) is a no-op, as required by ANSI C for free.               */
 374 GC_API void GC_CALL GC_free(void *);
 375
 376 /* Stubborn objects may be changed only if the collector is explicitly  */
 377 /* informed.  The collector is implicitly informed of coming change     */
 378 /* when such an object is first allocated.  The following routines      */
 379 /* inform the collector that an object will no longer be changed, or    */
 380 /* that it will once again be changed.  Only non-NULL pointer stores    */
 381 /* into the object are considered to be changes.  The argument to       */
 382 /* GC_end_stubborn_change must be exactly the value returned by         */
 383 /* GC_malloc_stubborn or passed to GC_change_stubborn.  (In the second  */
 384 /* case, it may be an interior pointer within 512 bytes of the          */
 385 /* beginning of the objects.)  There is a performance penalty for       */
 386 /* allowing more than one stubborn object to be changed at once, but it */
 387 /* is acceptable to do so.  The same applies to dropping stubborn       */
 388 /* objects that are still changeable.                                   */
 389 GC_API void GC_CALL GC_change_stubborn(void *);
 390 GC_API void GC_CALL GC_end_stubborn_change(void *);
 391
 392 /* Return a pointer to the base (lowest address) of an object given     */
 393 /* a pointer to a location within the object.                           */
 394 /* I.e. map an interior pointer to the corresponding bas pointer.       */
 395 /* Note that with debugging allocation, this returns a pointer to the   */
 396 /* actual base of the object, i.e. the debug information, not to        */
 397 /* the base of the user object.                                         */
 398 /* Return 0 if displaced_pointer doesn't point to within a valid        */
 399 /* object.                                                              */
 400 /* Note that a deallocated object in the garbage collected heap         */
 401 /* may be considered valid, even if it has been deallocated with        */
 402 /* GC_free.                                                             */
 403 GC_API void * GC_CALL GC_base(void * /* displaced_pointer */);
 404
 405 /* Given a pointer to the base of an object, return its size in bytes.  */
 406 /* The returned size may be slightly larger than what was originally    */
 407 /* requested.                                                           */
 408 GC_API size_t GC_CALL GC_size(const void * /* object_addr */);
 409
 410 /* For compatibility with C library.  This is occasionally faster than  */
 411 /* a malloc followed by a bcopy.  But if you rely on that, either here  */
 412 /* or with the standard C library, your code is broken.  In my          */
 413 /* opinion, it shouldn't have been invented, but now we're stuck. -HB   */
 414 /* The resulting object has the same kind as the original.              */
 415 /* If the argument is stubborn, the result will have changes enabled.   */
 416 /* It is an error to have changes enabled for the original object.      */
 417 /* Follows ANSI conventions for NULL old_object.                        */
 418 GC_API void * GC_CALL GC_realloc(void * /* old_object */,
 419                                  size_t /* new_size_in_bytes */)
 420                         /* 'realloc' attr */ GC_ATTR_ALLOC_SIZE(2);
 421
 422 /* Explicitly increase the heap size.   */
 423 /* Returns 0 on failure, 1 on success.  */
 424 GC_API int GC_CALL GC_expand_hp(size_t /* number_of_bytes */);
 425
 426 /* Limit the heap size to n bytes.  Useful when you're debugging,       */
 427 /* especially on systems that don't handle running out of memory well.  */
 428 /* n == 0 ==> unbounded.  This is the default.                          */
 429 GC_API void GC_CALL GC_set_max_heap_size(GC_word /* n */);
 430
 431 /* Inform the collector that a certain section of statically allocated  */
 432 /* memory contains no pointers to garbage collected memory.  Thus it    */
 433 /* need not be scanned.  This is sometimes important if the application */
 434 /* maps large read/write files into the address space, which could be   */
 435 /* mistaken for dynamic library data segments on some systems.          */
 436 /* The section (referred to by low_address) must be pointer-aligned.    */
 437 /* low_address must not be greater than high_address_plus_1.            */
 438 GC_API void GC_CALL GC_exclude_static_roots(void * /* low_address */,
 439                                         void * /* high_address_plus_1 */);
 440
 441 /* Clear the set of root segments.  Wizards only.                       */
 442 GC_API void GC_CALL GC_clear_roots(void);
 443
 444 /* Add a root segment.  Wizards only.                                   */
 445 /* The segment (referred to by low_address) must be pointer-aligned.    */
 446 /* low_address must not be greater than high_address_plus_1.            */
 447 GC_API void GC_CALL GC_add_roots(void * /* low_address */,
 448                                  void * /* high_address_plus_1 */);
 449
 450 /* Remove a root segment.  Wizards only.                                */
 451 /* May be unimplemented on some platforms.                              */
 452 GC_API void GC_CALL GC_remove_roots(void * /* low_address */,
 453                                     void * /* high_address_plus_1 */);
 454
 455 /* Add a displacement to the set of those considered valid by the       */
 456 /* collector.  GC_register_displacement(n) means that if p was returned */
 457 /* by GC_malloc, then (char *)p + n will be considered to be a valid    */
 458 /* pointer to p.  N must be small and less than the size of p.          */
 459 /* (All pointers to the interior of objects from the stack are          */
 460 /* considered valid in any case.  This applies to heap objects and      */
 461 /* static data.)                                                        */
 462 /* Preferably, this should be called before any other GC procedures.    */
 463 /* Calling it later adds to the probability of excess memory            */
 464 /* retention.                                                           */
 465 /* This is a no-op if the collector has recognition of                  */
 466 /* arbitrary interior pointers enabled, which is now the default.       */
 467 GC_API void GC_CALL GC_register_displacement(size_t /* n */);
 468
 469 /* The following version should be used if any debugging allocation is  */
 470 /* being done.                                                          */
 471 GC_API void GC_CALL GC_debug_register_displacement(size_t /* n */);
 472
 473 /* Explicitly trigger a full, world-stop collection.    */
 474 GC_API void GC_CALL GC_gcollect(void);
 475
 476 /* Same as above but ignores the default stop_func setting and tries to */
 477 /* unmap as much memory as possible (regardless of the corresponding    */
 478 /* switch setting).  The recommended usage: on receiving a system       */
 479 /* low-memory event; before retrying a system call failed because of    */
 480 /* the system is running out of resources.                              */
 481 GC_API void GC_CALL GC_gcollect_and_unmap(void);
 482
 483 /* Trigger a full world-stopped collection.  Abort the collection if    */
 484 /* and when stop_func returns a nonzero value.  Stop_func will be       */
 485 /* called frequently, and should be reasonably fast.  (stop_func is     */
 486 /* called with the allocation lock held and the world might be stopped; */
 487 /* it's not allowed for stop_func to manipulate pointers to the garbage */
 488 /* collected heap or call most of GC functions.)  This works even       */
 489 /* if virtual dirty bits, and hence incremental collection is not       */
 490 /* available for this architecture.  Collections can be aborted faster  */
 491 /* than normal pause times for incremental collection.  However,        */
 492 /* aborted collections do no useful work; the next collection needs     */
 493 /* to start from the beginning.  stop_func must not be 0.               */
 494 /* GC_try_to_collect() returns 0 if the collection was aborted (or the  */
 495 /* collections are disabled), 1 if it succeeded.                        */
 496 typedef int (GC_CALLBACK * GC_stop_func)(void);
 497 GC_API int GC_CALL GC_try_to_collect(GC_stop_func /* stop_func */);
 498
 499 /* Set and get the default stop_func.  The default stop_func is used by */
 500 /* GC_gcollect() and by implicitly trigged collections (except for the  */
 501 /* case when handling out of memory).  Must not be 0.                   */
 502 GC_API void GC_CALL GC_set_stop_func(GC_stop_func /* stop_func */);
 503 GC_API GC_stop_func GC_CALL GC_get_stop_func(void);
 504
 505 /* Return the number of bytes in the heap.  Excludes collector private  */
 506 /* data structures.  Excludes the unmapped memory (retuned to the OS).  */
 507 /* Includes empty blocks and fragmentation loss.  Includes some pages   */
 508 /* that were allocated but never written.                               */
 509 GC_API size_t GC_CALL GC_get_heap_size(void);
 510
 511 /* Return a lower bound on the number of free bytes in the heap         */
 512 /* (excluding the unmapped memory space).                               */
 513 GC_API size_t GC_CALL GC_get_free_bytes(void);
 514
 515 /* Return the size (in bytes) of the unmapped memory (which is returned */
 516 /* to the OS but could be remapped back by the collector later unless   */
 517 /* the OS runs out of system/virtual memory).                           */
 518 GC_API size_t GC_CALL GC_get_unmapped_bytes(void);
 519
 520 /* Return the number of bytes allocated since the last collection.      */
 521 GC_API size_t GC_CALL GC_get_bytes_since_gc(void);
 522
 523 /* Return the total number of bytes allocated in this process.          */
 524 /* Never decreases, except due to wrapping.                             */
 525 GC_API size_t GC_CALL GC_get_total_bytes(void);
 526
 527 /* Return the signal number used by the garbage collector to suspend    */
 528 /* threads on POSIX systems.  Return -1 otherwise.  Exported only if    */
 529 /* the library has been compiled with threads support (GC_THREADS).     */
 530 GC_API int GC_CALL GC_get_suspend_signal(void);
 531
 532 /* Disable garbage collection.  Even GC_gcollect calls will be          */
 533 /* ineffective.                                                         */
 534 GC_API void GC_CALL GC_disable(void);
 535
 536 /* Re-enable garbage collection.  GC_disable() and GC_enable() calls    */
 537 /* nest.  Garbage collection is enabled if the number of calls to both  */
 538 /* both functions is equal.                                             */
 539 GC_API void GC_CALL GC_enable(void);
 540
 541 /* Enable incremental/generational collection.  Not advisable unless    */
 542 /* dirty bits are available or most heap objects are pointer-free       */
 543 /* (atomic) or immutable.  Don't use in leak finding mode.  Ignored if  */
 544 /* GC_dont_gc is true.  Only the generational piece of this is          */
 545 /* functional if GC_parallel is TRUE or if GC_time_limit is             */
 546 /* GC_TIME_UNLIMITED.  Causes thread-local variant of GC_gcj_malloc()   */
 547 /* to revert to locked allocation.  Must be called before any such      */
 548 /* GC_gcj_malloc() calls.  For best performance, should be called as    */
 549 /* early as possible.  On some platforms, calling it later may have     */
 550 /* adverse effects.                                                     */
 551 /* Safe to call before GC_INIT().  Includes a  GC_init() call.          */
 552 GC_API void GC_CALL GC_enable_incremental(void);
 553
 554 /* Does incremental mode write-protect pages?  Returns zero or  */
 555 /* more of the following, or'ed together:                       */
 556 #define GC_PROTECTS_POINTER_HEAP  1 /* May protect non-atomic objs.     */
 557 #define GC_PROTECTS_PTRFREE_HEAP  2
 558 #define GC_PROTECTS_STATIC_DATA   4 /* Currently never.                 */
 559 #define GC_PROTECTS_STACK         8 /* Probably impractical.            */
 560
 561 #define GC_PROTECTS_NONE 0
 562 GC_API int GC_CALL GC_incremental_protection_needs(void);
 563
 564 /* Perform some garbage collection work, if appropriate.        */
 565 /* Return 0 if there is no more work to be done.                */
 566 /* Typically performs an amount of work corresponding roughly   */
 567 /* to marking from one page.  May do more work if further       */
 568 /* progress requires it, e.g. if incremental collection is      */
 569 /* disabled.  It is reasonable to call this in a wait loop      */
 570 /* until it returns 0.                                          */
 571 GC_API int GC_CALL GC_collect_a_little(void);
 572
 573 /* Allocate an object of size lb bytes.  The client guarantees that     */
 574 /* as long as the object is live, it will be referenced by a pointer    */
 575 /* that points to somewhere within the first 256 bytes of the object.   */
 576 /* (This should normally be declared volatile to prevent the compiler   */
 577 /* from invalidating this assertion.)  This routine is only useful      */
 578 /* if a large array is being allocated.  It reduces the chance of       */
 579 /* accidentally retaining such an array as a result of scanning an      */
 580 /* integer that happens to be an address inside the array.  (Actually,  */
 581 /* it reduces the chance of the allocator not finding space for such    */
 582 /* an array, since it will try hard to avoid introducing such a false   */
 583 /* reference.)  On a SunOS 4.X or MS Windows system this is recommended */
 584 /* for arrays likely to be larger than 100K or so.  For other systems,  */
 585 /* or if the collector is not configured to recognize all interior      */
 586 /* pointers, the threshold is normally much higher.                     */
 587 GC_API void * GC_CALL GC_malloc_ignore_off_page(size_t /* lb */)
 588                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 589 GC_API void * GC_CALL GC_malloc_atomic_ignore_off_page(size_t /* lb */)
 590                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 591
 592 #if defined(__sgi) && !defined(__GNUC__) && _COMPILER_VERSION >= 720
 593 # define GC_ADD_CALLER
 594 # define GC_RETURN_ADDR (GC_word)__return_address
 595 #endif
 596
 597 #if defined(__linux__) || defined(__GLIBC__)
 598 # include <features.h>
 599 # if (__GLIBC__ == 2 && __GLIBC_MINOR__ >= 1 || __GLIBC__ > 2) \
 600         && !defined(__ia64__) && !defined(__UCLIBC__) \
 601         && !defined(GC_HAVE_BUILTIN_BACKTRACE)
 602 #   define GC_HAVE_BUILTIN_BACKTRACE
 603 # endif
 604 # if defined(__i386__) || defined(__x86_64__)
 605 #   define GC_CAN_SAVE_CALL_STACKS
 606 # endif
 607 #endif
 608
 609 #if defined(_MSC_VER) && _MSC_VER >= 1200 /* version 12.0+ (MSVC 6.0+) */ \
 610         && !defined(_AMD64_) && !defined(GC_HAVE_NO_BUILTIN_BACKTRACE) \
 611         && !defined(_WIN32_WCE) && !defined(GC_HAVE_BUILTIN_BACKTRACE)
 612 # define GC_HAVE_BUILTIN_BACKTRACE
 613 #endif
 614
 615 #if defined(GC_HAVE_BUILTIN_BACKTRACE) && !defined(GC_CAN_SAVE_CALL_STACKS)
 616 # define GC_CAN_SAVE_CALL_STACKS
 617 #endif
 618
 619 #if defined(__sparc__)
 620 # define GC_CAN_SAVE_CALL_STACKS
 621 #endif
 622
 623 /* If we're on an a platform on which we can't save call stacks, but    */
 624 /* gcc is normally used, we go ahead and define GC_ADD_CALLER.          */
 625 /* We make this decision independent of whether gcc is actually being   */
 626 /* used, in order to keep the interface consistent, and allow mixing    */
 627 /* of compilers.                                                        */
 628 /* This may also be desirable if it is possible but expensive to        */
 629 /* retrieve the call chain.                                             */
 630 #if (defined(__linux__) || defined(__NetBSD__) || defined(__OpenBSD__) \
 631      || defined(__FreeBSD__) || defined(__DragonFly__)) \
 632     && !defined(GC_CAN_SAVE_CALL_STACKS)
 633 # define GC_ADD_CALLER
 634 # if __GNUC__ >= 3 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 95)
 635     /* gcc knows how to retrieve return address, but we don't know */
 636     /* how to generate call stacks.                                */
 637 #   define GC_RETURN_ADDR (GC_word)__builtin_return_address(0)
 638 # else
 639     /* Just pass 0 for gcc compatibility. */
 640 #   define GC_RETURN_ADDR 0
 641 # endif
 642 #endif
 643
 644 #ifdef GC_ADD_CALLER
 645 # define GC_EXTRAS GC_RETURN_ADDR, __FILE__, __LINE__
 646 # define GC_EXTRA_PARAMS GC_word ra, const char * s, int i
 647 #else
 648 # define GC_EXTRAS __FILE__, __LINE__
 649 # define GC_EXTRA_PARAMS const char * s, int i
 650 #endif
 651
 652 /* Debugging (annotated) allocation.  GC_gcollect will check            */
 653 /* objects allocated in this way for overwrites, etc.                   */
 654 GC_API void * GC_CALL GC_debug_malloc(size_t /* size_in_bytes */,
 655                                       GC_EXTRA_PARAMS)
 656                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 657 GC_API void * GC_CALL GC_debug_malloc_atomic(size_t /* size_in_bytes */,
 658                                              GC_EXTRA_PARAMS)
 659                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 660 GC_API char * GC_CALL GC_debug_strdup(const char *,
 661                                       GC_EXTRA_PARAMS) GC_ATTR_MALLOC;
 662 GC_API void * GC_CALL GC_debug_malloc_uncollectable(
 663                         size_t /* size_in_bytes */, GC_EXTRA_PARAMS)
 664                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 665 GC_API void * GC_CALL GC_debug_malloc_stubborn(size_t /* size_in_bytes */,
 666                                                GC_EXTRA_PARAMS)
 667                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 668 GC_API void * GC_CALL GC_debug_malloc_ignore_off_page(
 669                         size_t /* size_in_bytes */, GC_EXTRA_PARAMS)
 670                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 671 GC_API void * GC_CALL GC_debug_malloc_atomic_ignore_off_page(
 672                         size_t /* size_in_bytes */, GC_EXTRA_PARAMS)
 673                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 674 GC_API void GC_CALL GC_debug_free(void *);
 675 GC_API void * GC_CALL GC_debug_realloc(void * /* old_object */,
 676                         size_t /* new_size_in_bytes */, GC_EXTRA_PARAMS)
 677                         /* 'realloc' attr */ GC_ATTR_ALLOC_SIZE(2);
 678 GC_API void GC_CALL GC_debug_change_stubborn(void *);
 679 GC_API void GC_CALL GC_debug_end_stubborn_change(void *);
 680
 681 /* Routines that allocate objects with debug information (like the      */
 682 /* above), but just fill in dummy file and line number information.     */
 683 /* Thus they can serve as drop-in malloc/realloc replacements.  This    */
 684 /* can be useful for two reasons:                                       */
 685 /* 1) It allows the collector to be built with DBG_HDRS_ALL defined     */
 686 /*    even if some allocation calls come from 3rd party libraries       */
 687 /*    that can't be recompiled.                                         */
 688 /* 2) On some platforms, the file and line information is redundant,    */
 689 /*    since it can be reconstructed from a stack trace.  On such        */
 690 /*    platforms it may be more convenient not to recompile, e.g. for    */
 691 /*    leak detection.  This can be accomplished by instructing the      */
 692 /*    linker to replace malloc/realloc with these.                      */
 693 GC_API void * GC_CALL GC_debug_malloc_replacement(size_t /* size_in_bytes */)
 694                         GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1);
 695 GC_API void * GC_CALL GC_debug_realloc_replacement(void * /* object_addr */,
 696                                                    size_t /* size_in_bytes */)
 697                         /* 'realloc' attr */ GC_ATTR_ALLOC_SIZE(2);
 698
 699 #ifdef GC_DEBUG
 700 # define GC_MALLOC(sz) GC_debug_malloc(sz, GC_EXTRAS)
 701 # define GC_MALLOC_ATOMIC(sz) GC_debug_malloc_atomic(sz, GC_EXTRAS)
 702 # define GC_STRDUP(s) GC_debug_strdup((s), GC_EXTRAS)
 703 # define GC_MALLOC_UNCOLLECTABLE(sz) \
 704                         GC_debug_malloc_uncollectable(sz, GC_EXTRAS)
 705 # define GC_MALLOC_IGNORE_OFF_PAGE(sz) \
 706                         GC_debug_malloc_ignore_off_page(sz, GC_EXTRAS)
 707 # define GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(sz) \
 708                         GC_debug_malloc_atomic_ignore_off_page(sz, GC_EXTRAS)
 709 # define GC_REALLOC(old, sz) GC_debug_realloc(old, sz, GC_EXTRAS)
 710 # define GC_FREE(p) GC_debug_free(p)
 711 # define GC_REGISTER_FINALIZER(p, f, d, of, od) \
 712       GC_debug_register_finalizer(p, f, d, of, od)
 713 # define GC_REGISTER_FINALIZER_IGNORE_SELF(p, f, d, of, od) \
 714       GC_debug_register_finalizer_ignore_self(p, f, d, of, od)
 715 # define GC_REGISTER_FINALIZER_NO_ORDER(p, f, d, of, od) \
 716       GC_debug_register_finalizer_no_order(p, f, d, of, od)
 717 # define GC_REGISTER_FINALIZER_UNREACHABLE(p, f, d, of, od) \
 718       GC_debug_register_finalizer_unreachable(p, f, d, of, od)
 719 # define GC_MALLOC_STUBBORN(sz) GC_debug_malloc_stubborn(sz, GC_EXTRAS);
 720 # define GC_CHANGE_STUBBORN(p) GC_debug_change_stubborn(p)
 721 # define GC_END_STUBBORN_CHANGE(p) GC_debug_end_stubborn_change(p)
 722 # define GC_GENERAL_REGISTER_DISAPPEARING_LINK(link, obj) \
 723       GC_general_register_disappearing_link(link, GC_base(obj))
 724 # define GC_REGISTER_DISPLACEMENT(n) GC_debug_register_displacement(n)
 725 #else
 726 # define GC_MALLOC(sz) GC_malloc(sz)
 727 # define GC_MALLOC_ATOMIC(sz) GC_malloc_atomic(sz)
 728 # define GC_STRDUP(s) GC_strdup(s)
 729 # define GC_MALLOC_UNCOLLECTABLE(sz) GC_malloc_uncollectable(sz)
 730 # define GC_MALLOC_IGNORE_OFF_PAGE(sz) \
 731                         GC_malloc_ignore_off_page(sz)
 732 # define GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(sz) \
 733                         GC_malloc_atomic_ignore_off_page(sz)
 734 # define GC_REALLOC(old, sz) GC_realloc(old, sz)
 735 # define GC_FREE(p) GC_free(p)
 736 # define GC_REGISTER_FINALIZER(p, f, d, of, od) \
 737       GC_register_finalizer(p, f, d, of, od)
 738 # define GC_REGISTER_FINALIZER_IGNORE_SELF(p, f, d, of, od) \
 739       GC_register_finalizer_ignore_self(p, f, d, of, od)
 740 # define GC_REGISTER_FINALIZER_NO_ORDER(p, f, d, of, od) \
 741       GC_register_finalizer_no_order(p, f, d, of, od)
 742 # define GC_REGISTER_FINALIZER_UNREACHABLE(p, f, d, of, od) \
 743       GC_register_finalizer_unreachable(p, f, d, of, od)
 744 # define GC_MALLOC_STUBBORN(sz) GC_malloc_stubborn(sz)
 745 # define GC_CHANGE_STUBBORN(p) GC_change_stubborn(p)
 746 # define GC_END_STUBBORN_CHANGE(p) GC_end_stubborn_change(p)
 747 # define GC_GENERAL_REGISTER_DISAPPEARING_LINK(link, obj) \
 748       GC_general_register_disappearing_link(link, obj)
 749 # define GC_REGISTER_DISPLACEMENT(n) GC_register_displacement(n)
 750 #endif
 751
 752 /* The following are included because they are often convenient, and    */
 753 /* reduce the chance for a misspecified size argument.  But calls may   */
 754 /* expand to something syntactically incorrect if t is a complicated    */
 755 /* type expression.                                                     */
 756 #define GC_NEW(t) (t *)GC_MALLOC(sizeof (t))
 757 #define GC_NEW_ATOMIC(t) (t *)GC_MALLOC_ATOMIC(sizeof (t))
 758 #define GC_NEW_STUBBORN(t) (t *)GC_MALLOC_STUBBORN(sizeof (t))
 759 #define GC_NEW_UNCOLLECTABLE(t) (t *)GC_MALLOC_UNCOLLECTABLE(sizeof (t))
 760
 761 /* Finalization.  Some of these primitives are grossly unsafe.          */
 762 /* The idea is to make them both cheap, and sufficient to build         */
 763 /* a safer layer, closer to Modula-3, Java, or PCedar finalization.     */
 764 /* The interface represents my conclusions from a long discussion       */
 765 /* with Alan Demers, Dan Greene, Carl Hauser, Barry Hayes,              */
 766 /* Christian Jacobi, and Russ Atkinson.  It's not perfect, and          */
 767 /* probably nobody else agrees with it.     Hans-J. Boehm  3/13/92      */
 768 typedef void (GC_CALLBACK * GC_finalization_proc)(void * /* obj */,
 769                                                   void * /* client_data */);
 770
 771 GC_API void GC_CALL GC_register_finalizer(void * /* obj */,
 772                         GC_finalization_proc /* fn */, void * /* cd */,
 773                         GC_finalization_proc * /* ofn */, void ** /* ocd */);
 774 GC_API void GC_CALL GC_debug_register_finalizer(void * /* obj */,
 775                         GC_finalization_proc /* fn */, void * /* cd */,
 776                         GC_finalization_proc * /* ofn */, void ** /* ocd */);
 777         /* When obj is no longer accessible, invoke             */
 778         /* (*fn)(obj, cd).  If a and b are inaccessible, and    */
 779         /* a points to b (after disappearing links have been    */
 780         /* made to disappear), then only a will be              */
 781         /* finalized.  (If this does not create any new         */
 782         /* pointers to b, then b will be finalized after the    */
 783         /* next collection.)  Any finalizable object that       */
 784         /* is reachable from itself by following one or more    */
 785         /* pointers will not be finalized (or collected).       */
 786         /* Thus cycles involving finalizable objects should     */
 787         /* be avoided, or broken by disappearing links.         */
 788         /* All but the last finalizer registered for an object  */
 789         /* is ignored.                                          */
 790         /* Finalization may be removed by passing 0 as fn.      */
 791         /* Finalizers are implicitly unregistered when they are */
 792         /* enqueued for finalization (i.e. become ready to be   */
 793         /* finalized).                                          */
 794         /* The old finalizer and client data are stored in      */
 795         /* *ofn and *ocd.  (ofn and/or ocd may be NULL.         */
 796         /* The allocation lock is held while *ofn and *ocd are  */
 797         /* updated.  In case of error (no memory to register    */
 798         /* new finalizer), *ofn and *ocd remain unchanged.)     */
 799         /* Fn is never invoked on an accessible object,         */
 800         /* provided hidden pointers are converted to real       */
 801         /* pointers only if the allocation lock is held, and    */
 802         /* such conversions are not performed by finalization   */
 803         /* routines.                                            */
 804         /* If GC_register_finalizer is aborted as a result of   */
 805         /* a signal, the object may be left with no             */
 806         /* finalization, even if neither the old nor new        */
 807         /* finalizer were NULL.                                 */
 808         /* Obj should be the starting address of an object      */
 809         /* allocated by GC_malloc or friends. Obj may also be   */
 810         /* NULL or point to something outside GC heap (in this  */
 811         /* case, fn is ignored, *ofn and *ocd are set to NULL). */
 812         /* Note that any garbage collectable object referenced  */
 813         /* by cd will be considered accessible until the        */
 814         /* finalizer is invoked.                                */
 815
 816 /* Another versions of the above follow.  It ignores            */
 817 /* self-cycles, i.e. pointers from a finalizable object to      */
 818 /* itself.  There is a stylistic argument that this is wrong,   */
 819 /* but it's unavoidable for C++, since the compiler may         */
 820 /* silently introduce these.  It's also benign in that specific */
 821 /* case.  And it helps if finalizable objects are split to      */
 822 /* avoid cycles.                                                */
 823 /* Note that cd will still be viewed as accessible, even if it  */
 824 /* refers to the object itself.                                 */
 825 GC_API void GC_CALL GC_register_finalizer_ignore_self(void * /* obj */,
 826                         GC_finalization_proc /* fn */, void * /* cd */,
 827                         GC_finalization_proc * /* ofn */, void ** /* ocd */);
 828 GC_API void GC_CALL GC_debug_register_finalizer_ignore_self(void * /* obj */,
 829                         GC_finalization_proc /* fn */, void * /* cd */,
 830                         GC_finalization_proc * /* ofn */, void ** /* ocd */);
 831
 832 /* Another version of the above.  It ignores all cycles.        */
 833 /* It should probably only be used by Java implementations.     */
 834 /* Note that cd will still be viewed as accessible, even if it  */
 835 /* refers to the object itself.                                 */
 836 GC_API void GC_CALL GC_register_finalizer_no_order(void * /* obj */,
 837                         GC_finalization_proc /* fn */, void * /* cd */,
 838                         GC_finalization_proc * /* ofn */, void ** /* ocd */);
 839 GC_API void GC_CALL GC_debug_register_finalizer_no_order(void * /* obj */,
 840                         GC_finalization_proc /* fn */, void * /* cd */,
 841                         GC_finalization_proc * /* ofn */, void ** /* ocd */);
 842
 843 /* This is a special finalizer that is useful when an object's  */
 844 /* finalizer must be run when the object is known to be no      */
 845 /* longer reachable, not even from other finalizable objects.   */
 846 /* It behaves like "normal" finalization, except that the       */
 847 /* finalizer is not run while the object is reachable from      */
 848 /* other objects specifying unordered finalization.             */
 849 /* Effectively it allows an object referenced, possibly         */
 850 /* indirectly, from an unordered finalizable object to override */
 851 /* the unordered finalization request.                          */
 852 /* This can be used in combination with finalizer_no_order so   */
 853 /* as to release resources that must not be released while an   */
 854 /* object can still be brought back to life by other            */
 855 /* finalizers.                                                  */
 856 /* Only works if GC_java_finalization is set.  Probably only    */
 857 /* of interest when implementing a language that requires       */
 858 /* unordered finalization (e.g. Java, C#).                      */
 859 GC_API void GC_CALL GC_register_finalizer_unreachable(void * /* obj */,
 860                         GC_finalization_proc /* fn */, void * /* cd */,
 861                         GC_finalization_proc * /* ofn */, void ** /* ocd */);
 862 GC_API void GC_CALL GC_debug_register_finalizer_unreachable(void * /* obj */,
 863                         GC_finalization_proc /* fn */, void * /* cd */,
 864                         GC_finalization_proc * /* ofn */, void ** /* ocd */);
 865
 866 #define GC_NO_MEMORY 2  /* Failure due to lack of memory.       */
 867
 868 /* The following routine may be used to break cycles between    */
 869 /* finalizable objects, thus causing cyclic finalizable         */
 870 /* objects to be finalized in the correct order.  Standard      */
 871 /* use involves calling GC_register_disappearing_link(&p),      */
 872 /* where p is a pointer that is not followed by finalization    */
 873 /* code, and should not be considered in determining            */
 874 /* finalization order.                                          */
 875 GC_API int GC_CALL GC_register_disappearing_link(void ** /* link */);
 876         /* Link should point to a field of a heap allocated     */
 877         /* object obj.  *link will be cleared when obj is       */
 878         /* found to be inaccessible.  This happens BEFORE any   */
 879         /* finalization code is invoked, and BEFORE any         */
 880         /* decisions about finalization order are made.         */
 881         /* This is useful in telling the finalizer that         */
 882         /* some pointers are not essential for proper           */
 883         /* finalization.  This may avoid finalization cycles.   */
 884         /* Note that obj may be resurrected by another          */
 885         /* finalizer, and thus the clearing of *link may        */
 886         /* be visible to non-finalization code.                 */
 887         /* There's an argument that an arbitrary action should  */
 888         /* be allowed here, instead of just clearing a pointer. */
 889         /* But this causes problems if that action alters, or   */
 890         /* examines connectivity.  Returns GC_DUPLICATE if link */
 891         /* was already registered, GC_SUCCESS if registration   */
 892         /* succeeded, GC_NO_MEMORY if it failed for lack of     */
 893         /* memory, and GC_oom_fn did not handle the problem.    */
 894         /* Only exists for backward compatibility.  See below:  */
 895
 896 GC_API int GC_CALL GC_general_register_disappearing_link(void ** /* link */,
 897                                                          void * /* obj */);
 898         /* A slight generalization of the above. *link is       */
 899         /* cleared when obj first becomes inaccessible.  This   */
 900         /* can be used to implement weak pointers easily and    */
 901         /* safely. Typically link will point to a location      */
 902         /* holding a disguised pointer to obj.  (A pointer      */
 903         /* inside an "atomic" object is effectively disguised.) */
 904         /* In this way, weak pointers are broken before any     */
 905         /* object reachable from them gets finalized.           */
 906         /* Each link may be registered only with one obj value, */
 907         /* i.e. all objects but the last one (link registered   */
 908         /* with) are ignored.  This was added after a long      */
 909         /* email discussion with John Ellis.                    */
 910         /* link must be non-NULL (and be properly aligned).     */
 911         /* obj must be a pointer to the first word of an object */
 912         /* allocated by GC_malloc or friends.  It is unsafe to  */
 913         /* explicitly deallocate the object containing link.    */
 914         /* Explicit deallocation of obj may or may not cause    */
 915         /* link to eventually be cleared.                       */
 916         /* This function can be used to implement certain types */
 917         /* of weak pointers.  Note, however, this generally     */
 918         /* requires that the allocation lock is held (see       */
 919         /* GC_call_with_alloc_lock() below) when the disguised  */
 920         /* pointer is accessed.  Otherwise a strong pointer     */
 921         /* could be recreated between the time the collector    */
 922         /* decides to reclaim the object and the link is        */
 923         /* cleared.  Returns GC_SUCCESS if registration         */
 924         /* succeeded (a new link is registered), GC_DUPLICATE   */
 925         /* if link was already registered (with some object),   */
 926         /* GC_NO_MEMORY if registration failed for lack of      */
 927         /* memory (and GC_oom_fn did not handle the problem).   */
 928
 929 GC_API int GC_CALL GC_unregister_disappearing_link(void ** /* link */);
 930         /* Undoes a registration by either of the above two     */
 931         /* routines.  Returns 0 if link was not actually        */
 932         /* registered (otherwise returns 1).                    */
 933
 934 /* Returns !=0 if GC_invoke_finalizers has something to do.     */
 935 GC_API int GC_CALL GC_should_invoke_finalizers(void);
 936
 937 GC_API int GC_CALL GC_invoke_finalizers(void);
 938         /* Run finalizers for all objects that are ready to     */
 939         /* be finalized.  Return the number of finalizers       */
 940         /* that were run.  Normally this is also called         */
 941         /* implicitly during some allocations.  If              */
 942         /* GC_finalize_on_demand is nonzero, it must be called  */
 943         /* explicitly.                                          */
 944
 945 /* Explicitly tell the collector that an object is reachable    */
 946 /* at a particular program point.  This prevents the argument   */
 947 /* pointer from being optimized away, even it is otherwise no   */
 948 /* longer needed.  It should have no visible effect in the      */
 949 /* absence of finalizers or disappearing links.  But it may be  */
 950 /* needed to prevent finalizers from running while the          */
 951 /* associated external resource is still in use.                */
 952 /* The function is sometimes called keep_alive in other         */
 953 /* settings.                                                    */
 954 #if defined(__GNUC__) && !defined(__INTEL_COMPILER)
 955 # define GC_reachable_here(ptr) \
 956   __asm__ volatile(" " : : "X"(ptr) : "memory");
 957 #else
 958   GC_API void GC_CALL GC_noop1(GC_word);
 959 # define GC_reachable_here(ptr) GC_noop1((GC_word)(ptr));
 960 #endif
 961
 962 /* GC_set_warn_proc can be used to redirect or filter warning messages. */
 963 /* p may not be a NULL pointer.  Both the setter and the getter acquire */
 964 /* the GC lock (to avoid data races).                                   */
 965 typedef void (GC_CALLBACK * GC_warn_proc)(char * /* msg */,
 966                                           GC_word /* arg */);
 967 GC_API void GC_CALL GC_set_warn_proc(GC_warn_proc /* p */);
 968 /* GC_get_warn_proc returns the current warn_proc.                      */
 969 GC_API GC_warn_proc GC_CALL GC_get_warn_proc(void);
 970
 971     /* GC_ignore_warn_proc may be used as an argument for       */
 972     /* GC_set_warn_proc() to suppress all warnings (unless      */
 973     /* statistics printing is turned on).                       */
 974 GC_API void GC_CALLBACK GC_ignore_warn_proc(char *, GC_word);
 975
 976 /* The following is intended to be used by a higher level       */
 977 /* (e.g. Java-like) finalization facility.  It is expected      */
 978 /* that finalization code will arrange for hidden pointers to   */
 979 /* disappear.  Otherwise objects can be accessed after they     */
 980 /* have been collected.                                         */
 981 /* Note that putting pointers in atomic objects or in           */
 982 /* nonpointer slots of "typed" objects is equivalent to         */
 983 /* disguising them in this way, and may have other advantages.  */
 984 #if defined(I_HIDE_POINTERS) || defined(GC_I_HIDE_POINTERS)
 985   typedef GC_word GC_hidden_pointer;
 986 # define HIDE_POINTER(p) (~(GC_hidden_pointer)(p))
 987 # define REVEAL_POINTER(p) ((void *)HIDE_POINTER(p))
 988   /* Converting a hidden pointer to a real pointer requires verifying   */
 989   /* that the object still exists.  This involves acquiring the         */
 990   /* allocator lock to avoid a race with the collector.                 */
 991 #endif /* I_HIDE_POINTERS */
 992
 993 /* The GC-prefixed symbols are preferred for new code (I_HIDE_POINTERS, */
 994 /* HIDE_POINTER and REVEAL_POINTER remain for compatibility).           */
 995 #ifdef GC_I_HIDE_POINTERS
 996 # define GC_HIDE_POINTER(p) HIDE_POINTER(p)
 997 # define GC_REVEAL_POINTER(p) REVEAL_POINTER(p)
 998 #endif
 999
1000 typedef void * (GC_CALLBACK * GC_fn_type)(void * /* client_data */);
1001 GC_API void * GC_CALL GC_call_with_alloc_lock(GC_fn_type /* fn */,
1002                                                 void * /* client_data */);
1003
1004 /* These routines are intended to explicitly notify the collector       */
1005 /* of new threads.  Often this is unnecessary because thread creation   */
1006 /* is implicitly intercepted by the collector, using header-file        */
1007 /* defines, or linker-based interception.  In the long run the intent   */
1008 /* is to always make redundant registration safe.  In the short run,    */
1009 /* this is being implemented a platform at a time.                      */
1010 /* The interface is complicated by the fact that we probably will not   */
1011 /* ever be able to automatically determine the stack base for thread    */
1012 /* stacks on all platforms.                                             */
1013
1014 /* Structure representing the base of a thread stack.  On most          */
1015 /* platforms this contains just a single address.                       */
1016 struct GC_stack_base {
1017   void * mem_base; /* Base of memory stack. */
1018 # if defined(__ia64) || defined(__ia64__) || defined(_M_IA64)
1019     void * reg_base; /* Base of separate register stack. */
1020 # endif
1021 };
1022
1023 typedef void * (GC_CALLBACK * GC_stack_base_func)(
1024                 struct GC_stack_base * /* sb */, void * /* arg */);
1025
1026 /* Call a function with a stack base structure corresponding to         */
1027 /* somewhere in the GC_call_with_stack_base frame.  This often can      */
1028 /* be used to provide a sufficiently accurate stack base.  And we       */
1029 /* implement it everywhere.                                             */
1030 GC_API void * GC_CALL GC_call_with_stack_base(GC_stack_base_func /* fn */,
1031                                               void * /* arg */);
1032
1033 #define GC_SUCCESS 0
1034 #define GC_DUPLICATE 1          /* Was already registered.              */
1035 #define GC_NO_THREADS 2         /* No thread support in GC.             */
1036         /* GC_NO_THREADS is not returned by any GC func anymore.        */
1037 #define GC_UNIMPLEMENTED 3 /* Not yet implemented on this platform.     */
1038
1039 /* GC_allow_register_threads(), GC_register_my_thread() and             */
1040 /* GC_unregister_my_thread() are exported only if the library has been  */
1041 /* compiled with threads support (GC_THREADS).                          */
1042
1043 /* Explicitly enable GC_register_my_thread() invocation.                */
1044 /* Done implicitly if a GC thread-creation function is called (or       */
1045 /* DllMain-based thread registration is enabled).  Otherwise, it must   */
1046 /* be called from the main (or any previously registered) thread        */
1047 /* between the collector initialization and the first explicit          */
1048 /* registering of a thread (it should be called as late as possible).   */
1049 GC_API void GC_CALL GC_allow_register_threads(void);
1050
1051 /* Register the current thread, with the indicated stack base, as       */
1052 /* a new thread whose stack(s) should be traced by the GC.  If it       */
1053 /* is not implicitly called by the GC, this must be called before a     */
1054 /* thread can allocate garbage collected memory, or assign pointers     */
1055 /* to the garbage collected heap.  Once registered, a thread will be    */
1056 /* stopped during garbage collections.                                  */
1057 /* This call must be previously enabled (see above).                    */
1058 /* This should never be called from the main thread, where it is        */
1059 /* always done implicitly.  This is normally done implicitly if GC_     */
1060 /* functions are called to create the thread, e.g. by defining          */
1061 /* GC_THREADS and including gc.h (which redefines some system           */
1062 /* functions) before calling the system thread creation function.       */
1063 /* It is also always done implicitly under win32 with DllMain-based     */
1064 /* thread registration enabled.  Except in this latter case, explicit   */
1065 /* calls are normally required for threads created by third-party       */
1066 /* libraries.                                                           */
1067 GC_API int GC_CALL GC_register_my_thread(const struct GC_stack_base *);
1068
1069 /* Unregister the current thread.  Only an explicity registered thread  */
1070 /* (i.e. for which GC_register_my_thread() returns GC_SUCCESS) is       */
1071 /* allowed (and required) to call this function.  The thread may no     */
1072 /* longer allocate garbage collected memory or manipulate pointers to   */
1073 /* the garbage collected heap after making this call.                   */
1074 /* Specifically, if it wants to return or otherwise communicate a       */
1075 /* pointer to the garbage-collected heap to another thread, it must     */
1076 /* do this before calling GC_unregister_my_thread, most probably        */
1077 /* by saving it in a global data structure.  Must not be called inside  */
1078 /* a GC callback function (except for GC_call_with_stack_base() one).   */
1079 GC_API int GC_CALL GC_unregister_my_thread(void);
1080
1081 /* Wrapper for functions that are likely to block (or, at least, do not */
1082 /* allocate garbage collected memory and/or manipulate pointers to the  */
1083 /* garbage collected heap) for an appreciable length of time.  While fn */
1084 /* is running, the collector is said to be in the "inactive" state for  */
1085 /* the current thread (this means that the thread is not suspended and  */
1086 /* the thread's stack frames "belonging" to the functions in the        */
1087 /* "inactive" state are not scanned during garbage collections).  It is */
1088 /* allowed for fn to call GC_call_with_gc_active() (even recursively),  */
1089 /* thus temporarily toggling the collector's state back to "active".    */
1090 GC_API void * GC_CALL GC_do_blocking(GC_fn_type /* fn */,
1091                                      void * /* client_data */);
1092
1093 /* Call a function switching to the "active" state of the collector for */
1094 /* the current thread (i.e. the user function is allowed to call any    */
1095 /* GC function and/or manipulate pointers to the garbage collected      */
1096 /* heap).  GC_call_with_gc_active() has the functionality opposite to   */
1097 /* GC_do_blocking() one.  It is assumed that the collector is already   */
1098 /* initialized and the current thread is registered.  fn may toggle     */
1099 /* the collector thread's state temporarily to "inactive" one by using  */
1100 /* GC_do_blocking.  GC_call_with_gc_active() often can be used to       */
1101 /* provide a sufficiently accurate stack base.                          */
1102 GC_API void * GC_CALL GC_call_with_gc_active(GC_fn_type /* fn */,
1103                                              void * /* client_data */);
1104
1105 /* Attempt to fill in the GC_stack_base structure with the stack base   */
1106 /* for this thread.  This appears to be required to implement anything  */
1107 /* like the JNI AttachCurrentThread in an environment in which new      */
1108 /* threads are not automatically registered with the collector.         */
1109 /* It is also unfortunately hard to implement well on many platforms.   */
1110 /* Returns GC_SUCCESS or GC_UNIMPLEMENTED.                              */
1111 GC_API int GC_CALL GC_get_stack_base(struct GC_stack_base *);
1112
1113 /* The following routines are primarily intended for use with a         */
1114 /* preprocessor which inserts calls to check C pointer arithmetic.      */
1115 /* They indicate failure by invoking the corresponding _print_proc.     */
1116
1117 /* Check that p and q point to the same object.                 */
1118 /* Fail conspicuously if they don't.                            */
1119 /* Returns the first argument.                                  */
1120 /* Succeeds if neither p nor q points to the heap.              */
1121 /* May succeed if both p and q point to between heap objects.   */
1122 GC_API void * GC_CALL GC_same_obj(void * /* p */, void * /* q */);
1123
1124 /* Checked pointer pre- and post- increment operations.  Note that      */
1125 /* the second argument is in units of bytes, not multiples of the       */
1126 /* object size.  This should either be invoked from a macro, or the     */
1127 /* call should be automatically generated.                              */
1128 GC_API void * GC_CALL GC_pre_incr(void **, ptrdiff_t /* how_much */);
1129 GC_API void * GC_CALL GC_post_incr(void **, ptrdiff_t /* how_much */);
1130
1131 /* Check that p is visible                                              */
1132 /* to the collector as a possibly pointer containing location.          */
1133 /* If it isn't fail conspicuously.                                      */
1134 /* Returns the argument in all cases.  May erroneously succeed          */
1135 /* in hard cases.  (This is intended for debugging use with             */
1136 /* untyped allocations.  The idea is that it should be possible, though */
1137 /* slow, to add such a call to all indirect pointer stores.)            */
1138 /* Currently useless for multithreaded worlds.                          */
1139 GC_API void * GC_CALL GC_is_visible(void * /* p */);
1140
1141 /* Check that if p is a pointer to a heap page, then it points to       */
1142 /* a valid displacement within a heap object.                           */
1143 /* Fail conspicuously if this property does not hold.                   */
1144 /* Uninteresting with GC_all_interior_pointers.                         */
1145 /* Always returns its argument.                                         */
1146 GC_API void * GC_CALL GC_is_valid_displacement(void * /* p */);
1147
1148 /* Explicitly dump the GC state.  This is most often called from the    */
1149 /* debugger, or by setting the GC_DUMP_REGULARLY environment variable,  */
1150 /* but it may be useful to call it from client code during debugging.   */
1151 /* Defined only if the library has been compiled without NO_DEBUGGING.  */
1152 GC_API void GC_CALL GC_dump(void);
1153
1154 /* Safer, but slow, pointer addition.  Probably useful mainly with      */
1155 /* a preprocessor.  Useful only for heap pointers.                      */
1156 /* Only the macros without trailing digits are meant to be used         */
1157 /* by clients.  These are designed to model the available C pointer     */
1158 /* arithmetic expressions.                                              */
1159 /* Even then, these are probably more useful as                         */
1160 /* documentation than as part of the API.                               */
1161 /* Note that GC_PTR_ADD evaluates the first argument more than once.    */
1162 #if defined(GC_DEBUG) && defined(__GNUC__)
1163 # define GC_PTR_ADD3(x, n, type_of_result) \
1164         ((type_of_result)GC_same_obj((x)+(n), (x)))
1165 # define GC_PRE_INCR3(x, n, type_of_result) \
1166         ((type_of_result)GC_pre_incr((void **)(&(x)), (n)*sizeof(*x)))
1167 # define GC_POST_INCR3(x, n, type_of_result) \
1168         ((type_of_result)GC_post_incr((void **)(&(x)), (n)*sizeof(*x)))
1169 # define GC_PTR_ADD(x, n) GC_PTR_ADD3(x, n, typeof(x))
1170 # define GC_PRE_INCR(x, n) GC_PRE_INCR3(x, n, typeof(x))
1171 # define GC_POST_INCR(x) GC_POST_INCR3(x, 1, typeof(x))
1172 # define GC_POST_DECR(x) GC_POST_INCR3(x, -1, typeof(x))
1173 #else /* !GC_DEBUG || !__GNUC__ */
1174   /* We can't do this right without typeof, which ANSI decided was not    */
1175   /* sufficiently useful.  Without it we resort to the non-debug version. */
1176   /* FIXME: This should eventually support C++0x decltype.                */
1177 # define GC_PTR_ADD(x, n) ((x)+(n))
1178 # define GC_PRE_INCR(x, n) ((x) += (n))
1179 # define GC_POST_INCR(x) ((x)++)
1180 # define GC_POST_DECR(x) ((x)--)
1181 #endif /* !GC_DEBUG || !__GNUC__ */
1182
1183 /* Safer assignment of a pointer to a non-stack location.       */
1184 #ifdef GC_DEBUG
1185 # define GC_PTR_STORE(p, q) \
1186         (*(void **)GC_is_visible(p) = GC_is_valid_displacement(q))
1187 #else
1188 # define GC_PTR_STORE(p, q) (*(p) = (q))
1189 #endif
1190
1191 /* Functions called to report pointer checking errors */
1192 GC_API void (GC_CALLBACK * GC_same_obj_print_proc)(void * /* p */,
1193                                                    void * /* q */);
1194 GC_API void (GC_CALLBACK * GC_is_valid_displacement_print_proc)(void *);
1195 GC_API void (GC_CALLBACK * GC_is_visible_print_proc)(void *);
1196
1197 #ifdef GC_PTHREADS
1198   /* For pthread support, we generally need to intercept a number of    */
1199   /* thread library calls.  We do that here by macro defining them.     */
1200 # include "gc_pthread_redirects.h"
1201 #endif
1202
1203 /* This returns a list of objects, linked through their first word.     */
1204 /* Its use can greatly reduce lock contention problems, since the       */
1205 /* allocation lock can be acquired and released many fewer times.       */
1206 /* Exported only if the library has been compiled with threads support. */
1207 GC_API void * GC_CALL GC_malloc_many(size_t /* lb */);
1208 #define GC_NEXT(p) (*(void * *)(p))     /* Retrieve the next element    */
1209                                         /* in returned list.            */
1210
1211 /* A filter function to control the scanning of dynamic libraries.      */
1212 /* If implemented, called by GC before registering a dynamic library    */
1213 /* (discovered by GC) section as a static data root (called only as     */
1214 /* a last reason not to register).  The filename of the library, the    */
1215 /* address and the length of the memory region (section) are passed.    */
1216 /* This routine should return nonzero if that region should be scanned. */
1217 /* Always called with the allocation lock held.  Depending on the       */
1218 /* platform, might be called with the "world" stopped.                  */
1219 typedef int (GC_CALLBACK * GC_has_static_roots_func)(
1220                                         const char * /* dlpi_name */,
1221                                         void * /* section_start */,
1222                                         size_t /* section_size */);
1223
1224 /* Register a new callback (a user-supplied filter) to control the      */
1225 /* scanning of dynamic libraries.  Replaces any previously registered   */
1226 /* callback.  May be 0 (means no filtering).  May be unused on some     */
1227 /* platforms (if the filtering is unimplemented or inappropriate).      */
1228 GC_API void GC_CALL GC_register_has_static_roots_callback(
1229                                         GC_has_static_roots_func);
1230
1231 #if defined(GC_WIN32_THREADS) && !defined(GC_PTHREADS)
1232
1233 # ifndef GC_NO_THREAD_DECLS
1234
1235 #   ifdef __cplusplus
1236       } /* Including windows.h in an extern "C" context no longer works. */
1237 #   endif
1238
1239 #   if !defined(_WIN32_WCE) && !defined(__CEGCC__)
1240 #     include <process.h> /* For _beginthreadex, _endthreadex */
1241 #   endif
1242
1243 #   include <windows.h>
1244
1245 #   ifdef __cplusplus
1246       extern "C" {
1247 #   endif
1248
1249 #   ifdef GC_UNDERSCORE_STDCALL
1250       /* Explicitly prefix exported/imported WINAPI (__stdcall) symbols */
1251       /* with '_' (underscore).  Might be useful if MinGW/x86 is used.  */
1252 #     define GC_CreateThread _GC_CreateThread
1253 #     define GC_ExitThread _GC_ExitThread
1254 #   endif
1255
1256     /* All threads must be created using GC_CreateThread or             */
1257     /* GC_beginthreadex, or must explicitly call GC_register_my_thread  */
1258     /* (and call GC_unregister_my_thread before thread termination), so */
1259     /* that they will be recorded in the thread table.  For backward    */
1260     /* compatibility, it is possible to build the GC with GC_DLL        */
1261     /* defined, and to call GC_use_DllMain().  This implicitly          */
1262     /* registers all created threads, but appears to be less robust.    */
1263     /* Currently the collector expects all threads to fall through and  */
1264     /* terminate normally, or call GC_endthreadex() or GC_ExitThread,   */
1265     /* so that the thread is properly unregistered.                     */
1266     GC_API HANDLE WINAPI GC_CreateThread(
1267                 LPSECURITY_ATTRIBUTES /* lpThreadAttributes */,
1268                 DWORD /* dwStackSize */,
1269                 LPTHREAD_START_ROUTINE /* lpStartAddress */,
1270                 LPVOID /* lpParameter */, DWORD /* dwCreationFlags */,
1271                 LPDWORD /* lpThreadId */);
1272
1273     GC_API void WINAPI GC_ExitThread(DWORD /* dwExitCode */);
1274
1275 #   if !defined(_WIN32_WCE) && !defined(__CEGCC__)
1276 #     if !defined(_UINTPTR_T) && !defined(_UINTPTR_T_DEFINED) \
1277                 && !defined(UINTPTR_MAX)
1278         typedef GC_word GC_uintptr_t;
1279 #     else
1280         typedef uintptr_t GC_uintptr_t;
1281 #     endif
1282
1283       GC_API GC_uintptr_t GC_CALL GC_beginthreadex(
1284                         void * /* security */, unsigned /* stack_size */,
1285                         unsigned (__stdcall *)(void *),
1286                         void * /* arglist */, unsigned /* initflag */,
1287                         unsigned * /* thrdaddr */);
1288
1289       GC_API void GC_CALL GC_endthreadex(unsigned /* retval */);
1290 #   endif /* !_WIN32_WCE */
1291
1292 # endif /* !GC_NO_THREAD_DECLS */
1293
1294 # ifdef GC_WINMAIN_REDIRECT
1295     /* win32_threads.c implements the real WinMain(), which will start  */
1296     /* a new thread to call GC_WinMain() after initializing the garbage */
1297     /* collector.                                                       */
1298 #   define WinMain GC_WinMain
1299 # endif
1300
1301   /* Use implicit thread registration via DllMain.  Deprecated.  Must   */
1302   /* be called before GC_INIT() and other GC routines.  Should be       */
1303   /* avoided if GC_beginthreadex() or GC_CreateThread() could be called */
1304   /* instead.                                                           */
1305   GC_API void GC_CALL GC_use_DllMain(void);
1306
1307 # ifndef GC_NO_THREAD_REDIRECTS
1308 #   define CreateThread GC_CreateThread
1309 #   define ExitThread GC_ExitThread
1310 #   undef _beginthreadex
1311 #   define _beginthreadex GC_beginthreadex
1312 #   undef _endthreadex
1313 #   define _endthreadex GC_endthreadex
1314 /* #define _beginthread { > "Please use _beginthreadex instead of _beginthread" < } */
1315 # endif /* !GC_NO_THREAD_REDIRECTS */
1316
1317 #endif /* GC_WIN32_THREADS */
1318
1319 /* Public setter and getter for switching "unmap as much as possible"   */
1320 /* mode on(1) and off(0).  Has no effect unless unmapping is turned on. */
1321 /* Has no effect on implicitly-initiated garbage collections.  Initial  */
1322 /* value is controlled by GC_FORCE_UNMAP_ON_GCOLLECT.                   */
1323 GC_API void GC_CALL GC_set_force_unmap_on_gcollect(int);
1324 GC_API int GC_CALL GC_get_force_unmap_on_gcollect(void);
1325
1326  /* Fully portable code should call GC_INIT() from the main program     */
1327  /* before making any other GC_ calls.  On most platforms this is a     */
1328  /* no-op and the collector self-initializes.  But a number of          */
1329  /* platforms make that too hard.                                       */
1330  /* A GC_INIT call is required if the collector is built with           */
1331  /* THREAD_LOCAL_ALLOC defined and the initial allocation call is not   */
1332  /* to GC_malloc() or GC_malloc_atomic().                               */
1333
1334 #ifdef __CYGWIN32__
1335   /* Similarly gnu-win32 DLLs need explicit initialization from the     */
1336   /* main program, as does AIX.                                         */
1337   extern int _data_start__[], _data_end__[], _bss_start__[], _bss_end__[];
1338 # define GC_DATASTART (_data_start__ < _bss_start__ ? \
1339                        (void *)_data_start__ : (void *)_bss_start__)
1340 # define GC_DATAEND (_data_end__ > _bss_end__ ? \
1341                      (void *)_data_end__ : (void *)_bss_end__)
1342 # define GC_INIT_CONF_ROOTS GC_add_roots(GC_DATASTART, GC_DATAEND); \
1343                                  GC_gcollect() /* For blacklisting. */
1344         /* Required at least if GC is in dll.  And doesn't hurt. */
1345 #elif defined(_AIX)
1346   extern int _data[], _end[];
1347 # define GC_DATASTART ((void *)((ulong)_data))
1348 # define GC_DATAEND ((void *)((ulong)_end))
1349 # define GC_INIT_CONF_ROOTS GC_add_roots(GC_DATASTART, GC_DATAEND)
1350 #else
1351 # define GC_INIT_CONF_ROOTS /* empty */
1352 #endif
1353
1354 #ifdef GC_DONT_EXPAND
1355   /* Set GC_dont_expand to TRUE at start-up */
1356 # define GC_INIT_CONF_DONT_EXPAND GC_set_dont_expand(1)
1357 #else
1358 # define GC_INIT_CONF_DONT_EXPAND /* empty */
1359 #endif
1360
1361 #ifdef GC_FORCE_UNMAP_ON_GCOLLECT
1362   /* Turn on "unmap as much as possible on explicit GC" mode at start-up */
1363 # define GC_INIT_CONF_FORCE_UNMAP_ON_GCOLLECT \
1364                 GC_set_force_unmap_on_gcollect(1)
1365 #else
1366 # define GC_INIT_CONF_FORCE_UNMAP_ON_GCOLLECT /* empty */
1367 #endif
1368
1369 #ifdef GC_MAX_RETRIES
1370   /* Set GC_max_retries to the desired value at start-up */
1371 # define GC_INIT_CONF_MAX_RETRIES GC_set_max_retries(GC_MAX_RETRIES)
1372 #else
1373 # define GC_INIT_CONF_MAX_RETRIES /* empty */
1374 #endif
1375
1376 #ifdef GC_FREE_SPACE_DIVISOR
1377   /* Set GC_free_space_divisor to the desired value at start-up */
1378 # define GC_INIT_CONF_FREE_SPACE_DIVISOR \
1379                 GC_set_free_space_divisor(GC_FREE_SPACE_DIVISOR)
1380 #else
1381 # define GC_INIT_CONF_FREE_SPACE_DIVISOR /* empty */
1382 #endif
1383
1384 #ifdef GC_FULL_FREQ
1385   /* Set GC_full_freq to the desired value at start-up */
1386 # define GC_INIT_CONF_FULL_FREQ GC_set_full_freq(GC_FULL_FREQ)
1387 #else
1388 # define GC_INIT_CONF_FULL_FREQ /* empty */
1389 #endif
1390
1391 #ifdef GC_TIME_LIMIT
1392   /* Set GC_time_limit to the desired value at start-up */
1393 # define GC_INIT_CONF_TIME_LIMIT GC_set_time_limit(GC_TIME_LIMIT)
1394 #else
1395 # define GC_INIT_CONF_TIME_LIMIT /* empty */
1396 #endif
1397
1398 #ifdef GC_MAXIMUM_HEAP_SIZE
1399   /* Limit the heap size to the desired value (useful for debugging).   */
1400   /* The limit could be overridden either at the program start-up by    */
1401   /* the similar environment variable or anytime later by the           */
1402   /* corresponding API function call.                                   */
1403 # define GC_INIT_CONF_MAXIMUM_HEAP_SIZE \
1404                 GC_set_max_heap_size(GC_MAXIMUM_HEAP_SIZE)
1405 #else
1406 # define GC_INIT_CONF_MAXIMUM_HEAP_SIZE /* empty */
1407 #endif
1408
1409 #ifdef GC_IGNORE_WARN
1410   /* Turn off all warnings at start-up (after GC initialization) */
1411 # define GC_INIT_CONF_IGNORE_WARN GC_set_warn_proc(GC_ignore_warn_proc)
1412 #else
1413 # define GC_INIT_CONF_IGNORE_WARN /* empty */
1414 #endif
1415
1416 #ifdef GC_INITIAL_HEAP_SIZE
1417   /* Set heap size to the desired value at start-up */
1418 # define GC_INIT_CONF_INITIAL_HEAP_SIZE \
1419                 { size_t heap_size = GC_get_heap_size(); \
1420                   if (heap_size < (GC_INITIAL_HEAP_SIZE)) \
1421                     (void)GC_expand_hp((GC_INITIAL_HEAP_SIZE) - heap_size); }
1422 #else
1423 # define GC_INIT_CONF_INITIAL_HEAP_SIZE /* empty */
1424 #endif
1425
1426 #define GC_INIT() { GC_INIT_CONF_DONT_EXPAND; /* pre-init */ \
1427                     GC_INIT_CONF_FORCE_UNMAP_ON_GCOLLECT; \
1428                     GC_INIT_CONF_MAX_RETRIES; \
1429                     GC_INIT_CONF_FREE_SPACE_DIVISOR; \
1430                     GC_INIT_CONF_FULL_FREQ; \
1431                     GC_INIT_CONF_TIME_LIMIT; \
1432                     GC_INIT_CONF_MAXIMUM_HEAP_SIZE; \
1433                     GC_init(); /* real GC initialization */ \
1434                     GC_INIT_CONF_ROOTS; /* post-init */ \
1435                     GC_INIT_CONF_IGNORE_WARN; \
1436                     GC_INIT_CONF_INITIAL_HEAP_SIZE; }
1437
1438 /* win32S may not free all resources on process exit.   */
1439 /* This explicitly deallocates the heap.                */
1440 GC_API void GC_CALL GC_win32_free_heap(void);
1441
1442 #if defined(_AMIGA) && !defined(GC_AMIGA_MAKINGLIB)
1443   /* Allocation really goes through GC_amiga_allocwrapper_do    */
1444 # include "gc_amiga_redirects.h"
1445 #endif
1446
1447   /*
1448    * GC_REDIRECT_TO_LOCAL is now redundant;
1449    * that's the default with THREAD_LOCAL_ALLOC.
1450    */
1451
1452 #ifdef __cplusplus
1453   }  /* end of extern "C" */
1454 #endif
1455
1456 #endif /* GC_H */