Back to index

plt-scheme  4.2.1
gc.h
Go to the documentation of this file.
00001 /* 
00002  * Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
00003  * Copyright (c) 1991-1995 by Xerox Corporation.  All rights reserved.
00004  * Copyright 1996-1999 by Silicon Graphics.  All rights reserved.
00005  * Copyright 1999 by Hewlett-Packard Company.  All rights reserved.
00006  *
00007  * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
00008  * OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
00009  *
00010  * Permission is hereby granted to use or copy this program
00011  * for any purpose,  provided the above notices are retained on all copies.
00012  * Permission to modify the code and to distribute modified code is granted,
00013  * provided the above notices are retained, and a notice that the code was
00014  * modified is included with the above copyright notice.
00015  */
00016 
00017 /*
00018  * Note that this defines a large number of tuning hooks, which can
00019  * safely be ignored in nearly all cases.  For normal use it suffices
00020  * to call only GC_MALLOC and perhaps GC_REALLOC.
00021  * For better performance, also look at GC_MALLOC_ATOMIC, and
00022  * GC_enable_incremental.  If you need an action to be performed
00023  * immediately before an object is collected, look at GC_register_finalizer.
00024  * If you are using Solaris threads, look at the end of this file.
00025  * Everything else is best ignored unless you encounter performance
00026  * problems.
00027  */
00028  
00029 #ifndef _GC_H
00030 
00031 # define _GC_H
00032 
00033 # include "gc_config_macros.h"
00034 
00035 # if defined(__STDC__) || defined(__cplusplus) || defined(_AIX)
00036 #   define GC_PROTO(args) args
00037     typedef void * GC_PTR;
00038 #   define GC_CONST const
00039 # else
00040 #   define GC_PROTO(args) ()
00041     typedef char * GC_PTR;
00042 #   define GC_CONST
00043 #  endif
00044 
00045 # ifdef __cplusplus
00046     extern "C" {
00047 # endif
00048 
00049 
00050 /* Define word and signed_word to be unsigned and signed types of the        */
00051 /* size as char * or void *.  There seems to be no way to do this     */
00052 /* even semi-portably.  The following is probably no better/worse     */
00053 /* than almost anything else.                                         */
00054 /* The ANSI standard suggests that size_t and ptr_diff_t might be     */
00055 /* better choices.  But those had incorrect definitions on some older */
00056 /* systems.  Notably "typedef int size_t" is WRONG.                   */
00057 #ifndef _WIN64
00058   typedef unsigned long GC_word;
00059   typedef long GC_signed_word;
00060 #else
00061   /* Win64 isn't really supported yet, but this is the first step. And       */
00062   /* it might cause error messages to show up in more plausible places.      */
00063   /* This needs basetsd.h, which is included by windows.h.            */
00064   typedef ULONG_PTR GC_word;
00065   typedef LONG_PTR GC_word;
00066 #endif
00067 
00068 /* Public read-only variables */
00069 
00070 GC_API GC_word GC_gc_no;/* Counter incremented per collection.        */
00071                      /* Includes empty GCs at startup.         */
00072 
00073 GC_API int GC_parallel;     /* GC is parallelized for performance on  */
00074                      /* multiprocessors.  Currently set only          */
00075                      /* implicitly if collector is built with  */
00076                      /* -DPARALLEL_MARK and if either:         */
00077                      /*  Env variable GC_NPROC is set to > 1, or      */
00078                      /*  GC_NPROC is not set and this is an MP.       */
00079                      /* If GC_parallel is set, incremental            */
00080                      /* collection is only partially functional,      */
00081                      /* and may not be desirable.                     */
00082                      
00083 
00084 /* Public R/W variables */
00085 
00086 GC_API GC_PTR (*GC_oom_fn) GC_PROTO((size_t bytes_requested));
00087                      /* When there is insufficient memory to satisfy */
00088                      /* an allocation request, we return              */
00089                      /* (*GC_oom_fn)().  By default this just  */
00090                      /* returns 0.                             */
00091                      /* If it returns, it must return 0 or a valid    */
00092                      /* pointer to a previously allocated heap        */
00093                      /* object.                                */
00094 
00095 GC_API int GC_find_leak;
00096                      /* Do not actually garbage collect, but simply   */
00097                      /* report inaccessible memory that was not       */
00098                      /* deallocated with GC_free.  Initial value      */
00099                      /* is determined by FIND_LEAK macro.             */
00100 
00101 GC_API int GC_all_interior_pointers;
00102                      /* Arrange for pointers to object interiors to   */
00103                      /* be recognized as valid.  May not be changed   */
00104                      /* after GC initialization.               */
00105                      /* Initial value is determined by         */
00106                      /* -DALL_INTERIOR_POINTERS.               */
00107                      /* Unless DONT_ADD_BYTE_AT_END is defined, this  */
00108                      /* also affects whether sizes are increased by   */
00109                      /* at least a byte to allow "off the end" */
00110                      /* pointer recognition.                          */
00111                      /* MUST BE 0 or 1.                        */
00112 
00113 GC_API int GC_quiet; /* Disable statistics output.  Only matters if   */
00114                      /* collector has been compiled with statistics   */
00115                      /* enabled.  This involves a performance cost,   */
00116                      /* and is thus not the default.                  */
00117 
00118 GC_API int GC_finalize_on_demand;
00119                      /* If nonzero, finalizers will only be run in    */
00120                      /* response to an explicit GC_invoke_finalizers  */
00121                      /* call.  The default is determined by whether   */
00122                      /* the FINALIZE_ON_DEMAND macro is defined       */
00123                      /* when the collector is built.                  */
00124 
00125 GC_API int GC_java_finalization;
00126                      /* Mark objects reachable from finalizable       */
00127                      /* objects in a separate postpass.  This makes   */
00128                      /* it a bit safer to use non-topologically-      */
00129                      /* ordered finalization.  Default value is       */
00130                      /* determined by JAVA_FINALIZATION macro. */
00131 
00132 GC_API void (* GC_finalizer_notifier) GC_PROTO((void));
00133                      /* Invoked by the collector when there are       */
00134                      /* objects to be finalized.  Invoked at most     */
00135                      /* once per GC cycle.  Never invoked unless      */
00136                      /* GC_finalize_on_demand is set.          */
00137                      /* Typically this will notify a finalization     */
00138                      /* thread, which will call GC_invoke_finalizers */
00139                      /* in response.                                  */
00140 
00141 GC_API int GC_dont_gc;      /* != 0 ==> Dont collect.  In versions 6.2a1+,   */
00142                      /* this overrides explicit GC_gcollect() calls.  */
00143                      /* Used as a counter, so that nested enabling    */
00144                      /* and disabling work correctly.  Should  */
00145                      /* normally be updated with GC_enable() and      */
00146                      /* GC_disable() calls.                           */
00147                      /* Direct assignment to GC_dont_gc is            */
00148                      /* deprecated.                                   */
00149 
00150 GC_API int GC_dont_expand;
00151                      /* Dont expand heap unless explicitly requested */
00152                      /* or forced to.                          */
00153 
00154 GC_API int GC_use_entire_heap;
00155               /* Causes the nonincremental collector to use the       */
00156               /* entire heap before collecting.  This was the only    */
00157               /* option for GC versions < 5.0.  This sometimes */
00158               /* results in more large block fragmentation, since     */
00159               /* very larg blocks will tend to get broken up          */
00160               /* during each GC cycle.  It is likely to result in a   */
00161               /* larger working set, but lower collection             */
00162               /* frequencies, and hence fewer instructions executed   */
00163               /* in the collector.                             */
00164 
00165 GC_API int GC_full_freq;    /* Number of partial collections between  */
00166                          /* full collections.  Matters only if */
00167                          /* GC_incremental is set.                    */
00168                          /* Full collections are also triggered if    */
00169                          /* the collector detects a substantial       */
00170                          /* increase in the number of in-use heap     */
00171                          /* blocks.  Values in the tens are now       */
00172                          /* perfectly reasonable, unlike for          */
00173                          /* earlier GC versions.               */
00174                      
00175 GC_API GC_word GC_non_gc_bytes;
00176                      /* Bytes not considered candidates for collection. */
00177                      /* Used only to control scheduling of collections. */
00178                      /* Updated by GC_malloc_uncollectable and GC_free. */
00179                      /* Wizards only.                             */
00180 
00181 GC_API int GC_no_dls;
00182                      /* Don't register dynamic library data segments. */
00183                      /* Wizards only.  Should be used only if the      */
00184                      /* application explicitly registers all roots.    */
00185                      /* In Microsoft Windows environments, this will   */
00186                      /* usually also prevent registration of the       */
00187                      /* main data segment as part of the root set.     */
00188 
00189 GC_API GC_word GC_free_space_divisor;
00190                      /* We try to make sure that we allocate at       */
00191                      /* least N/GC_free_space_divisor bytes between   */
00192                      /* collections, where N is the heap size plus    */
00193                      /* a rough estimate of the root set size. */
00194                      /* Initially, GC_free_space_divisor = 3.  */
00195                      /* Increasing its value will use less space      */
00196                      /* but more collection time.  Decreasing it      */
00197                      /* will appreciably decrease collection time     */
00198                      /* at the expense of space.               */
00199                      /* GC_free_space_divisor = 1 will effectively    */
00200                      /* disable collections.                          */
00201 
00202 GC_API GC_word GC_max_retries;
00203                      /* The maximum number of GCs attempted before    */
00204                      /* reporting out of memory after heap            */
00205                      /* expansion fails.  Initially 0.         */
00206                      
00207 
00208 GC_API char *GC_stackbottom;       /* Cool end of user stack.         */
00209                             /* May be set in the client prior to      */
00210                             /* calling any GC_ routines.  This */
00211                             /* avoids some overhead, and              */
00212                             /* potentially some signals that can      */
00213                             /* confuse debuggers.  Otherwise the      */
00214                             /* collector attempts to set it    */
00215                             /* automatically.                  */
00216                             /* For multithreaded code, this is the    */
00217                             /* cold end of the stack for the   */
00218                             /* primordial thread.                     */     
00219                             
00220 GC_API int GC_dont_precollect;  /* Don't collect as part of           */
00221                             /* initialization.  Should be set only    */
00222                             /* if the client wants a chance to */
00223                             /* manually initialize the root set       */
00224                             /* before the first collection.           */
00225                             /* Interferes with blacklisting.   */
00226                             /* Wizards only.                   */
00227 
00228 GC_API unsigned long GC_time_limit;
00229                             /* If incremental collection is enabled, */
00230                             /* We try to terminate collections  */
00231                             /* after this many milliseconds.  Not a    */
00232                             /* hard time bound.  Setting this to       */
00233                             /* GC_TIME_UNLIMITED will essentially      */
00234                             /* disable incremental collection while  */
00235                             /* leaving generational collection  */
00236                             /* enabled.                         */
00237 #      define GC_TIME_UNLIMITED 999999
00238                             /* Setting GC_time_limit to this value     */
00239                             /* will disable the "pause time exceeded"*/
00240                             /* tests.                           */
00241 
00242 /* Public procedures */
00243 
00244 /* Initialize the collector.  This is only required when using thread-local
00245  * allocation, since unlike the regular allocation routines, GC_local_malloc
00246  * is not self-initializing.  If you use GC_local_malloc you should arrange
00247  * to call this somehow (e.g. from a constructor) before doing any allocation.
00248  * For win32 threads, it needs to be called explicitly.
00249  */
00250 GC_API void GC_init GC_PROTO((void));
00251 
00252 /*
00253  * general purpose allocation routines, with roughly malloc calling conv.
00254  * The atomic versions promise that no relevant pointers are contained
00255  * in the object.  The nonatomic versions guarantee that the new object
00256  * is cleared.  GC_malloc_stubborn promises that no changes to the object
00257  * will occur after GC_end_stubborn_change has been called on the
00258  * result of GC_malloc_stubborn. GC_malloc_uncollectable allocates an object
00259  * that is scanned for pointers to collectable objects, but is not itself
00260  * collectable.  The object is scanned even if it does not appear to
00261  * be reachable.  GC_malloc_uncollectable and GC_free called on the resulting
00262  * object implicitly update GC_non_gc_bytes appropriately.
00263  *
00264  * Note that the GC_malloc_stubborn support is stubbed out by default
00265  * starting in 6.0.  GC_malloc_stubborn is an alias for GC_malloc unless
00266  * the collector is built with STUBBORN_ALLOC defined.
00267  */
00268 GC_API GC_PTR GC_malloc GC_PROTO((size_t size_in_bytes));
00269 GC_API GC_PTR GC_malloc_atomic GC_PROTO((size_t size_in_bytes));
00270 GC_API char *GC_strdup GC_PROTO((const char *str));
00271 GC_API GC_PTR GC_malloc_uncollectable GC_PROTO((size_t size_in_bytes));
00272 GC_API GC_PTR GC_malloc_stubborn GC_PROTO((size_t size_in_bytes));
00273 
00274 /* The following is only defined if the library has been suitably     */
00275 /* compiled:                                                   */
00276 GC_API GC_PTR GC_malloc_atomic_uncollectable GC_PROTO((size_t size_in_bytes));
00277 
00278 /* Explicitly deallocate an object.  Dangerous if used incorrectly.     */
00279 /* Requires a pointer to the base of an object.                       */
00280 /* If the argument is stubborn, it should not be changeable when freed. */
00281 /* An object should not be enable for finalization when it is         */
00282 /* explicitly deallocated.                                     */
00283 /* GC_free(0) is a no-op, as required by ANSI C for free.             */
00284 GC_API void GC_free GC_PROTO((GC_PTR object_addr));
00285 
00286 /*
00287  * Stubborn objects may be changed only if the collector is explicitly informed.
00288  * The collector is implicitly informed of coming change when such
00289  * an object is first allocated.  The following routines inform the
00290  * collector that an object will no longer be changed, or that it will
00291  * once again be changed.  Only nonNIL pointer stores into the object
00292  * are considered to be changes.  The argument to GC_end_stubborn_change
00293  * must be exacly the value returned by GC_malloc_stubborn or passed to
00294  * GC_change_stubborn.  (In the second case it may be an interior pointer
00295  * within 512 bytes of the beginning of the objects.)
00296  * There is a performance penalty for allowing more than
00297  * one stubborn object to be changed at once, but it is acceptable to
00298  * do so.  The same applies to dropping stubborn objects that are still
00299  * changeable.
00300  */
00301 GC_API void GC_change_stubborn GC_PROTO((GC_PTR));
00302 GC_API void GC_end_stubborn_change GC_PROTO((GC_PTR));
00303 
00304 /* Return a pointer to the base (lowest address) of an object given   */
00305 /* a pointer to a location within the object.                         */
00306 /* I.e. map an interior pointer to the corresponding bas pointer.     */
00307 /* Note that with debugging allocation, this returns a pointer to the */
00308 /* actual base of the object, i.e. the debug information, not to      */
00309 /* the base of the user object.                                       */
00310 /* Return 0 if displaced_pointer doesn't point to within a valid      */
00311 /* object.                                                     */
00312 /* Note that a deallocated object in the garbage collected heap              */
00313 /* may be considered valid, even if it has been deallocated with      */
00314 /* GC_free.                                                    */
00315 GC_API GC_PTR GC_base GC_PROTO((GC_PTR displaced_pointer));
00316 
00317 /* Given a pointer to the base of an object, return its size in bytes.       */
00318 /* The returned size may be slightly larger than what was originally  */
00319 /* requested.                                                  */
00320 GC_API size_t GC_size GC_PROTO((GC_PTR object_addr));
00321 
00322 /* For compatibility with C library.  This is occasionally faster than       */
00323 /* a malloc followed by a bcopy.  But if you rely on that, either here       */
00324 /* or with the standard C library, your code is broken.  In my        */
00325 /* opinion, it shouldn't have been invented, but now we're stuck. -HB */
00326 /* The resulting object has the same kind as the original.            */
00327 /* If the argument is stubborn, the result will have changes enabled. */
00328 /* It is an error to have changes enabled for the original object.    */
00329 /* Follows ANSI comventions for NULL old_object.               */
00330 GC_API GC_PTR GC_realloc
00331        GC_PROTO((GC_PTR old_object, size_t new_size_in_bytes));
00332                                
00333 /* Explicitly increase the heap size.     */
00334 /* Returns 0 on failure, 1 on success.  */
00335 GC_API int GC_expand_hp GC_PROTO((size_t number_of_bytes));
00336 
00337 /* Limit the heap size to n bytes.  Useful when you're debugging,     */
00338 /* especially on systems that don't handle running out of memory well.       */
00339 /* n == 0 ==> unbounded.  This is the default.                        */
00340 GC_API void GC_set_max_heap_size GC_PROTO((GC_word n));
00341 
00342 /* Inform the collector that a certain section of statically allocated       */
00343 /* memory contains no pointers to garbage collected memory.  Thus it  */
00344 /* need not be scanned.  This is sometimes important if the application */
00345 /* maps large read/write files into the address space, which could be */
00346 /* mistaken for dynamic library data segments on some systems.        */
00347 GC_API void GC_exclude_static_roots GC_PROTO((GC_PTR start, GC_PTR finish));
00348 
00349 /* Clear the set of root segments.  Wizards only. */
00350 GC_API void GC_clear_roots GC_PROTO((void));
00351 
00352 /* Add a root segment.  Wizards only. */
00353 GC_API void GC_add_roots GC_PROTO((char * low_address,
00354                                char * high_address_plus_1));
00355 
00356 /* Remove a root segment.  Wizards only. */
00357 GC_API void GC_remove_roots GC_PROTO((char * low_address, 
00358     char * high_address_plus_1));
00359 
00360 /* Add a displacement to the set of those considered valid by the     */
00361 /* collector.  GC_register_displacement(n) means that if p was returned */
00362 /* by GC_malloc, then (char *)p + n will be considered to be a valid  */
00363 /* pointer to p.  N must be small and less than the size of p.        */
00364 /* (All pointers to the interior of objects from the stack are        */
00365 /* considered valid in any case.  This applies to heap objects and    */
00366 /* static data.)                                               */
00367 /* Preferably, this should be called before any other GC procedures.  */
00368 /* Calling it later adds to the probability of excess memory          */
00369 /* retention.                                                  */
00370 /* This is a no-op if the collector has recognition of                */
00371 /* arbitrary interior pointers enabled, which is now the default.     */
00372 GC_API void GC_register_displacement GC_PROTO((GC_word n));
00373 
00374 /* The following version should be used if any debugging allocation is       */
00375 /* being done.                                                        */
00376 GC_API void GC_debug_register_displacement GC_PROTO((GC_word n));
00377 
00378 /* Explicitly trigger a full, world-stop collection.    */
00379 GC_API void GC_gcollect GC_PROTO((void));
00380 
00381 /* Trigger a full world-stopped collection.  Abort the collection if  */
00382 /* and when stop_func returns a nonzero value.  Stop_func will be     */
00383 /* called frequently, and should be reasonably fast.  This works even */
00384 /* if virtual dirty bits, and hence incremental collection is not     */
00385 /* available for this architecture.  Collections can be aborted faster       */
00386 /* than normal pause times for incremental collection.  However,      */
00387 /* aborted collections do no useful work; the next collection needs   */
00388 /* to start from the beginning.                                       */
00389 /* Return 0 if the collection was aborted, 1 if it succeeded.         */
00390 typedef int (* GC_stop_func) GC_PROTO((void));
00391 GC_API int GC_try_to_collect GC_PROTO((GC_stop_func stop_func));
00392 
00393 /* Return the number of bytes in the heap.  Excludes collector private       */
00394 /* data structures.  Includes empty blocks and fragmentation loss.    */
00395 /* Includes some pages that were allocated but never written.         */
00396 GC_API size_t GC_get_heap_size GC_PROTO((void));
00397 
00398 /* Return a lower bound on the number of free bytes in the heap.      */
00399 GC_API size_t GC_get_free_bytes GC_PROTO((void));
00400 
00401 /* Return the number of bytes allocated since the last collection.    */
00402 GC_API size_t GC_get_bytes_since_gc GC_PROTO((void));
00403 
00404 /* Return the total number of bytes allocated in this process.        */
00405 /* Never decreases, except due to wrapping.                           */
00406 GC_API size_t GC_get_total_bytes GC_PROTO((void));
00407 
00408 /* Disable garbage collection.  Even GC_gcollect calls will be               */
00409 /* ineffective.                                                       */
00410 GC_API void GC_disable GC_PROTO((void));
00411 
00412 /* Reenable garbage collection.  GC_disable() and GC_enable() calls   */
00413 /* nest.  Garbage collection is enabled if the number of calls to both       */
00414 /* both functions is equal.                                    */
00415 GC_API void GC_enable GC_PROTO((void));
00416 
00417 /* Enable incremental/generational collection.   */
00418 /* Not advisable unless dirty bits are           */
00419 /* available or most heap objects are            */
00420 /* pointerfree(atomic) or immutable.             */
00421 /* Don't use in leak finding mode.        */
00422 /* Ignored if GC_dont_gc is true.         */
00423 /* Only the generational piece of this is */
00424 /* functional if GC_parallel is TRUE             */
00425 /* or if GC_time_limit is GC_TIME_UNLIMITED.     */
00426 /* Causes GC_local_gcj_malloc() to revert to     */
00427 /* locked allocation.  Must be called            */
00428 /* before any GC_local_gcj_malloc() calls.       */
00429 GC_API void GC_enable_incremental GC_PROTO((void));
00430 
00431 /* Does incremental mode write-protect pages?  Returns zero or */
00432 /* more of the following, or'ed together:               */
00433 #define GC_PROTECTS_POINTER_HEAP  1 /* May protect non-atomic objs.   */
00434 #define GC_PROTECTS_PTRFREE_HEAP  2
00435 #define GC_PROTECTS_STATIC_DATA   4 /* Curently never.                */
00436 #define GC_PROTECTS_STACK     8 /* Probably impractical.              */
00437 
00438 #define GC_PROTECTS_NONE 0
00439 GC_API int GC_incremental_protection_needs GC_PROTO((void));
00440 
00441 /* Perform some garbage collection work, if appropriate.       */
00442 /* Return 0 if there is no more work to be done.        */
00443 /* Typically performs an amount of work corresponding roughly  */
00444 /* to marking from one page.  May do more work if further      */
00445 /* progress requires it, e.g. if incremental collection is     */
00446 /* disabled.  It is reasonable to call this in a wait loop     */
00447 /* until it returns 0.                                         */
00448 GC_API int GC_collect_a_little GC_PROTO((void));
00449 
00450 /* Allocate an object of size lb bytes.  The client guarantees that   */
00451 /* as long as the object is live, it will be referenced by a pointer  */
00452 /* that points to somewhere within the first 256 bytes of the object. */
00453 /* (This should normally be declared volatile to prevent the compiler */
00454 /* from invalidating this assertion.)  This routine is only useful    */
00455 /* if a large array is being allocated.  It reduces the chance of     */
00456 /* accidentally retaining such an array as a result of scanning an    */
00457 /* integer that happens to be an address inside the array.  (Actually,       */
00458 /* it reduces the chance of the allocator not finding space for such  */
00459 /* an array, since it will try hard to avoid introducing such a false */
00460 /* reference.)  On a SunOS 4.X or MS Windows system this is recommended */
00461 /* for arrays likely to be larger than 100K or so.  For other systems,       */
00462 /* or if the collector is not configured to recognize all interior    */
00463 /* pointers, the threshold is normally much higher.                   */
00464 GC_API GC_PTR GC_malloc_ignore_off_page GC_PROTO((size_t lb));
00465 GC_API GC_PTR GC_malloc_atomic_ignore_off_page GC_PROTO((size_t lb));
00466 
00467 #if defined(__sgi) && !defined(__GNUC__) && _COMPILER_VERSION >= 720
00468 #   define GC_ADD_CALLER
00469 #   define GC_RETURN_ADDR (GC_word)__return_address
00470 #endif
00471 
00472 #ifdef __linux__
00473 # include <features.h>
00474 # if (__GLIBC__ == 2 && __GLIBC_MINOR__ >= 1 || __GLIBC__ > 2) \
00475      && !defined(__ia64__)
00476 #   ifndef GC_HAVE_BUILTIN_BACKTRACE
00477 #     define GC_HAVE_BUILTIN_BACKTRACE
00478 #   endif
00479 # endif
00480 # if defined(__i386__) || defined(__x86_64__)
00481 #   define GC_CAN_SAVE_CALL_STACKS
00482 # endif
00483 #endif
00484 
00485 #if defined(GC_HAVE_BUILTIN_BACKTRACE) && !defined(GC_CAN_SAVE_CALL_STACKS)
00486 # define GC_CAN_SAVE_CALL_STACKS
00487 #endif
00488 
00489 #if defined(__sparc__)
00490 #   define GC_CAN_SAVE_CALL_STACKS
00491 #endif
00492 
00493 /* If we're on an a platform on which we can't save call stacks, but  */
00494 /* gcc is normally used, we go ahead and define GC_ADD_CALLER.        */
00495 /* We make this decision independent of whether gcc is actually being */
00496 /* used, in order to keep the interface consistent, and allow mixing  */
00497 /* of compilers.                                               */
00498 /* This may also be desirable if it is possible but expensive to      */
00499 /* retrieve the call chain.                                    */
00500 #if (defined(__linux__) || defined(__NetBSD__) || defined(__OpenBSD__) \
00501      || defined(__FreeBSD__)) & !defined(GC_CAN_SAVE_CALL_STACKS)
00502 # define GC_ADD_CALLER
00503 # if __GNUC__ >= 3 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 95) 
00504     /* gcc knows how to retrieve return address, but we don't know */
00505     /* how to generate call stacks.                               */
00506 #   define GC_RETURN_ADDR (GC_word)__builtin_return_address(0)
00507 # else
00508     /* Just pass 0 for gcc compatibility. */
00509 #   define GC_RETURN_ADDR 0
00510 # endif
00511 #endif
00512 
00513 #ifdef GC_ADD_CALLER
00514 #  define GC_EXTRAS GC_RETURN_ADDR, __FILE__, __LINE__
00515 #  define GC_EXTRA_PARAMS GC_word ra, GC_CONST char * s, int i
00516 #else
00517 #  define GC_EXTRAS __FILE__, __LINE__
00518 #  define GC_EXTRA_PARAMS GC_CONST char * s, int i
00519 #endif
00520 
00521 /* Debugging (annotated) allocation.  GC_gcollect will check          */
00522 /* objects allocated in this way for overwrites, etc.                 */
00523 GC_API GC_PTR GC_debug_malloc
00524        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00525 GC_API GC_PTR GC_debug_malloc_atomic
00526        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00527 GC_API char *GC_debug_strdup
00528        GC_PROTO((const char *str, GC_EXTRA_PARAMS));
00529 GC_API GC_PTR GC_debug_malloc_uncollectable
00530        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00531 GC_API GC_PTR GC_debug_malloc_stubborn
00532        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00533 GC_API GC_PTR GC_debug_malloc_ignore_off_page
00534        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00535 GC_API GC_PTR GC_debug_malloc_atomic_ignore_off_page
00536        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00537 GC_API void GC_debug_free GC_PROTO((GC_PTR object_addr));
00538 GC_API GC_PTR GC_debug_realloc
00539        GC_PROTO((GC_PTR old_object, size_t new_size_in_bytes,
00540                 GC_EXTRA_PARAMS));
00541 GC_API void GC_debug_change_stubborn GC_PROTO((GC_PTR));
00542 GC_API void GC_debug_end_stubborn_change GC_PROTO((GC_PTR));
00543 
00544 /* Routines that allocate objects with debug information (like the    */
00545 /* above), but just fill in dummy file and line number information.   */
00546 /* Thus they can serve as drop-in malloc/realloc replacements.  This  */
00547 /* can be useful for two reasons:                                     */
00548 /* 1) It allows the collector to be built with DBG_HDRS_ALL defined   */
00549 /*    even if some allocation calls come from 3rd party libraries     */
00550 /*    that can't be recompiled.                                       */
00551 /* 2) On some platforms, the file and line information is redundant,  */
00552 /*    since it can be reconstructed from a stack trace.  On such      */
00553 /*    platforms it may be more convenient not to recompile, e.g. for  */
00554 /*    leak detection.  This can be accomplished by instructing the    */
00555 /*    linker to replace malloc/realloc with these.                    */
00556 GC_API GC_PTR GC_debug_malloc_replacement GC_PROTO((size_t size_in_bytes));
00557 GC_API GC_PTR GC_debug_realloc_replacement
00558              GC_PROTO((GC_PTR object_addr, size_t size_in_bytes));
00559                              
00560 # ifdef GC_DEBUG
00561 #   define GC_MALLOC(sz) GC_debug_malloc(sz, GC_EXTRAS)
00562 #   define GC_MALLOC_ATOMIC(sz) GC_debug_malloc_atomic(sz, GC_EXTRAS)
00563 #   define GC_STRDUP(s) GC_debug_strdup((s), GC_EXTRAS)
00564 #   define GC_MALLOC_UNCOLLECTABLE(sz) \
00565                      GC_debug_malloc_uncollectable(sz, GC_EXTRAS)
00566 #   define GC_MALLOC_IGNORE_OFF_PAGE(sz) \
00567                      GC_debug_malloc_ignore_off_page(sz, GC_EXTRAS)
00568 #   define GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(sz) \
00569                      GC_debug_malloc_atomic_ignore_off_page(sz, GC_EXTRAS)
00570 #   define GC_REALLOC(old, sz) GC_debug_realloc(old, sz, GC_EXTRAS)
00571 #   define GC_FREE(p) GC_debug_free(p)
00572 #   define GC_REGISTER_FINALIZER(p, f, d, of, od) \
00573        GC_debug_register_finalizer(p, f, d, of, od)
00574 #   define GC_REGISTER_FINALIZER_IGNORE_SELF(p, f, d, of, od) \
00575        GC_debug_register_finalizer_ignore_self(p, f, d, of, od)
00576 #   define GC_REGISTER_FINALIZER_NO_ORDER(p, f, d, of, od) \
00577        GC_debug_register_finalizer_no_order(p, f, d, of, od)
00578 #   define GC_MALLOC_STUBBORN(sz) GC_debug_malloc_stubborn(sz, GC_EXTRAS);
00579 #   define GC_CHANGE_STUBBORN(p) GC_debug_change_stubborn(p)
00580 #   define GC_END_STUBBORN_CHANGE(p) GC_debug_end_stubborn_change(p)
00581 #   define GC_GENERAL_REGISTER_DISAPPEARING_LINK(link, obj) \
00582        GC_general_register_disappearing_link(link, GC_base(obj))
00583 #   define GC_REGISTER_DISPLACEMENT(n) GC_debug_register_displacement(n)
00584 # else
00585 #   define GC_MALLOC(sz) GC_malloc(sz)
00586 #   define GC_MALLOC_ATOMIC(sz) GC_malloc_atomic(sz)
00587 #   define GC_STRDUP(s) GC_strdup(s)
00588 #   define GC_MALLOC_UNCOLLECTABLE(sz) GC_malloc_uncollectable(sz)
00589 #   define GC_MALLOC_IGNORE_OFF_PAGE(sz) \
00590                      GC_malloc_ignore_off_page(sz)
00591 #   define GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(sz) \
00592                      GC_malloc_atomic_ignore_off_page(sz)
00593 #   define GC_REALLOC(old, sz) GC_realloc(old, sz)
00594 #   define GC_FREE(p) GC_free(p)
00595 #   define GC_REGISTER_FINALIZER(p, f, d, of, od) \
00596        GC_register_finalizer(p, f, d, of, od)
00597 #   define GC_REGISTER_FINALIZER_IGNORE_SELF(p, f, d, of, od) \
00598        GC_register_finalizer_ignore_self(p, f, d, of, od)
00599 #   define GC_REGISTER_FINALIZER_NO_ORDER(p, f, d, of, od) \
00600        GC_register_finalizer_no_order(p, f, d, of, od)
00601 #   define GC_MALLOC_STUBBORN(sz) GC_malloc_stubborn(sz)
00602 #   define GC_CHANGE_STUBBORN(p) GC_change_stubborn(p)
00603 #   define GC_END_STUBBORN_CHANGE(p) GC_end_stubborn_change(p)
00604 #   define GC_GENERAL_REGISTER_DISAPPEARING_LINK(link, obj) \
00605        GC_general_register_disappearing_link(link, obj)
00606 #   define GC_REGISTER_DISPLACEMENT(n) GC_register_displacement(n)
00607 # endif
00608 /* The following are included because they are often convenient, and  */
00609 /* reduce the chance for a misspecifed size argument.  But calls may  */
00610 /* expand to something syntactically incorrect if t is a complicated  */
00611 /* type expression.                                                   */
00612 # define GC_NEW(t) (t *)GC_MALLOC(sizeof (t))
00613 # define GC_NEW_ATOMIC(t) (t *)GC_MALLOC_ATOMIC(sizeof (t))
00614 # define GC_NEW_STUBBORN(t) (t *)GC_MALLOC_STUBBORN(sizeof (t))
00615 # define GC_NEW_UNCOLLECTABLE(t) (t *)GC_MALLOC_UNCOLLECTABLE(sizeof (t))
00616 
00617 /* Finalization.  Some of these primitives are grossly unsafe.        */
00618 /* The idea is to make them both cheap, and sufficient to build              */
00619 /* a safer layer, closer to Modula-3, Java, or PCedar finalization.   */
00620 /* The interface represents my conclusions from a long discussion     */
00621 /* with Alan Demers, Dan Greene, Carl Hauser, Barry Hayes,            */
00622 /* Christian Jacobi, and Russ Atkinson.  It's not perfect, and        */
00623 /* probably nobody else agrees with it.       Hans-J. Boehm  3/13/92  */
00624 typedef void (*GC_finalization_proc)
00625        GC_PROTO((GC_PTR obj, GC_PTR client_data));
00626 
00627 GC_API void GC_register_finalizer
00628        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00629                 GC_finalization_proc *ofn, GC_PTR *ocd));
00630 GC_API void GC_debug_register_finalizer
00631        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00632                 GC_finalization_proc *ofn, GC_PTR *ocd));
00633        /* When obj is no longer accessible, invoke             */
00634        /* (*fn)(obj, cd).  If a and b are inaccessible, and    */
00635        /* a points to b (after disappearing links have been    */
00636        /* made to disappear), then only a will be              */
00637        /* finalized.  (If this does not create any new         */
00638        /* pointers to b, then b will be finalized after the    */
00639        /* next collection.)  Any finalizable object that       */
00640        /* is reachable from itself by following one or more    */
00641        /* pointers will not be finalized (or collected).       */
00642        /* Thus cycles involving finalizable objects should     */
00643        /* be avoided, or broken by disappearing links.         */
00644        /* All but the last finalizer registered for an object  */
00645        /* is ignored.                                          */
00646        /* Finalization may be removed by passing 0 as fn.      */
00647        /* Finalizers are implicitly unregistered just before   */
00648        /* they are invoked.                             */
00649        /* The old finalizer and client data are stored in      */
00650        /* *ofn and *ocd.                                */ 
00651        /* Fn is never invoked on an accessible object,         */
00652        /* provided hidden pointers are converted to real       */
00653        /* pointers only if the allocation lock is held, and    */
00654        /* such conversions are not performed by finalization   */
00655        /* routines.                                     */
00656        /* If GC_register_finalizer is aborted as a result of   */
00657        /* a signal, the object may be left with no             */
00658        /* finalization, even if neither the old nor new */
00659        /* finalizer were NULL.                                 */
00660        /* Obj should be the nonNULL starting address of an     */
00661        /* object allocated by GC_malloc or friends.            */
00662        /* Note that any garbage collectable object referenced  */
00663        /* by cd will be considered accessible until the */
00664        /* finalizer is invoked.                         */
00665 
00666 /* Another versions of the above follow.  It ignores           */
00667 /* self-cycles, i.e. pointers from a finalizable object to     */
00668 /* itself.  There is a stylistic argument that this is wrong,  */
00669 /* but it's unavoidable for C++, since the compiler may        */
00670 /* silently introduce these.  It's also benign in that specific       */
00671 /* case.  And it helps if finalizable objects are split to     */
00672 /* avoid cycles.                                        */
00673 /* Note that cd will still be viewed as accessible, even if it */
00674 /* refers to the object itself.                                */
00675 GC_API void GC_register_finalizer_ignore_self
00676        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00677                 GC_finalization_proc *ofn, GC_PTR *ocd));
00678 GC_API void GC_debug_register_finalizer_ignore_self
00679        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00680                 GC_finalization_proc *ofn, GC_PTR *ocd));
00681 
00682 /* Another version of the above.  It ignores all cycles.        */
00683 /* It should probably only be used by Java implementations.     */
00684 /* Note that cd will still be viewed as accessible, even if it */
00685 /* refers to the object itself.                                */
00686 GC_API void GC_register_finalizer_no_order
00687        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00688                 GC_finalization_proc *ofn, GC_PTR *ocd));
00689 GC_API void GC_debug_register_finalizer_no_order
00690        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00691                 GC_finalization_proc *ofn, GC_PTR *ocd));
00692 
00693 
00694 /* PLTSCHEME: eager finalizers do not care about cycles at all.
00695    The intent is for guardian-like and will-like uses where
00696    the object will always be made immediately live again, but
00697    some action needed to be triggered by the object's (possibly
00698    temporary) unreachableness. */
00699 GC_API void GC_register_eager_finalizer
00700        GC_PROTO((GC_PTR obj, int eager_level,
00701                   GC_finalization_proc fn, GC_PTR cd,
00702                 GC_finalization_proc *ofn, GC_PTR *ocd));
00703 
00704 /* The following routine may be used to break cycles between   */
00705 /* finalizable objects, thus causing cyclic finalizable        */
00706 /* objects to be finalized in the correct order.  Standard     */
00707 /* use involves calling GC_register_disappearing_link(&p),     */
00708 /* where p is a pointer that is not followed by finalization   */
00709 /* code, and should not be considered in determining           */
00710 /* finalization order.                                         */
00711 GC_API int GC_register_disappearing_link GC_PROTO((GC_PTR * /* link */));
00712        /* Link should point to a field of a heap allocated     */
00713        /* object obj.  *link will be cleared when obj is       */
00714        /* found to be inaccessible.  This happens BEFORE any   */
00715        /* finalization code is invoked, and BEFORE any         */
00716        /* decisions about finalization order are made.         */
00717        /* This is useful in telling the finalizer that  */
00718        /* some pointers are not essential for proper           */
00719        /* finalization.  This may avoid finalization cycles.   */
00720        /* Note that obj may be resurrected by another          */
00721        /* finalizer, and thus the clearing of *link may */
00722        /* be visible to non-finalization code.          */
00723        /* There's an argument that an arbitrary action should  */
00724        /* be allowed here, instead of just clearing a pointer. */
00725        /* But this causes problems if that action alters, or   */
00726        /* examines connectivity.                        */
00727        /* Returns 1 if link was already registered, 0          */
00728        /* otherwise.                                    */
00729        /* Only exists for backward compatibility.  See below:  */
00730        
00731 GC_API int GC_general_register_disappearing_link
00732        GC_PROTO((GC_PTR * /* link */, GC_PTR obj));
00733        /* A slight generalization of the above. *link is       */
00734        /* cleared when obj first becomes inaccessible.  This   */
00735        /* can be used to implement weak pointers easily and    */
00736        /* safely. Typically link will point to a location      */
00737        /* holding a disguised pointer to obj.  (A pointer      */
00738        /* inside an "atomic" object is effectively             */
00739        /* disguised.)   In this way soft                */
00740        /* pointers are broken before any object         */
00741        /* reachable from them are finalized.  Each link */
00742        /* May be registered only once, i.e. with one obj       */
00743        /* value.  This was added after a long email discussion */
00744        /* with John Ellis.                              */
00745        /* Obj must be a pointer to the first word of an object */
00746        /* we allocated.  It is unsafe to explicitly deallocate */
00747        /* the object containing link.  Explicitly deallocating */
00748        /* obj may or may not cause link to eventually be       */
00749        /* cleared.                                      */
00750 GC_API int GC_unregister_disappearing_link GC_PROTO((GC_PTR * /* link */));
00751        /* Returns 0 if link was not actually registered.       */
00752        /* Undoes a registration by either of the above two     */
00753        /* routines.                                     */
00754 
00755 /* Returns !=0  if GC_invoke_finalizers has something to do.          */
00756 GC_API int GC_should_invoke_finalizers GC_PROTO((void));
00757 
00758 GC_API int GC_invoke_finalizers GC_PROTO((void));
00759        /* Run finalizers for all objects that are ready to     */
00760        /* be finalized.  Return the number of finalizers       */
00761        /* that were run.  Normally this is also called         */
00762        /* implicitly during some allocations.    If            */
00763        /* GC-finalize_on_demand is nonzero, it must be called  */
00764        /* explicitly.                                          */
00765 
00766 /* GC_set_warn_proc can be used to redirect or filter warning messages.      */
00767 /* p may not be a NULL pointer.                                       */
00768 typedef void (*GC_warn_proc) GC_PROTO((char *msg, GC_word arg));
00769 GC_API GC_warn_proc GC_set_warn_proc GC_PROTO((GC_warn_proc p));
00770     /* Returns old warning procedure.     */
00771 
00772 GC_API GC_word GC_set_free_space_divisor GC_PROTO((GC_word value));
00773     /* Set free_space_divisor.  See above for definition.      */
00774     /* Returns old value.                               */
00775        
00776 /* The following is intended to be used by a higher level      */
00777 /* (e.g. Java-like) finalization facility.  It is expected     */
00778 /* that finalization code will arrange for hidden pointers to  */
00779 /* disappear.  Otherwise objects can be accessed after they    */
00780 /* have been collected.                                        */
00781 /* Note that putting pointers in atomic objects or in          */
00782 /* nonpointer slots of "typed" objects is equivalent to        */
00783 /* disguising them in this way, and may have other advantages. */
00784 # if defined(I_HIDE_POINTERS) || defined(GC_I_HIDE_POINTERS)
00785     typedef GC_word GC_hidden_pointer;
00786 #   define HIDE_POINTER(p) (~(GC_hidden_pointer)(p))
00787 #   define REVEAL_POINTER(p) ((GC_PTR)(HIDE_POINTER(p)))
00788     /* Converting a hidden pointer to a real pointer requires verifying      */
00789     /* that the object still exists.  This involves acquiring the     */
00790     /* allocator lock to avoid a race with the collector.             */
00791 # endif /* I_HIDE_POINTERS */
00792 
00793 typedef GC_PTR (*GC_fn_type) GC_PROTO((GC_PTR client_data));
00794 GC_API GC_PTR GC_call_with_alloc_lock
00795               GC_PROTO((GC_fn_type fn, GC_PTR client_data));
00796 
00797 /* The following routines are primarily intended for use with a       */
00798 /* preprocessor which inserts calls to check C pointer arithmetic.    */
00799 /* They indicate failure by invoking the corresponding _print_proc.   */
00800 
00801 /* Check that p and q point to the same object.                */
00802 /* Fail conspicuously if they don't.                           */
00803 /* Returns the first argument.                          */
00804 /* Succeeds if neither p nor q points to the heap.             */
00805 /* May succeed if both p and q point to between heap objects.  */
00806 GC_API GC_PTR GC_same_obj GC_PROTO((GC_PTR p, GC_PTR q));
00807 
00808 /* Checked pointer pre- and post- increment operations.  Note that    */
00809 /* the second argument is in units of bytes, not multiples of the     */
00810 /* object size.  This should either be invoked from a macro, or the   */
00811 /* call should be automatically generated.                            */
00812 GC_API GC_PTR GC_pre_incr GC_PROTO((GC_PTR *p, size_t how_much));
00813 GC_API GC_PTR GC_post_incr GC_PROTO((GC_PTR *p, size_t how_much));
00814 
00815 /* Check that p is visible                                     */
00816 /* to the collector as a possibly pointer containing location.        */
00817 /* If it isn't fail conspicuously.                             */
00818 /* Returns the argument in all cases.  May erroneously succeed        */
00819 /* in hard cases.  (This is intended for debugging use with           */
00820 /* untyped allocations.  The idea is that it should be possible, though      */
00821 /* slow, to add such a call to all indirect pointer stores.)          */
00822 /* Currently useless for multithreaded worlds.                        */
00823 GC_API GC_PTR GC_is_visible GC_PROTO((GC_PTR p));
00824 
00825 /* Check that if p is a pointer to a heap page, then it points to     */
00826 /* a valid displacement within a heap object.                         */
00827 /* Fail conspicuously if this property does not hold.                 */
00828 /* Uninteresting with GC_all_interior_pointers.                       */
00829 /* Always returns its argument.                                       */
00830 GC_API GC_PTR GC_is_valid_displacement GC_PROTO((GC_PTR p));
00831 
00832 /* Safer, but slow, pointer addition.  Probably useful mainly with    */
00833 /* a preprocessor.  Useful only for heap pointers.                    */
00834 #ifdef GC_DEBUG
00835 #   define GC_PTR_ADD3(x, n, type_of_result) \
00836        ((type_of_result)GC_same_obj((x)+(n), (x)))
00837 #   define GC_PRE_INCR3(x, n, type_of_result) \
00838        ((type_of_result)GC_pre_incr(&(x), (n)*sizeof(*x))
00839 #   define GC_POST_INCR2(x, type_of_result) \
00840        ((type_of_result)GC_post_incr(&(x), sizeof(*x))
00841 #   ifdef __GNUC__
00842 #       define GC_PTR_ADD(x, n) \
00843            GC_PTR_ADD3(x, n, typeof(x))
00844 #       define GC_PRE_INCR(x, n) \
00845            GC_PRE_INCR3(x, n, typeof(x))
00846 #       define GC_POST_INCR(x, n) \
00847            GC_POST_INCR3(x, typeof(x))
00848 #   else
00849        /* We can't do this right without typeof, which ANSI    */
00850        /* decided was not sufficiently useful.  Repeatedly     */
00851        /* mentioning the arguments seems too dangerous to be   */
00852        /* useful.  So does not casting the result.             */
00853 #      define GC_PTR_ADD(x, n) ((x)+(n))
00854 #   endif
00855 #else  /* !GC_DEBUG */
00856 #   define GC_PTR_ADD3(x, n, type_of_result) ((x)+(n))
00857 #   define GC_PTR_ADD(x, n) ((x)+(n))
00858 #   define GC_PRE_INCR3(x, n, type_of_result) ((x) += (n))
00859 #   define GC_PRE_INCR(x, n) ((x) += (n))
00860 #   define GC_POST_INCR2(x, n, type_of_result) ((x)++)
00861 #   define GC_POST_INCR(x, n) ((x)++)
00862 #endif
00863 
00864 /* Safer assignment of a pointer to a nonstack location.       */
00865 #ifdef GC_DEBUG
00866 # if defined(__STDC__) || defined(_AIX)
00867 #   define GC_PTR_STORE(p, q) \
00868        (*(void **)GC_is_visible(p) = GC_is_valid_displacement(q))
00869 # else
00870 #   define GC_PTR_STORE(p, q) \
00871        (*(char **)GC_is_visible(p) = GC_is_valid_displacement(q))
00872 # endif
00873 #else /* !GC_DEBUG */
00874 #   define GC_PTR_STORE(p, q) *((p) = (q))
00875 #endif
00876 
00877 /* Functions called to report pointer checking errors */
00878 GC_API void (*GC_same_obj_print_proc) GC_PROTO((GC_PTR p, GC_PTR q));
00879 
00880 GC_API void (*GC_is_valid_displacement_print_proc)
00881        GC_PROTO((GC_PTR p));
00882 
00883 GC_API void (*GC_is_visible_print_proc)
00884        GC_PROTO((GC_PTR p));
00885 
00886 
00887 /* For pthread support, we generally need to intercept a number of    */
00888 /* thread library calls.  We do that here by macro defining them.     */
00889 
00890 #if !defined(GC_USE_LD_WRAP) && \
00891     (defined(GC_PTHREADS) || defined(GC_SOLARIS_THREADS))
00892 # include "gc_pthread_redirects.h"
00893 #endif
00894 
00895 # if defined(PCR) || defined(GC_SOLARIS_THREADS) || \
00896      defined(GC_PTHREADS) || defined(GC_WIN32_THREADS)
00897        /* Any flavor of threads except SRC_M3.   */
00898 /* This returns a list of objects, linked through their first         */
00899 /* word.  Its use can greatly reduce lock contention problems, since  */
00900 /* the allocation lock can be acquired and released many fewer times. */
00901 /* lb must be large enough to hold the pointer field.                 */
00902 /* It is used internally by gc_local_alloc.h, which provides a simpler       */
00903 /* programming interface on Linux.                             */
00904 GC_PTR GC_malloc_many(size_t lb);
00905 #define GC_NEXT(p) (*(GC_PTR *)(p))       /* Retrieve the next element       */
00906                                    /* in returned list.        */
00907 extern void GC_thr_init GC_PROTO((void));/* Needed for Solaris/X86    */
00908 
00909 #endif /* THREADS && !SRC_M3 */
00910 
00911 #if defined(GC_WIN32_THREADS) && !defined(__CYGWIN32__) && !defined(__CYGWIN__)
00912 # include <windows.h>
00913 
00914   /*
00915    * All threads must be created using GC_CreateThread, so that they will be
00916    * recorded in the thread table.  For backwards compatibility, this is not
00917    * technically true if the GC is built as a dynamic library, since it can
00918    * and does then use DllMain to keep track of thread creations.  But new code
00919    * should be built to call GC_CreateThread.
00920    */
00921    GC_API HANDLE WINAPI GC_CreateThread(
00922       LPSECURITY_ATTRIBUTES lpThreadAttributes,
00923       DWORD dwStackSize, LPTHREAD_START_ROUTINE lpStartAddress,
00924       LPVOID lpParameter, DWORD dwCreationFlags, LPDWORD lpThreadId );
00925 
00926 # if defined(_WIN32_WCE)
00927   /*
00928    * win32_threads.c implements the real WinMain, which will start a new thread
00929    * to call GC_WinMain after initializing the garbage collector.
00930    */
00931   int WINAPI GC_WinMain(
00932       HINSTANCE hInstance,
00933       HINSTANCE hPrevInstance,
00934       LPWSTR lpCmdLine,
00935       int nCmdShow );
00936 
00937 #  ifndef GC_BUILD
00938 #    define WinMain GC_WinMain
00939 #    define CreateThread GC_CreateThread
00940 #  endif
00941 # endif /* defined(_WIN32_WCE) */
00942 
00943 #endif /* defined(GC_WIN32_THREADS)  && !cygwin */
00944 
00945  /*
00946   * Fully portable code should call GC_INIT() from the main program
00947   * before making any other GC_ calls.  On most platforms this is a
00948   * no-op and the collector self-initializes.  But a number of platforms
00949   * make that too hard.
00950   */
00951 #if (defined(sparc) || defined(__sparc)) && defined(sun)
00952     /*
00953      * If you are planning on putting
00954      * the collector in a SunOS 5 dynamic library, you need to call GC_INIT()
00955      * from the statically loaded program section.
00956      * This circumvents a Solaris 2.X (X<=4) linker bug.
00957      */
00958 #   ifdef __cplusplus
00959 #     define GC_INIT() { extern int _end[], _etext[]; \
00960                        extern "C" void GC_noop1(GC_word); \
00961                        GC_noop1((GC_word)_end); \
00962                       GC_noop1((GC_word)_etext); }
00963 #   else
00964 #     define GC_INIT() { extern int _end[], _etext[]; \
00965                        extern void GC_noop(); \
00966                        GC_noop(_end, _etext); }
00967 #   endif /* !__cplusplus */
00968 #else
00969 # if defined(__CYGWIN32__) || defined (_AIX)
00970     /*
00971      * Similarly gnu-win32 DLLs need explicit initialization from
00972      * the main program, as does AIX.
00973      */
00974 #   ifdef __CYGWIN32__
00975       extern int _data_start__[];
00976       extern int _data_end__[];
00977       extern int _bss_start__[];
00978       extern int _bss_end__[];
00979 #     define GC_MAX(x,y) ((x) > (y) ? (x) : (y))
00980 #     define GC_MIN(x,y) ((x) < (y) ? (x) : (y))
00981 #     define GC_DATASTART ((GC_PTR) GC_MIN(_data_start__, _bss_start__))
00982 #     define GC_DATAEND      ((GC_PTR) GC_MAX(_data_end__, _bss_end__))
00983 #     ifdef GC_DLL
00984 #       define GC_INIT() { GC_add_roots(GC_DATASTART, GC_DATAEND); }
00985 #     else
00986 #       define GC_INIT()
00987 #     endif
00988 #   endif
00989 #   if defined(_AIX)
00990       extern int _data[], _end[];
00991 #     define GC_DATASTART ((GC_PTR)((ulong)_data))
00992 #     define GC_DATAEND ((GC_PTR)((ulong)_end))
00993 #     define GC_INIT() { GC_add_roots(GC_DATASTART, GC_DATAEND); }
00994 #   endif
00995 # else
00996 #  if defined(__APPLE__) && defined(__MACH__) || defined(GC_WIN32_THREADS)
00997 #   define GC_INIT() { GC_init(); }
00998 #  else
00999 #   define GC_INIT()
01000 #  endif /* !__MACH && !GC_WIN32_THREADS */
01001 # endif /* !AIX && !cygwin */
01002 #endif /* !sparc */
01003 
01004 #if !defined(_WIN32_WCE) \
01005     && ((defined(_MSDOS) || defined(_MSC_VER)) && (_M_IX86 >= 300) \
01006         || defined(_WIN32) && !defined(__CYGWIN32__) && !defined(__CYGWIN__))
01007   /* win32S may not free all resources on process exit.  */
01008   /* This explicitly deallocates the heap.               */
01009     GC_API void GC_win32_free_heap ();
01010 #endif
01011 
01012 #if ( defined(_AMIGA) && !defined(GC_AMIGA_MAKINGLIB) )
01013   /* Allocation really goes through GC_amiga_allocwrapper_do */
01014 # include "gc_amiga_redirects.h"
01015 #endif
01016 
01017 #if defined(GC_REDIRECT_TO_LOCAL) && !defined(GC_LOCAL_ALLOC_H)
01018 #  include  "gc_local_alloc.h"
01019 #endif
01020 typedef void (*GC_collect_start_callback_Proc)(void);
01021 typedef void (*GC_collect_end_callback_Proc)(void);
01022 
01023 /* PLTSCHEME: */
01024 GC_API void (*GC_custom_finalize)(void);
01025 GC_API void (*GC_push_last_roots)(void);
01026 GC_API void (*GC_push_last_roots_again)(void);
01027 GC_API GC_collect_start_callback_Proc GC_set_collect_start_callback(GC_collect_start_callback_Proc);
01028 GC_API GC_collect_end_callback_Proc GC_set_collect_end_callback(GC_collect_end_callback_Proc);
01029 GC_API void (*GC_out_of_memory)(void);
01030 GC_API int GC_did_mark_stack_overflow(void);
01031 GC_API void GC_mark_from_mark_stack(void);
01032 GC_API void GC_mark_overflow_recover(void *p);
01033 GC_API void GC_flush_mark_stack(void);
01034 GC_API long GC_get_memory_use(void);
01035 GC_API void GC_pre_init(void);
01036 
01037 #ifdef __cplusplus
01038     }  /* end of extern "C" */
01039 #endif
01040 
01041 #endif /* _GC_H */