Back to index

plt-scheme  4.2.1
gc2.h
Go to the documentation of this file.
00001 
00002 #ifndef __mzscheme_gc_2__
00003 #define __mzscheme_gc_2__
00004 
00005 #ifdef MZ_USE_PLACES
00006 # if _MSC_VER
00007 #  define THREAD_LOCAL __declspec(thread)
00008 # else
00009 #  define THREAD_LOCAL __thread
00010 # endif
00011 #else
00012 # define THREAD_LOCAL /* empty */
00013 #endif
00014 
00015 /***************************************************************************/
00016 /***   See README for a general overview of the interface architecture.  ***/
00017 /***************************************************************************/
00018 
00019 #ifndef GC2_JUST_MACROS
00020 
00021 typedef int (*Size_Proc)(void *obj);
00022 typedef int (*Mark_Proc)(void *obj);
00023 typedef int (*Fixup_Proc)(void *obj);
00024 typedef void (*GC_collect_start_callback_Proc)(void);
00025 typedef void (*GC_collect_end_callback_Proc)(void);
00026 typedef void (*GC_collect_inform_callback_Proc)(int major_gc, long pre_used, long post_used);
00027 typedef unsigned long (*GC_get_thread_stack_base_Proc)(void);
00028 /* 
00029    Types of the traversal procs (supplied by MzScheme); see overview in README
00030    for information about traversals. The return value is the size of
00031    the object in words. */
00032 
00033 # ifdef GC2_JUST_MACROS_AND_TYPEDEFS
00034 #  define GC2_JUST_MACROS
00035 # endif
00036 
00037 #endif
00038 
00039 #ifdef MZ_USE_PLACES
00040 # define GC_OBJHEAD_SIZE (2*sizeof(unsigned long))
00041 #else 
00042 # define GC_OBJHEAD_SIZE (sizeof(unsigned long))
00043 #endif
00044 
00045 #ifndef GC2_JUST_MACROS
00046 
00047 #include <stddef.h>
00048 
00049 #ifndef GC2_EXTERN
00050 # ifdef GC2_AS_EXPORT
00051 #  define GC2_EXTERN __declspec(dllexport)
00052 # endif
00053 # ifdef GC2_AS_IMPORT
00054 #  define GC2_EXTERN __declspec(dllimport)
00055 # endif
00056 # ifndef GC2_EXTERN
00057 #  define GC2_EXTERN extern
00058 # endif
00059 #endif
00060 
00061 # ifdef __cplusplus
00062 extern "C" {
00063 # endif
00064 
00065 /***************************************************************************/
00066 /* Administration                                                          */
00067 /***************************************************************************/
00068 
00069 GC2_EXTERN void GC_set_get_thread_stack_base(unsigned long (*)(void));
00070 /* 
00071    Sets callback called by GC to get the base for stack traversal in the current
00072    thread (see README). The returned address must not be in the middle
00073    of a variable-stack record. */
00074 
00075 GC2_EXTERN void GC_set_stack_base(void *base);
00076 GC2_EXTERN unsigned long GC_get_stack_base(void);
00077 /*
00078    Called by MzScheme to set/get value used for stack base when
00079    GC_get_thread_stack_base is null. This is mainly useful for getting
00080    MzScheme started, before it has multiple threads. */
00081 
00082 GC2_EXTERN void GC_add_roots(void *start, void *end);
00083 /*
00084    Called by MzScheme to install roots. The memory between
00085    `start' (inclusive) and `end' (exclusive) contains pointers. */
00086 
00087 GC2_EXTERN void GC_init_type_tags(int count, int pair, int mutable_pair, int weakbox, 
00088                                   int ephemeron, int weakarray, int custbox);
00089 /*
00090    Called by MzScheme to indicate the number of different type tags it
00091    uses, starting from 0. `count' is always less than 256. The weakbox
00092    argument is the value to be used for tagging weak box, the
00093    ephemeron is the value to tagging an ephemeron, etc. (The GC has some
00094    freedom in the layout of a weak box or ephemeron, so it performs weak
00095    box traversals itself, but MzScheme gets to choose the tag.) */
00096 
00097 GC2_EXTERN void GC_register_root_custodian(void *);
00098 /*
00099    Registers the root custodian. */
00100 
00101 GC2_EXTERN void GC_register_new_thread(void *, void *);
00102 /*
00103    Indicates that a just-allocated point is for a thread record
00104    owned by a particular custodian. */
00105 GC2_EXTERN void GC_register_thread(void *, void *);
00106 /*
00107    Indicates that a a thread record is owned by a particular custodian. */
00108 
00109 GC2_EXTERN GC_collect_start_callback_Proc GC_set_collect_start_callback(GC_collect_start_callback_Proc);
00110 GC2_EXTERN GC_collect_end_callback_Proc GC_set_collect_end_callback(GC_collect_end_callback_Proc);
00111 GC2_EXTERN void GC_set_collect_inform_callback(GC_collect_inform_callback_Proc);
00112 /*
00113    Sets callbacks called by GC before/after performing a collection.  Used by MzScheme
00114    to zero out some data and record collection times. The end
00115    procedure should be called before finalizations are performed. */
00116 
00117 GC2_EXTERN void (*GC_out_of_memory)(void);
00118 /*
00119    Called by GC when it can't satify a memory request. GC_out_of_memory()
00120    might perform a longjmp. */
00121 
00122 GC2_EXTERN void (*GC_report_out_of_memory)(void);
00123 /*
00124    Called by GC when it has to give up, maybe due to running out of memory
00125    during a collection. */
00126 
00127 GC2_EXTERN void GC_dump(void);
00128 /*
00129    Dumps memory state info to stderr. */
00130 
00131 GC2_EXTERN long GC_get_memory_use(void *c);
00132 /*
00133    Returns the number of currently-allocated bytes (speficilly for
00134    custodian c, as much as the GC's accounting makes possible). */
00135 
00136 #define MZACCT_REQUIRE             0
00137 #define MZACCT_LIMIT        1
00138 GC2_EXTERN int GC_set_account_hook(int type, void *c1, unsigned long b, void *c2);
00139 /*
00140   Set a memory-accounting property. Returns 0 for failure (i.e., not
00141   supported). */
00142 
00143 GC2_EXTERN void GC_gcollect(void);
00144 /*
00145    Performs an immediate (full) collection. */
00146 
00147 GC2_EXTERN void GC_free_all(void);
00148 /*
00149    Releases all memory, removes all signal handlers, etc.
00150    This is mainly useful for unloading a DLL within an embedding
00151    program tht will keep running. */
00152 
00153 /***************************************************************************/
00154 /* Allocation                                                              */
00155 /***************************************************************************/
00156 
00157 GC2_EXTERN void *GC_malloc(size_t size_in_bytes);
00158 /*
00159    Alloc an array of pointers, initially zeroed. */
00160 
00161 GC2_EXTERN void *GC_malloc_one_tagged(size_t);
00162 /* 
00163    Alloc a tagged item, initially zeroed.  MzScheme sets the tag
00164    before a collection. */
00165 
00166 GC2_EXTERN void *GC_malloc_one_small_tagged(size_t);
00167 /* 
00168    Like GC_malloc_one_tagged, but the size must be less than 1kb,
00169    it must not be zero, and it must be a multiple of the word size. */
00170 
00171 GC2_EXTERN void *GC_malloc_one_small_dirty_tagged(size_t);
00172 /* 
00173    Like GC_malloc_one_small_tagged, but the memory is not
00174    zeroed. The client must set all words in the allocated
00175    object before a GC can occur. */
00176 
00177 GC2_EXTERN void *GC_malloc_pair(void *car, void *cdr);
00178 /* 
00179    Like GC_malloc_one_tagged, but even more streamlined.
00180    The main potential advantage is that `car' and `cdr' don't
00181    have to be retained by the callee in the case of a GC. */
00182 
00183 GC2_EXTERN void *GC_malloc_one_xtagged(size_t);
00184 /* 
00185    Alloc an item, initially zeroed. Rather than having a specific tag,
00186    all objects allocated this way are marked/fixedup via the function
00187    in GC_mark_xtagged and GC_fixup_xtagged. MzScheme sets
00188    GC_{mark,fixup}_xtagged. */
00189 
00190 GC2_EXTERN void (*GC_mark_xtagged)(void *obj);
00191 GC2_EXTERN void (*GC_fixup_xtagged)(void *obj);
00192 /* 
00193   Mark and fixup functions for memory allocated with
00194   GC_malloc_one_xtagged(). */
00195 
00196 GC2_EXTERN void *GC_malloc_array_tagged(size_t);
00197 /* 
00198    Alloc an array of tagged items. MzScheme sets the tag in the first
00199    item before a collection, by maybe not all items. When traversing,
00200    use the first one for size. */
00201 
00202 GC2_EXTERN void *GC_malloc_atomic(size_t size_in_bytes);
00203 /*
00204    Alloc pointerless memory (not necessarily zeroed). */
00205 
00206 #define GC_malloc_atomic_tagged GC_malloc_one_tagged
00207 #define GC_malloc_small_atomic_tagged GC_malloc_one_small_dirty_tagged
00208 /*
00209    Alloc pointer-free tagged memory (not necessarily zeroed).
00210    MzScheme sets the tag before a collection. */
00211 
00212 GC2_EXTERN void *GC_malloc_atomic_uncollectable(size_t size_in_bytes);
00213 /*
00214    Like plain malloc: pointer-free, never collected. */
00215 
00216 GC2_EXTERN void *GC_malloc_allow_interior(size_t size_in_bytes);
00217 /*
00218    Alloc an array of pointers (typically large), and recognize
00219    pointers into the middle of the array, or just past the end of the
00220    array. */
00221 
00222 GC2_EXTERN void *GC_malloc_atomic_allow_interior(size_t size_in_bytes);
00223 /*
00224    Like GC_malloc_allow_interior(), but for an atomic object. */
00225 
00226 GC2_EXTERN void *GC_malloc_tagged_allow_interior(size_t size_in_bytes);
00227 /*
00228    Like GC_malloc_allow_interior(), but for a tagged object. */
00229 
00230 GC2_EXTERN void *GC_malloc_weak_array(size_t size_in_bytes, void *replace_val);
00231 /*
00232    Alloc an array of weak pointers, initially zeroed.  When a value in
00233    the array is collected, it's replaced by `replace-val'. The
00234    precense of a pointer in the array doesn't keep the referenced
00235    memory from being collected. See also README for information about
00236    the structure of the array. */
00237 
00238 GC2_EXTERN void GC_free(void *);
00239 /* 
00240    Lets the collector optionally reverse an allocation immediately.
00241    [Generally a no-op.] */
00242 
00243 GC2_EXTERN void *GC_malloc_weak_box(void *p, void **secondary, int soffset);
00244 /* 
00245    Allocate a weak box. See README for details. */
00246 
00247 GC2_EXTERN void *GC_malloc_ephemeron(void *p, void *p2);
00248 /* 
00249    Allocate an ephemeron. See README for details. */
00250 
00251 GC2_EXTERN void **GC_malloc_immobile_box(void *p);
00252 GC2_EXTERN void GC_free_immobile_box(void **b);
00253 /* 
00254    Allocate (or free) a non-GCed box containing a pointer to a GCed
00255    value.  The pointer is stored as the first longword of the box. */
00256 
00257 GC2_EXTERN long GC_malloc_stays_put_threshold();
00258 /*
00259    Returns a minimum size for which allocations generate
00260    objects that never move, and where pointers are allowed
00261    into the object's interior. */
00262 
00263 /***************************************************************************/
00264 /* Memory tracing                                                          */
00265 /***************************************************************************/
00266 GC2_EXTERN int GC_mtrace_new_id(void *f);
00267 GC2_EXTERN int GC_mtrace_union_current_with(int newval);
00268 
00269 /***************************************************************************/
00270 /* Finalization                                                            */
00271 /***************************************************************************/
00272 
00273 typedef void (*GC_finalization_proc)(void *p, void *data);
00274 /*
00275    Type of a finalization procedure. */
00276 
00277 GC2_EXTERN void GC_set_finalizer(void *p, int tagged, int level, 
00278                              GC_finalization_proc f, void *data, 
00279                              GC_finalization_proc *oldf, void **olddata);
00280 /*
00281    See README for details. */
00282 
00283 GC2_EXTERN void GC_finalization_weak_ptr(void **p, int offset);
00284 /*
00285    See README for details. */
00286 
00287 /***************************************************************************/
00288 /* Cooperative GC                                                          */
00289 /***************************************************************************/
00290 
00291 GC2_EXTERN THREAD_LOCAL void **GC_variable_stack;
00292 /*
00293    See the general overview in README. */
00294 
00295 GC2_EXTERN void **GC_get_variable_stack();
00296 GC2_EXTERN void GC_set_variable_stack(void **p);
00297 
00298 GC2_EXTERN void GC_register_traversers(short tag, Size_Proc size, Mark_Proc mark, Fixup_Proc fixup,
00299                                    int is_constant_size, int is_atomic);
00300 /*
00301    Registers a traversal procedure for a tag. Obviously, a traversal
00302    procedure must be installed for each tag before a collection
00303    happens where an instance of the tag as been allocated.  If objects
00304    using the tag are always of the same size, is_constant_size can be
00305    non-zero, and `size' must return the right size given a null
00306    pointer. If objects using the tag are atomic, is_atomic can be
00307    non-zero. */
00308 
00309 /* #define gcMARK(x) ... see below ... */
00310 /* #define gcMARK_TYPED(t, x) ... see below ... */
00311 /* #define gcMARK_TYPED_NOW(t, x) ... see below ... */
00312 /* #define gcFIXUP(x) ... see below ... */
00313 /* #define gcFIXUP_TYPED(t, x) ... see below ... */
00314 /* #define gcFIXUP_TYPED_NOW(t, x) ... see below ... */
00315 /* Macros that, given an l-value and optional type, marks the
00316    referenced memory as live and updates the pointer as necessary
00317    (i.e., if it's GCable memory that is moving). The `x' argument can
00318    appear in the macro's output multiple times, and the output can be
00319    a statement rather than a expression. 
00320 
00321    The NOW versions force the mark or fixup to happen immediately. The
00322    other forms can queue the mark or fixup to happen later. */
00323 
00324 /* #define gcBYTES_TO_WORDS(x) ((x + 3) >> 2) */
00325 /*
00326    Helpful macro for computing the return value in a traversal proc,
00327    which must be in words. */
00328 
00329 GC2_EXTERN void *GC_resolve(void *p);
00330 /*
00331    Can be called by a traversal proc to get the current address of a
00332    object that might have been moved already. This is necessary, for
00333    example, if the size or structure of an object depends on the
00334    content of an object it references. For example, the size of a
00335    class instance usually depends on a field count that is stored in
00336    the class. In fixup mode, call this before fixing up. */
00337 
00338 GC2_EXTERN void *GC_fixup_self(void *p);
00339 /*
00340    Can be called by a fixup proc to get the final address of the
00341    pointer passed to the fixup proc. This is the identity function
00342    only when objects are moved before fixup, but objects might
00343    be moved after fixup. */
00344 
00345 /* INTERNAL for the current implemenation (used by macros): */
00346 GC2_EXTERN void GC_mark(const void *p);
00347 GC2_EXTERN void GC_fixup(void *p);
00348 /*
00349    Used in the expansion of gcMARK and gcFIXUP. 
00350  
00351    These procedures and variables are internal to the current
00352    implementation, and are *not* part of the "official" interface. */
00353 
00354 GC2_EXTERN void GC_mark_variable_stack(void **var_stack,
00355                                    long delta,
00356                                    void *limit,
00357                                        void *stack_mem);
00358 GC2_EXTERN void GC_fixup_variable_stack(void **var_stack,
00359                                    long delta,
00360                                    void *limit,
00361                                         void *stack_mem);
00362 /*
00363    Can be called by a mark or fixup traversal proc to traverse and
00364    update a chunk of (atomically-allocated) memory containing an image
00365    of the stack.
00366 
00367    The `var_stack' argument corresponds to the value of GC_var_stack
00368    for the copied stack (see the overview at the top of this
00369    file). The `var_stack' pointer refers to the address of the chain
00370    in the original stack, not in the heap copy. The `delta' argument
00371    specifies the difference heap_copy_address - stack_address (where
00372    stack_address is the numerically lower bound for the copied stack
00373    region, regardless of which direction the stack grows). The `limit'
00374    argument corresponds to the value that would have been returned by
00375    GC_get_thread_stack_base() at the time the stack was copied. 
00376 
00377    The `stack_mem' argument indicates the start of the allocated memory
00378    that contains `var_stack'. It is used for backtraces. */
00379 
00380 GC2_EXTERN int GC_merely_accounting();
00381 /*
00382    Can be called by a mark or fixup traversal proc to determine whether
00383    the traversal is merely for accounting, in which case some marking
00384    can be skipped if the corresponding data should be charged to a
00385    different object. */
00386 
00387 GC2_EXTERN void GC_write_barrier(void *p);
00388 /* 
00389    Explicit write barrier to ensure that a write-barrier signal is not
00390    triggered by a memory write.
00391 */
00392 GC2_EXTERN void GC_switch_in_master_gc();
00393 /*
00394    Makes the current thread the master GC thread.
00395 */
00396 GC2_EXTERN void GC_switch_out_master_gc();
00397 /*
00398    Makes the current GC the master GC.
00399    Creates a new place specific GC and links it to the master GC.
00400 */
00401 GC2_EXTERN void GC_construct_child_gc();
00402 /*
00403    Creates a new place specific GC and links to the master GC.
00404 */
00405 
00406 GC2_EXTERN void *GC_switch_to_master_gc();
00407 /*
00408    Switches to the master GC
00409 */
00410 
00411 GC2_EXTERN void GC_switch_back_from_master(void *gc);
00412 /*
00413    Switches to back to gc from the master GC
00414 */
00415 
00416 
00417 # ifdef __cplusplus
00418 };
00419 # endif
00420 
00421 #endif
00422 
00423 /* Macros (implementation-specific): */
00424 #ifdef __x86_64__
00425 # define gcLOG_WORD_SIZE 3
00426 #else
00427 # define gcLOG_WORD_SIZE 2
00428 #endif
00429 #define gcMARK(x) GC_mark(x)
00430 #define gcMARK_TYPED(t, x) gcMARK(x)
00431 #define gcMARK_TYPED_NOW(t, x) gcMARK(x)
00432 #define gcFIXUP_TYPED_NOW(t, x) GC_fixup(&(x))
00433 #define gcFIXUP_TYPED(t, x) gcFIXUP_TYPED_NOW(void*, x)
00434 #define gcFIXUP(x) gcFIXUP_TYPED(void*, x)
00435 #define gcBYTES_TO_WORDS(x) ((x + (1 << gcLOG_WORD_SIZE) - 1) >> gcLOG_WORD_SIZE)
00436 #define gcWORDS_TO_BYTES(x) (x << gcLOG_WORD_SIZE)
00437 
00438 #define GC_INTERIORABLES_NEVER_MOVE 1
00439 
00440 #endif /* __mzscheme_gc_2__ */