Back to index

lightning-sunbird  0.9+nobinonly
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 by Silicon Graphics.  All rights reserved.
00005  *
00006  * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
00007  * OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
00008  *
00009  * Permission is hereby granted to use or copy this program
00010  * for any purpose,  provided the above notices are retained on all copies.
00011  * Permission to modify the code and to distribute modified code is granted,
00012  * provided the above notices are retained, and a notice that the code was
00013  * modified is included with the above copyright notice.
00014  */
00015 
00016 /*
00017  * Note that this defines a large number of tuning hooks, which can
00018  * safely be ignored in nearly all cases.  For normal use it suffices
00019  * to call only GC_MALLOC and perhaps GC_REALLOC.
00020  * For better performance, also look at GC_MALLOC_ATOMIC, and
00021  * GC_enable_incremental.  If you need an action to be performed
00022  * immediately before an object is collected, look at GC_register_finalizer.
00023  * If you are using Solaris threads, look at the end of this file.
00024  * Everything else is best ignored unless you encounter performance
00025  * problems.
00026  */
00027  
00028 #ifndef _GC_H
00029 
00030 # define _GC_H
00031 # define __GC
00032 # include <stddef.h>
00033 
00034 #if defined(__CYGWIN32__) && defined(GC_USE_DLL)
00035 #include "libgc_globals.h"
00036 #endif
00037 
00038 #if defined(_MSC_VER) && defined(_DLL)
00039 # ifdef GC_BUILD
00040 #   define GC_API __declspec(dllexport)
00041 # else
00042 #   define GC_API __declspec(dllimport)
00043 # endif
00044 #endif
00045 
00046 #if defined(__WATCOMC__) && defined(GC_DLL)
00047 # ifdef GC_BUILD
00048 #   define GC_API extern __declspec(dllexport)
00049 # else
00050 #   define GC_API extern __declspec(dllimport)
00051 # endif
00052 #endif
00053 
00054 #ifndef GC_API
00055 #define GC_API extern
00056 #endif
00057 
00058 # if defined(__STDC__) || defined(__cplusplus)
00059 #   define GC_PROTO(args) args
00060     typedef void * GC_PTR;
00061 # else
00062 #   define GC_PROTO(args) ()
00063     typedef char * GC_PTR;
00064 #  endif
00065 
00066 # ifdef __cplusplus
00067     extern "C" {
00068 # endif
00069 
00070 
00071 /* Define word and signed_word to be unsigned and signed types of the        */
00072 /* size as char * or void *.  There seems to be no way to do this     */
00073 /* even semi-portably.  The following is probably no better/worse     */
00074 /* than almost anything else.                                         */
00075 /* The ANSI standard suggests that size_t and ptr_diff_t might be     */
00076 /* better choices.  But those appear to have incorrect definitions    */
00077 /* on may systems.  Notably "typedef int size_t" seems to be both     */
00078 /* frequent and WRONG.                                                */
00079 typedef unsigned long GC_word;
00080 typedef long GC_signed_word;
00081 
00082 /* Public read-only variables */
00083 
00084 GC_API GC_word GC_gc_no;/* Counter incremented per collection.        */
00085                      /* Includes empty GCs at startup.         */
00086                      
00087 
00088 /* Public R/W variables */
00089 
00090 GC_API GC_PTR (*GC_oom_fn) GC_PROTO((size_t bytes_requested));
00091                      /* When there is insufficient memory to satisfy */
00092                      /* an allocation request, we return              */
00093                      /* (*GC_oom_fn)().  By default this just  */
00094                      /* returns 0.                             */
00095                      /* If it returns, it must return 0 or a valid    */
00096                      /* pointer to a previously allocated heap        */
00097                      /* object.                                */
00098 
00099 GC_API int GC_quiet; /* Disable statistics output.  Only matters if   */
00100                      /* collector has been compiled with statistics   */
00101                      /* enabled.  This involves a performance cost,   */
00102                      /* and is thus not the default.                  */
00103 
00104 GC_API int GC_dont_gc;      /* Dont collect unless explicitly requested, e.g. */
00105                      /* because it's not safe.                   */
00106 
00107 GC_API int GC_dont_expand;
00108                      /* Dont expand heap unless explicitly requested */
00109                      /* or forced to.                          */
00110 
00111 GC_API int GC_full_freq;    /* Number of partial collections between  */
00112                          /* full collections.  Matters only if */
00113                          /* GC_incremental is set.                    */
00114                      
00115 GC_API GC_word GC_non_gc_bytes;
00116                      /* Bytes not considered candidates for collection. */
00117                      /* Used only to control scheduling of collections. */
00118 
00119 GC_API GC_word GC_free_space_divisor;
00120                      /* We try to make sure that we allocate at       */
00121                      /* least N/GC_free_space_divisor bytes between   */
00122                      /* collections, where N is the heap size plus    */
00123                      /* a rough estimate of the root set size. */
00124                      /* Initially, GC_free_space_divisor = 4.  */
00125                      /* Increasing its value will use less space      */
00126                      /* but more collection time.  Decreasing it      */
00127                      /* will appreciably decrease collection time     */
00128                      /* at the expense of space.               */
00129                      /* GC_free_space_divisor = 1 will effectively    */
00130                      /* disable collections.                          */
00131 
00132 GC_API GC_word GC_max_retries;
00133                      /* The maximum number of GCs attempted before    */
00134                      /* reporting out of memory after heap            */
00135                      /* expansion fails.  Initially 0.         */
00136                      
00137 
00138 GC_API char *GC_stackbottom;       /* Cool end of user stack.         */
00139                             /* May be set in the client prior to      */
00140                             /* calling any GC_ routines.  This */
00141                             /* avoids some overhead, and              */
00142                             /* potentially some signals that can      */
00143                             /* confuse debuggers.  Otherwise the      */
00144                             /* collector attempts to set it    */
00145                             /* automatically.                  */
00146                             /* For multithreaded code, this is the    */
00147                             /* cold end of the stack for the   */
00148                             /* primordial thread.                     */
00149                             
00150 /* Public procedures */
00151 /*
00152  * general purpose allocation routines, with roughly malloc calling conv.
00153  * The atomic versions promise that no relevant pointers are contained
00154  * in the object.  The nonatomic versions guarantee that the new object
00155  * is cleared.  GC_malloc_stubborn promises that no changes to the object
00156  * will occur after GC_end_stubborn_change has been called on the
00157  * result of GC_malloc_stubborn. GC_malloc_uncollectable allocates an object
00158  * that is scanned for pointers to collectable objects, but is not itself
00159  * collectable.  GC_malloc_uncollectable and GC_free called on the resulting
00160  * object implicitly update GC_non_gc_bytes appropriately.
00161  */
00162 GC_API GC_PTR GC_malloc GC_PROTO((size_t size_in_bytes));
00163 GC_API GC_PTR GC_malloc_atomic GC_PROTO((size_t size_in_bytes));
00164 GC_API GC_PTR GC_malloc_uncollectable GC_PROTO((size_t size_in_bytes));
00165 GC_API GC_PTR GC_malloc_stubborn GC_PROTO((size_t size_in_bytes));
00166 
00167 /* The following is only defined if the library has been suitably     */
00168 /* compiled:                                                   */
00169 GC_API GC_PTR GC_malloc_atomic_uncollectable GC_PROTO((size_t size_in_bytes));
00170 
00171 /* Explicitly deallocate an object.  Dangerous if used incorrectly.     */
00172 /* Requires a pointer to the base of an object.                       */
00173 /* If the argument is stubborn, it should not be changeable when freed. */
00174 /* An object should not be enable for finalization when it is         */
00175 /* explicitly deallocated.                                     */
00176 /* GC_free(0) is a no-op, as required by ANSI C for free.             */
00177 GC_API void GC_free GC_PROTO((GC_PTR object_addr));
00178 
00179 /*
00180  * Stubborn objects may be changed only if the collector is explicitly informed.
00181  * The collector is implicitly informed of coming change when such
00182  * an object is first allocated.  The following routines inform the
00183  * collector that an object will no longer be changed, or that it will
00184  * once again be changed.  Only nonNIL pointer stores into the object
00185  * are considered to be changes.  The argument to GC_end_stubborn_change
00186  * must be exacly the value returned by GC_malloc_stubborn or passed to
00187  * GC_change_stubborn.  (In the second case it may be an interior pointer
00188  * within 512 bytes of the beginning of the objects.)
00189  * There is a performance penalty for allowing more than
00190  * one stubborn object to be changed at once, but it is acceptable to
00191  * do so.  The same applies to dropping stubborn objects that are still
00192  * changeable.
00193  */
00194 GC_API void GC_change_stubborn GC_PROTO((GC_PTR));
00195 GC_API void GC_end_stubborn_change GC_PROTO((GC_PTR));
00196 
00197 /* Return a pointer to the base (lowest address) of an object given   */
00198 /* a pointer to a location within the object.                         */
00199 /* Return 0 if displaced_pointer doesn't point to within a valid      */
00200 /* object.                                                     */
00201 GC_API GC_PTR GC_base GC_PROTO((GC_PTR displaced_pointer));
00202 
00203 /* Given a pointer to the base of an object, return its size in bytes.       */
00204 /* The returned size may be slightly larger than what was originally  */
00205 /* requested.                                                  */
00206 GC_API size_t GC_size GC_PROTO((GC_PTR object_addr));
00207 
00208 /* For compatibility with C library.  This is occasionally faster than       */
00209 /* a malloc followed by a bcopy.  But if you rely on that, either here       */
00210 /* or with the standard C library, your code is broken.  In my        */
00211 /* opinion, it shouldn't have been invented, but now we're stuck. -HB */
00212 /* The resulting object has the same kind as the original.            */
00213 /* If the argument is stubborn, the result will have changes enabled. */
00214 /* It is an error to have changes enabled for the original object.    */
00215 /* Follows ANSI comventions for NULL old_object.               */
00216 GC_API GC_PTR GC_realloc
00217        GC_PROTO((GC_PTR old_object, size_t new_size_in_bytes));
00218                                
00219 /* Explicitly increase the heap size.     */
00220 /* Returns 0 on failure, 1 on success.  */
00221 GC_API int GC_expand_hp GC_PROTO((size_t number_of_bytes));
00222 
00223 /* Limit the heap size to n bytes.  Useful when you're debugging,     */
00224 /* especially on systems that don't handle running out of memory well.       */
00225 /* n == 0 ==> unbounded.  This is the default.                        */
00226 GC_API void GC_set_max_heap_size GC_PROTO((GC_word n));
00227 
00228 /* Inform the collector that a certain section of statically allocated       */
00229 /* memory contains no pointers to garbage collected memory.  Thus it  */
00230 /* need not be scanned.  This is sometimes important if the application */
00231 /* maps large read/write files into the address space, which could be */
00232 /* mistaken for dynamic library data segments on some systems.        */
00233 GC_API void GC_exclude_static_roots GC_PROTO((GC_PTR start, GC_PTR finish));
00234 
00235 /* Clear the set of root segments.  Wizards only. */
00236 GC_API void GC_clear_roots GC_PROTO((void));
00237 
00238 /* Add a root segment.  Wizards only. */
00239 GC_API void GC_add_roots GC_PROTO((char * low_address,
00240                                char * high_address_plus_1));
00241 
00242 /* Remove a root segment.  Wizards only. */
00243 GC_API void GC_remove_roots GC_PROTO((char * low_address,
00244                                char * high_address_plus_1));
00245 
00246 
00247 /* Add a displacement to the set of those considered valid by the     */
00248 /* collector.  GC_register_displacement(n) means that if p was returned */
00249 /* by GC_malloc, then (char *)p + n will be considered to be a valid  */
00250 /* pointer to n.  N must be small and less than the size of p.        */
00251 /* (All pointers to the interior of objects from the stack are        */
00252 /* considered valid in any case.  This applies to heap objects and    */
00253 /* static data.)                                               */
00254 /* Preferably, this should be called before any other GC procedures.  */
00255 /* Calling it later adds to the probability of excess memory          */
00256 /* retention.                                                  */
00257 /* This is a no-op if the collector was compiled with recognition of  */
00258 /* arbitrary interior pointers enabled, which is now the default.     */
00259 GC_API void GC_register_displacement GC_PROTO((GC_word n));
00260 
00261 /* The following version should be used if any debugging allocation is       */
00262 /* being done.                                                        */
00263 GC_API void GC_debug_register_displacement GC_PROTO((GC_word n));
00264 
00265 /* Explicitly trigger a full, world-stop collection.    */
00266 GC_API void GC_gcollect GC_PROTO((void));
00267 
00268 /* Trigger a full world-stopped collection.  Abort the collection if  */
00269 /* and when stop_func returns a nonzero value.  Stop_func will be     */
00270 /* called frequently, and should be reasonably fast.  This works even */
00271 /* if virtual dirty bits, and hence incremental collection is not     */
00272 /* available for this architecture.  Collections can be aborted faster       */
00273 /* than normal pause times for incremental collection.  However,      */
00274 /* aborted collections do no useful work; the next collection needs   */
00275 /* to start from the beginning.                                       */
00276 /* Return 0 if the collection was aborted, 1 if it succeeded.         */
00277 typedef int (* GC_stop_func) GC_PROTO((void));
00278 GC_API int GC_try_to_collect GC_PROTO((GC_stop_func stop_func));
00279 
00280 /* Return the number of bytes in the heap.  Excludes collector private       */
00281 /* data structures.  Includes empty blocks and fragmentation loss.    */
00282 /* Includes some pages that were allocated but never written.         */
00283 GC_API size_t GC_get_heap_size GC_PROTO((void));
00284 
00285 /* Return the number of bytes allocated since the last collection.    */
00286 GC_API size_t GC_get_bytes_since_gc GC_PROTO((void));
00287 
00288 /* Enable incremental/generational collection.   */
00289 /* Not advisable unless dirty bits are           */
00290 /* available or most heap objects are            */
00291 /* pointerfree(atomic) or immutable.             */
00292 /* Don't use in leak finding mode.        */
00293 /* Ignored if GC_dont_gc is true.         */
00294 GC_API void GC_enable_incremental GC_PROTO((void));
00295 
00296 /* Perform some garbage collection work, if appropriate.       */
00297 /* Return 0 if there is no more work to be done.        */
00298 /* Typically performs an amount of work corresponding roughly  */
00299 /* to marking from one page.  May do more work if further      */
00300 /* progress requires it, e.g. if incremental collection is     */
00301 /* disabled.  It is reasonable to call this in a wait loop     */
00302 /* until it returns 0.                                         */
00303 GC_API int GC_collect_a_little GC_PROTO((void));
00304 
00305 /* Allocate an object of size lb bytes.  The client guarantees that   */
00306 /* as long as the object is live, it will be referenced by a pointer  */
00307 /* that points to somewhere within the first 256 bytes of the object. */
00308 /* (This should normally be declared volatile to prevent the compiler */
00309 /* from invalidating this assertion.)  This routine is only useful    */
00310 /* if a large array is being allocated.  It reduces the chance of     */
00311 /* accidentally retaining such an array as a result of scanning an    */
00312 /* integer that happens to be an address inside the array.  (Actually,       */
00313 /* it reduces the chance of the allocator not finding space for such  */
00314 /* an array, since it will try hard to avoid introducing such a false */
00315 /* reference.)  On a SunOS 4.X or MS Windows system this is recommended */
00316 /* for arrays likely to be larger than 100K or so.  For other systems,       */
00317 /* or if the collector is not configured to recognize all interior    */
00318 /* pointers, the threshold is normally much higher.                   */
00319 GC_API GC_PTR GC_malloc_ignore_off_page GC_PROTO((size_t lb));
00320 GC_API GC_PTR GC_malloc_atomic_ignore_off_page GC_PROTO((size_t lb));
00321 
00322 #if defined(__sgi) && !defined(__GNUC__) && _COMPILER_VERSION >= 720
00323 #   define GC_ADD_CALLER
00324 #   define GC_RETURN_ADDR (GC_word)__return_address
00325 #endif
00326 
00327 #ifdef GC_ADD_CALLER
00328 #  define GC_EXTRAS GC_RETURN_ADDR, __FILE__, __LINE__
00329 #  define GC_EXTRA_PARAMS GC_word ra, char * descr_string, int descr_int
00330 #else
00331 #  define GC_EXTRAS __FILE__, __LINE__
00332 #  define GC_EXTRA_PARAMS char * descr_string, int descr_int
00333 #endif
00334 
00335 /* Debugging (annotated) allocation.  GC_gcollect will check          */
00336 /* objects allocated in this way for overwrites, etc.                 */
00337 GC_API GC_PTR GC_debug_malloc
00338        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00339 GC_API GC_PTR GC_debug_malloc_atomic
00340        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00341 GC_API GC_PTR GC_debug_malloc_uncollectable
00342        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00343 GC_API GC_PTR GC_debug_malloc_stubborn
00344        GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
00345 GC_API void GC_debug_free GC_PROTO((GC_PTR object_addr));
00346 GC_API GC_PTR GC_debug_realloc
00347        GC_PROTO((GC_PTR old_object, size_t new_size_in_bytes,
00348                 GC_EXTRA_PARAMS));
00349                              
00350 GC_API void GC_debug_change_stubborn GC_PROTO((GC_PTR));
00351 GC_API void GC_debug_end_stubborn_change GC_PROTO((GC_PTR));
00352 # ifdef GC_DEBUG
00353 #   define GC_MALLOC(sz) GC_debug_malloc(sz, GC_EXTRAS)
00354 #   define GC_MALLOC_ATOMIC(sz) GC_debug_malloc_atomic(sz, GC_EXTRAS)
00355 #   define GC_MALLOC_UNCOLLECTABLE(sz) GC_debug_malloc_uncollectable(sz, \
00356                                                  GC_EXTRAS)
00357 #   define GC_REALLOC(old, sz) GC_debug_realloc(old, sz, GC_EXTRAS)
00358 #   define GC_FREE(p) GC_debug_free(p)
00359 #   define GC_REGISTER_FINALIZER(p, f, d, of, od) \
00360        GC_debug_register_finalizer(p, f, d, of, od)
00361 #   define GC_REGISTER_FINALIZER_IGNORE_SELF(p, f, d, of, od) \
00362        GC_debug_register_finalizer_ignore_self(p, f, d, of, od)
00363 #   define GC_MALLOC_STUBBORN(sz) GC_debug_malloc_stubborn(sz, GC_EXTRAS);
00364 #   define GC_CHANGE_STUBBORN(p) GC_debug_change_stubborn(p)
00365 #   define GC_END_STUBBORN_CHANGE(p) GC_debug_end_stubborn_change(p)
00366 #   define GC_GENERAL_REGISTER_DISAPPEARING_LINK(link, obj) \
00367        GC_general_register_disappearing_link(link, GC_base(obj))
00368 #   define GC_REGISTER_DISPLACEMENT(n) GC_debug_register_displacement(n)
00369 # else
00370 #   define GC_MALLOC(sz) GC_malloc(sz)
00371 #   define GC_MALLOC_ATOMIC(sz) GC_malloc_atomic(sz)
00372 #   define GC_MALLOC_UNCOLLECTABLE(sz) GC_malloc_uncollectable(sz)
00373 #   define GC_REALLOC(old, sz) GC_realloc(old, sz)
00374 #   define GC_FREE(p) GC_free(p)
00375 #   define GC_REGISTER_FINALIZER(p, f, d, of, od) \
00376        GC_register_finalizer(p, f, d, of, od)
00377 #   define GC_REGISTER_FINALIZER_IGNORE_SELF(p, f, d, of, od) \
00378        GC_register_finalizer_ignore_self(p, f, d, of, od)
00379 #   define GC_MALLOC_STUBBORN(sz) GC_malloc_stubborn(sz)
00380 #   define GC_CHANGE_STUBBORN(p) GC_change_stubborn(p)
00381 #   define GC_END_STUBBORN_CHANGE(p) GC_end_stubborn_change(p)
00382 #   define GC_GENERAL_REGISTER_DISAPPEARING_LINK(link, obj) \
00383        GC_general_register_disappearing_link(link, obj)
00384 #   define GC_REGISTER_DISPLACEMENT(n) GC_register_displacement(n)
00385 # endif
00386 /* The following are included because they are often convenient, and  */
00387 /* reduce the chance for a misspecifed size argument.  But calls may  */
00388 /* expand to something syntactically incorrect if t is a complicated  */
00389 /* type expression.                                                   */
00390 # define GC_NEW(t) (t *)GC_MALLOC(sizeof (t))
00391 # define GC_NEW_ATOMIC(t) (t *)GC_MALLOC_ATOMIC(sizeof (t))
00392 # define GC_NEW_STUBBORN(t) (t *)GC_MALLOC_STUBBORN(sizeof (t))
00393 # define GC_NEW_UNCOLLECTABLE(t) (t *)GC_MALLOC_UNCOLLECTABLE(sizeof (t))
00394 
00395 /* Finalization.  Some of these primitives are grossly unsafe.        */
00396 /* The idea is to make them both cheap, and sufficient to build              */
00397 /* a safer layer, closer to PCedar finalization.               */
00398 /* The interface represents my conclusions from a long discussion     */
00399 /* with Alan Demers, Dan Greene, Carl Hauser, Barry Hayes,            */
00400 /* Christian Jacobi, and Russ Atkinson.  It's not perfect, and        */
00401 /* probably nobody else agrees with it.       Hans-J. Boehm  3/13/92  */
00402 typedef void (*GC_finalization_proc)
00403        GC_PROTO((GC_PTR obj, GC_PTR client_data));
00404 
00405 GC_API void GC_register_finalizer
00406        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00407                 GC_finalization_proc *ofn, GC_PTR *ocd));
00408 GC_API void GC_debug_register_finalizer
00409        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00410                 GC_finalization_proc *ofn, GC_PTR *ocd));
00411        /* When obj is no longer accessible, invoke             */
00412        /* (*fn)(obj, cd).  If a and b are inaccessible, and    */
00413        /* a points to b (after disappearing links have been    */
00414        /* made to disappear), then only a will be              */
00415        /* finalized.  (If this does not create any new         */
00416        /* pointers to b, then b will be finalized after the    */
00417        /* next collection.)  Any finalizable object that       */
00418        /* is reachable from itself by following one or more    */
00419        /* pointers will not be finalized (or collected).       */
00420        /* Thus cycles involving finalizable objects should     */
00421        /* be avoided, or broken by disappearing links.         */
00422        /* All but the last finalizer registered for an object  */
00423        /* is ignored.                                          */
00424        /* Finalization may be removed by passing 0 as fn.      */
00425        /* Finalizers are implicitly unregistered just before   */
00426        /* they are invoked.                             */
00427        /* The old finalizer and client data are stored in      */
00428        /* *ofn and *ocd.                                */ 
00429        /* Fn is never invoked on an accessible object,         */
00430        /* provided hidden pointers are converted to real       */
00431        /* pointers only if the allocation lock is held, and    */
00432        /* such conversions are not performed by finalization   */
00433        /* routines.                                     */
00434        /* If GC_register_finalizer is aborted as a result of   */
00435        /* a signal, the object may be left with no             */
00436        /* finalization, even if neither the old nor new */
00437        /* finalizer were NULL.                                 */
00438        /* Obj should be the nonNULL starting address of an     */
00439        /* object allocated by GC_malloc or friends.            */
00440        /* Note that any garbage collectable object referenced  */
00441        /* by cd will be considered accessible until the */
00442        /* finalizer is invoked.                         */
00443 
00444 /* Another versions of the above follow.  It ignores           */
00445 /* self-cycles, i.e. pointers from a finalizable object to     */
00446 /* itself.  There is a stylistic argument that this is wrong,  */
00447 /* but it's unavoidable for C++, since the compiler may        */
00448 /* silently introduce these.  It's also benign in that specific       */
00449 /* case.                                                */
00450 GC_API void GC_register_finalizer_ignore_self
00451        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00452                 GC_finalization_proc *ofn, GC_PTR *ocd));
00453 GC_API void GC_debug_register_finalizer_ignore_self
00454        GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
00455                 GC_finalization_proc *ofn, GC_PTR *ocd));
00456 
00457 /* The following routine may be used to break cycles between   */
00458 /* finalizable objects, thus causing cyclic finalizable        */
00459 /* objects to be finalized in the correct order.  Standard     */
00460 /* use involves calling GC_register_disappearing_link(&p),     */
00461 /* where p is a pointer that is not followed by finalization   */
00462 /* code, and should not be considered in determining           */
00463 /* finalization order.                                         */
00464 GC_API int GC_register_disappearing_link GC_PROTO((GC_PTR * /* link */));
00465        /* Link should point to a field of a heap allocated     */
00466        /* object obj.  *link will be cleared when obj is       */
00467        /* found to be inaccessible.  This happens BEFORE any   */
00468        /* finalization code is invoked, and BEFORE any         */
00469        /* decisions about finalization order are made.         */
00470        /* This is useful in telling the finalizer that  */
00471        /* some pointers are not essential for proper           */
00472        /* finalization.  This may avoid finalization cycles.   */
00473        /* Note that obj may be resurrected by another          */
00474        /* finalizer, and thus the clearing of *link may */
00475        /* be visible to non-finalization code.          */
00476        /* There's an argument that an arbitrary action should  */
00477        /* be allowed here, instead of just clearing a pointer. */
00478        /* But this causes problems if that action alters, or   */
00479        /* examines connectivity.                        */
00480        /* Returns 1 if link was already registered, 0          */
00481        /* otherwise.                                    */
00482        /* Only exists for backward compatibility.  See below:  */
00483        
00484 GC_API int GC_general_register_disappearing_link
00485        GC_PROTO((GC_PTR * /* link */, GC_PTR obj));
00486        /* A slight generalization of the above. *link is       */
00487        /* cleared when obj first becomes inaccessible.  This   */
00488        /* can be used to implement weak pointers easily and    */
00489        /* safely. Typically link will point to a location      */
00490        /* holding a disguised pointer to obj.  (A pointer      */
00491        /* inside an "atomic" object is effectively             */
00492        /* disguised.)   In this way soft                */
00493        /* pointers are broken before any object         */
00494        /* reachable from them are finalized.  Each link */
00495        /* May be registered only once, i.e. with one obj       */
00496        /* value.  This was added after a long email discussion */
00497        /* with John Ellis.                              */
00498        /* Obj must be a pointer to the first word of an object */
00499        /* we allocated.  It is unsafe to explicitly deallocate */
00500        /* the object containing link.  Explicitly deallocating */
00501        /* obj may or may not cause link to eventually be       */
00502        /* cleared.                                      */
00503 GC_API int GC_unregister_disappearing_link GC_PROTO((GC_PTR * /* link */));
00504        /* Returns 0 if link was not actually registered.       */
00505        /* Undoes a registration by either of the above two     */
00506        /* routines.                                     */
00507 
00508 /* Auxiliary fns to make finalization work correctly with displaced   */
00509 /* pointers introduced by the debugging allocators.                   */
00510 GC_API GC_PTR GC_make_closure GC_PROTO((GC_finalization_proc fn, GC_PTR data));
00511 GC_API void GC_debug_invoke_finalizer GC_PROTO((GC_PTR obj, GC_PTR data));
00512 
00513 GC_API int GC_invoke_finalizers GC_PROTO((void));
00514        /* Run finalizers for all objects that are ready to     */
00515        /* be finalized.  Return the number of finalizers       */
00516        /* that were run.  Normally this is also called         */
00517        /* implicitly during some allocations.    If            */
00518        /* FINALIZE_ON_DEMAND is defined, it must be called     */
00519        /* explicitly.                                          */
00520 
00521 /* GC_set_warn_proc can be used to redirect or filter warning messages.      */
00522 /* p may not be a NULL pointer.                                       */
00523 typedef void (*GC_warn_proc) GC_PROTO((char *msg, GC_word arg));
00524 GC_API GC_warn_proc GC_set_warn_proc GC_PROTO((GC_warn_proc p));
00525     /* Returns old warning procedure.     */
00526        
00527 /* The following is intended to be used by a higher level      */
00528 /* (e.g. cedar-like) finalization facility.  It is expected    */
00529 /* that finalization code will arrange for hidden pointers to  */
00530 /* disappear.  Otherwise objects can be accessed after they    */
00531 /* have been collected.                                        */
00532 /* Note that putting pointers in atomic objects or in          */
00533 /* nonpointer slots of "typed" objects is equivalent to        */
00534 /* disguising them in this way, and may have other advantages. */
00535 # if defined(I_HIDE_POINTERS) || defined(GC_I_HIDE_POINTERS)
00536     typedef GC_word GC_hidden_pointer;
00537 #   define HIDE_POINTER(p) (~(GC_hidden_pointer)(p))
00538 #   define REVEAL_POINTER(p) ((GC_PTR)(HIDE_POINTER(p)))
00539     /* Converting a hidden pointer to a real pointer requires verifying      */
00540     /* that the object still exists.  This involves acquiring the     */
00541     /* allocator lock to avoid a race with the collector.             */
00542 # endif /* I_HIDE_POINTERS */
00543 
00544 typedef GC_PTR (*GC_fn_type) GC_PROTO((GC_PTR client_data));
00545 GC_API GC_PTR GC_call_with_alloc_lock
00546               GC_PROTO((GC_fn_type fn, GC_PTR client_data));
00547 
00548 /* Check that p and q point to the same object.                */
00549 /* Fail conspicuously if they don't.                           */
00550 /* Returns the first argument.                          */
00551 /* Succeeds if neither p nor q points to the heap.             */
00552 /* May succeed if both p and q point to between heap objects.  */
00553 GC_API GC_PTR GC_same_obj GC_PROTO((GC_PTR p, GC_PTR q));
00554 
00555 /* Checked pointer pre- and post- increment operations.  Note that    */
00556 /* the second argument is in units of bytes, not multiples of the     */
00557 /* object size.  This should either be invoked from a macro, or the   */
00558 /* call should be automatically generated.                            */
00559 GC_API GC_PTR GC_pre_incr GC_PROTO((GC_PTR *p, size_t how_much));
00560 GC_API GC_PTR GC_post_incr GC_PROTO((GC_PTR *p, size_t how_much));
00561 
00562 /* Check that p is visible                                     */
00563 /* to the collector as a possibly pointer containing location.        */
00564 /* If it isn't fail conspicuously.                             */
00565 /* Returns the argument in all cases.  May erroneously succeed        */
00566 /* in hard cases.  (This is intended for debugging use with           */
00567 /* untyped allocations.  The idea is that it should be possible, though      */
00568 /* slow, to add such a call to all indirect pointer stores.)          */
00569 /* Currently useless for multithreaded worlds.                        */
00570 GC_API GC_PTR GC_is_visible GC_PROTO((GC_PTR p));
00571 
00572 /* Check that if p is a pointer to a heap page, then it points to     */
00573 /* a valid displacement within a heap object.                         */
00574 /* Fail conspicuously if this property does not hold.                 */
00575 /* Uninteresting with ALL_INTERIOR_POINTERS.                          */
00576 /* Always returns its argument.                                       */
00577 GC_API GC_PTR GC_is_valid_displacement GC_PROTO((GC_PTR p));
00578 
00579 /* Safer, but slow, pointer addition.  Probably useful mainly with    */
00580 /* a preprocessor.  Useful only for heap pointers.                    */
00581 #ifdef GC_DEBUG
00582 #   define GC_PTR_ADD3(x, n, type_of_result) \
00583        ((type_of_result)GC_same_obj((x)+(n), (x)))
00584 #   define GC_PRE_INCR3(x, n, type_of_result) \
00585        ((type_of_result)GC_pre_incr(&(x), (n)*sizeof(*x))
00586 #   define GC_POST_INCR2(x, type_of_result) \
00587        ((type_of_result)GC_post_incr(&(x), sizeof(*x))
00588 #   ifdef __GNUC__
00589 #       define GC_PTR_ADD(x, n) \
00590            GC_PTR_ADD3(x, n, typeof(x))
00591 #   define GC_PRE_INCR(x, n) \
00592            GC_PRE_INCR3(x, n, typeof(x))
00593 #   define GC_POST_INCR(x, n) \
00594            GC_POST_INCR3(x, typeof(x))
00595 #   else
00596        /* We can't do this right without typeof, which ANSI    */
00597        /* decided was not sufficiently useful.  Repeatedly     */
00598        /* mentioning the arguments seems too dangerous to be   */
00599        /* useful.  So does not casting the result.             */
00600 #      define GC_PTR_ADD(x, n) ((x)+(n))
00601 #   endif
00602 #else  /* !GC_DEBUG */
00603 #   define GC_PTR_ADD3(x, n, type_of_result) ((x)+(n))
00604 #   define GC_PTR_ADD(x, n) ((x)+(n))
00605 #   define GC_PRE_INCR3(x, n, type_of_result) ((x) += (n))
00606 #   define GC_PRE_INCR(x, n) ((x) += (n))
00607 #   define GC_POST_INCR2(x, n, type_of_result) ((x)++)
00608 #   define GC_POST_INCR(x, n) ((x)++)
00609 #endif
00610 
00611 /* Safer assignment of a pointer to a nonstack location.       */
00612 #ifdef GC_DEBUG
00613 # ifdef __STDC__
00614 #   define GC_PTR_STORE(p, q) \
00615        (*(void **)GC_is_visible(p) = GC_is_valid_displacement(q))
00616 # else
00617 #   define GC_PTR_STORE(p, q) \
00618        (*(char **)GC_is_visible(p) = GC_is_valid_displacement(q))
00619 # endif
00620 #else /* !GC_DEBUG */
00621 #   define GC_PTR_STORE(p, q) *((p) = (q))
00622 #endif
00623 
00624 /* Fynctions called to report pointer checking errors */
00625 GC_API void (*GC_same_obj_print_proc) GC_PROTO((GC_PTR p, GC_PTR q));
00626 
00627 GC_API void (*GC_is_valid_displacement_print_proc)
00628        GC_PROTO((GC_PTR p));
00629 
00630 GC_API void (*GC_is_visible_print_proc)
00631        GC_PROTO((GC_PTR p));
00632 
00633 #if defined(_SOLARIS_PTHREADS) && !defined(SOLARIS_THREADS)
00634 #   define SOLARIS_THREADS
00635 #endif
00636 
00637 #ifdef SOLARIS_THREADS
00638 /* We need to intercept calls to many of the threads primitives, so   */
00639 /* that we can locate thread stacks and stop the world.               */
00640 /* Note also that the collector cannot see thread specific data.      */
00641 /* Thread specific data should generally consist of pointers to              */
00642 /* uncollectable objects, which are deallocated using the destructor  */
00643 /* facility in thr_keycreate.                                         */
00644 # include <thread.h>
00645 # include <signal.h>
00646   int GC_thr_create(void *stack_base, size_t stack_size,
00647                     void *(*start_routine)(void *), void *arg, long flags,
00648                     thread_t *new_thread);
00649   int GC_thr_join(thread_t wait_for, thread_t *departed, void **status);
00650   int GC_thr_suspend(thread_t target_thread);
00651   int GC_thr_continue(thread_t target_thread);
00652   void * GC_dlopen(const char *path, int mode);
00653 
00654 # ifdef _SOLARIS_PTHREADS
00655 #   include <pthread.h>
00656     extern int GC_pthread_create(pthread_t *new_thread,
00657                               const pthread_attr_t *attr,
00658                              void * (*thread_execp)(void *), void *arg);
00659     extern int GC_pthread_join(pthread_t wait_for, void **status);
00660 
00661 #   undef thread_t
00662 
00663 #   define pthread_join GC_pthread_join
00664 #   define pthread_create GC_pthread_create
00665 #endif
00666 
00667 # define thr_create GC_thr_create
00668 # define thr_join GC_thr_join
00669 # define thr_suspend GC_thr_suspend
00670 # define thr_continue GC_thr_continue
00671 # define dlopen GC_dlopen
00672 
00673 # endif /* SOLARIS_THREADS */
00674 
00675 
00676 #if defined(IRIX_THREADS) || defined(LINUX_THREADS)
00677 /* We treat these similarly. */
00678 # include <pthread.h>
00679 # include <signal.h>
00680 
00681   int GC_pthread_create(pthread_t *new_thread,
00682                         const pthread_attr_t *attr,
00683                       void *(*start_routine)(void *), void *arg);
00684   int GC_pthread_sigmask(int how, const sigset_t *set, sigset_t *oset);
00685   int GC_pthread_join(pthread_t thread, void **retval);
00686 
00687 # define pthread_create GC_pthread_create
00688 # define pthread_sigmask GC_pthread_sigmask
00689 # define pthread_join GC_pthread_join
00690 
00691 #endif /* IRIX_THREADS || LINUX_THREADS */
00692 
00693 # if defined(PCR) || defined(SOLARIS_THREADS) || defined(WIN32_THREADS) || \
00694        defined(IRIX_THREADS) || defined(LINUX_THREADS) || \
00695        defined(IRIX_JDK_THREADS)
00696        /* Any flavor of threads except SRC_M3.   */
00697 /* This returns a list of objects, linked through their first         */
00698 /* word.  Its use can greatly reduce lock contention problems, since  */
00699 /* the allocation lock can be acquired and released many fewer times. */
00700 GC_PTR GC_malloc_many(size_t lb);
00701 #define GC_NEXT(p) (*(GC_PTR *)(p))       /* Retrieve the next element       */
00702                                    /* in returned list.        */
00703 extern void GC_thr_init();  /* Needed for Solaris/X86   */
00704 
00705 #endif /* THREADS && !SRC_M3 */
00706 
00707 /*
00708  * If you are planning on putting
00709  * the collector in a SunOS 5 dynamic library, you need to call GC_INIT()
00710  * from the statically loaded program section.
00711  * This circumvents a Solaris 2.X (X<=4) linker bug.
00712  */
00713 #if defined(sparc) || defined(__sparc)
00714 #   define GC_INIT() { extern end, etext; \
00715                      GC_noop(&end, &etext); }
00716 #else
00717 # if defined(__CYGWIN32__) && defined(GC_USE_DLL)
00718     /*
00719      * Similarly gnu-win32 DLLs need explicit initialization
00720      */
00721 #   define GC_INIT() { GC_add_roots(DATASTART, DATAEND); }
00722 # else
00723 #   define GC_INIT()
00724 # endif
00725 #endif
00726 
00727 #if (defined(_MSDOS) || defined(_MSC_VER)) && (_M_IX86 >= 300) \
00728      || defined(_WIN32)
00729   /* win32S may not free all resources on process exit.  */
00730   /* This explicitly deallocates the heap.               */
00731     GC_API void GC_win32_free_heap ();
00732 #endif
00733 
00734 #ifdef __cplusplus
00735     }  /* end of extern "C" */
00736 #endif
00737 
00738 #endif /* _GC_H */