Annotation of OpenXM_contrib2/asir2000/gc/include/gc.h, Revision 1.2
1.1 noro 1: /*
2: * Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
3: * Copyright (c) 1991-1995 by Xerox Corporation. All rights reserved.
4: * Copyright 1996 by Silicon Graphics. All rights reserved.
5: *
6: * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
7: * OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
8: *
9: * Permission is hereby granted to use or copy this program
10: * for any purpose, provided the above notices are retained on all copies.
11: * Permission to modify the code and to distribute modified code is granted,
12: * provided the above notices are retained, and a notice that the code was
13: * modified is included with the above copyright notice.
14: */
15:
16: /*
17: * Note that this defines a large number of tuning hooks, which can
18: * safely be ignored in nearly all cases. For normal use it suffices
19: * to call only GC_MALLOC and perhaps GC_REALLOC.
20: * For better performance, also look at GC_MALLOC_ATOMIC, and
21: * GC_enable_incremental. If you need an action to be performed
22: * immediately before an object is collected, look at GC_register_finalizer.
23: * If you are using Solaris threads, look at the end of this file.
24: * Everything else is best ignored unless you encounter performance
25: * problems.
26: */
27:
28: #ifndef _GC_H
29:
30: # define _GC_H
31: # define __GC
32: # include <stddef.h>
33:
34: #if defined(__CYGWIN32__) && defined(GC_USE_DLL)
35: #include "libgc_globals.h"
36: #endif
37:
38: #if defined(_MSC_VER) && defined(_DLL)
39: # ifdef GC_BUILD
40: # define GC_API __declspec(dllexport)
41: # else
42: # define GC_API __declspec(dllimport)
43: # endif
44: #endif
45:
46: #if defined(__WATCOMC__) && defined(GC_DLL)
47: # ifdef GC_BUILD
48: # define GC_API extern __declspec(dllexport)
49: # else
50: # define GC_API extern __declspec(dllimport)
51: # endif
52: #endif
53:
54: #ifndef GC_API
55: #define GC_API extern
56: #endif
57:
58: # if defined(__STDC__) || defined(__cplusplus)
59: # define GC_PROTO(args) args
60: typedef void * GC_PTR;
1.2 ! noro 61: # define GC_CONST const
1.1 noro 62: # else
63: # define GC_PROTO(args) ()
64: typedef char * GC_PTR;
1.2 ! noro 65: # define GC_CONST
1.1 noro 66: # endif
67:
68: # ifdef __cplusplus
69: extern "C" {
70: # endif
71:
72:
73: /* Define word and signed_word to be unsigned and signed types of the */
74: /* size as char * or void *. There seems to be no way to do this */
75: /* even semi-portably. The following is probably no better/worse */
76: /* than almost anything else. */
77: /* The ANSI standard suggests that size_t and ptr_diff_t might be */
78: /* better choices. But those appear to have incorrect definitions */
79: /* on may systems. Notably "typedef int size_t" seems to be both */
80: /* frequent and WRONG. */
81: typedef unsigned long GC_word;
82: typedef long GC_signed_word;
83:
84: /* Public read-only variables */
85:
86: GC_API GC_word GC_gc_no;/* Counter incremented per collection. */
87: /* Includes empty GCs at startup. */
88:
89:
90: /* Public R/W variables */
91:
92: GC_API GC_PTR (*GC_oom_fn) GC_PROTO((size_t bytes_requested));
93: /* When there is insufficient memory to satisfy */
94: /* an allocation request, we return */
95: /* (*GC_oom_fn)(). By default this just */
96: /* returns 0. */
97: /* If it returns, it must return 0 or a valid */
98: /* pointer to a previously allocated heap */
99: /* object. */
100:
1.2 ! noro 101: GC_API int GC_find_leak;
! 102: /* Do not actually garbage collect, but simply */
! 103: /* report inaccessible memory that was not */
! 104: /* deallocated with GC_free. Initial value */
! 105: /* is determined by FIND_LEAK macro. */
! 106:
1.1 noro 107: GC_API int GC_quiet; /* Disable statistics output. Only matters if */
108: /* collector has been compiled with statistics */
109: /* enabled. This involves a performance cost, */
110: /* and is thus not the default. */
111:
1.2 ! noro 112: GC_API int GC_finalize_on_demand;
! 113: /* If nonzero, finalizers will only be run in */
! 114: /* response to an eplit GC_invoke_finalizers */
! 115: /* call. The default is determined by whether */
! 116: /* the FINALIZE_ON_DEMAND macro is defined */
! 117: /* when the collector is built. */
! 118:
! 119: GC_API int GC_java_finalization;
! 120: /* Mark objects reachable from finalizable */
! 121: /* objects in a separate postpass. This makes */
! 122: /* it a bit safer to use non-topologically- */
! 123: /* ordered finalization. Default value is */
! 124: /* determined by JAVA_FINALIZATION macro. */
! 125:
1.1 noro 126: GC_API int GC_dont_gc; /* Dont collect unless explicitly requested, e.g. */
127: /* because it's not safe. */
128:
129: GC_API int GC_dont_expand;
130: /* Dont expand heap unless explicitly requested */
131: /* or forced to. */
132:
133: GC_API int GC_full_freq; /* Number of partial collections between */
134: /* full collections. Matters only if */
135: /* GC_incremental is set. */
1.2 ! noro 136: /* Full collections are also triggered if */
! 137: /* the collector detects a substantial */
! 138: /* increase in the number of in-use heap */
! 139: /* blocks. Values in the tens are now */
! 140: /* perfectly reasonable, unlike for */
! 141: /* earlier GC versions. */
1.1 noro 142:
143: GC_API GC_word GC_non_gc_bytes;
144: /* Bytes not considered candidates for collection. */
145: /* Used only to control scheduling of collections. */
146:
147: GC_API GC_word GC_free_space_divisor;
148: /* We try to make sure that we allocate at */
149: /* least N/GC_free_space_divisor bytes between */
150: /* collections, where N is the heap size plus */
151: /* a rough estimate of the root set size. */
152: /* Initially, GC_free_space_divisor = 4. */
153: /* Increasing its value will use less space */
154: /* but more collection time. Decreasing it */
155: /* will appreciably decrease collection time */
156: /* at the expense of space. */
157: /* GC_free_space_divisor = 1 will effectively */
158: /* disable collections. */
159:
160: GC_API GC_word GC_max_retries;
161: /* The maximum number of GCs attempted before */
162: /* reporting out of memory after heap */
163: /* expansion fails. Initially 0. */
164:
165:
166: GC_API char *GC_stackbottom; /* Cool end of user stack. */
167: /* May be set in the client prior to */
168: /* calling any GC_ routines. This */
169: /* avoids some overhead, and */
170: /* potentially some signals that can */
171: /* confuse debuggers. Otherwise the */
172: /* collector attempts to set it */
173: /* automatically. */
174: /* For multithreaded code, this is the */
175: /* cold end of the stack for the */
176: /* primordial thread. */
177:
178: /* Public procedures */
179: /*
180: * general purpose allocation routines, with roughly malloc calling conv.
181: * The atomic versions promise that no relevant pointers are contained
182: * in the object. The nonatomic versions guarantee that the new object
183: * is cleared. GC_malloc_stubborn promises that no changes to the object
184: * will occur after GC_end_stubborn_change has been called on the
185: * result of GC_malloc_stubborn. GC_malloc_uncollectable allocates an object
186: * that is scanned for pointers to collectable objects, but is not itself
187: * collectable. GC_malloc_uncollectable and GC_free called on the resulting
188: * object implicitly update GC_non_gc_bytes appropriately.
189: */
190: GC_API GC_PTR GC_malloc GC_PROTO((size_t size_in_bytes));
191: GC_API GC_PTR GC_malloc_atomic GC_PROTO((size_t size_in_bytes));
192: GC_API GC_PTR GC_malloc_uncollectable GC_PROTO((size_t size_in_bytes));
193: GC_API GC_PTR GC_malloc_stubborn GC_PROTO((size_t size_in_bytes));
194:
195: /* The following is only defined if the library has been suitably */
196: /* compiled: */
197: GC_API GC_PTR GC_malloc_atomic_uncollectable GC_PROTO((size_t size_in_bytes));
198:
199: /* Explicitly deallocate an object. Dangerous if used incorrectly. */
200: /* Requires a pointer to the base of an object. */
201: /* If the argument is stubborn, it should not be changeable when freed. */
202: /* An object should not be enable for finalization when it is */
203: /* explicitly deallocated. */
204: /* GC_free(0) is a no-op, as required by ANSI C for free. */
205: GC_API void GC_free GC_PROTO((GC_PTR object_addr));
206:
207: /*
208: * Stubborn objects may be changed only if the collector is explicitly informed.
209: * The collector is implicitly informed of coming change when such
210: * an object is first allocated. The following routines inform the
211: * collector that an object will no longer be changed, or that it will
212: * once again be changed. Only nonNIL pointer stores into the object
213: * are considered to be changes. The argument to GC_end_stubborn_change
214: * must be exacly the value returned by GC_malloc_stubborn or passed to
215: * GC_change_stubborn. (In the second case it may be an interior pointer
216: * within 512 bytes of the beginning of the objects.)
217: * There is a performance penalty for allowing more than
218: * one stubborn object to be changed at once, but it is acceptable to
219: * do so. The same applies to dropping stubborn objects that are still
220: * changeable.
221: */
222: GC_API void GC_change_stubborn GC_PROTO((GC_PTR));
223: GC_API void GC_end_stubborn_change GC_PROTO((GC_PTR));
224:
225: /* Return a pointer to the base (lowest address) of an object given */
226: /* a pointer to a location within the object. */
227: /* Return 0 if displaced_pointer doesn't point to within a valid */
228: /* object. */
229: GC_API GC_PTR GC_base GC_PROTO((GC_PTR displaced_pointer));
230:
231: /* Given a pointer to the base of an object, return its size in bytes. */
232: /* The returned size may be slightly larger than what was originally */
233: /* requested. */
234: GC_API size_t GC_size GC_PROTO((GC_PTR object_addr));
235:
236: /* For compatibility with C library. This is occasionally faster than */
237: /* a malloc followed by a bcopy. But if you rely on that, either here */
238: /* or with the standard C library, your code is broken. In my */
239: /* opinion, it shouldn't have been invented, but now we're stuck. -HB */
240: /* The resulting object has the same kind as the original. */
241: /* If the argument is stubborn, the result will have changes enabled. */
242: /* It is an error to have changes enabled for the original object. */
243: /* Follows ANSI comventions for NULL old_object. */
244: GC_API GC_PTR GC_realloc
245: GC_PROTO((GC_PTR old_object, size_t new_size_in_bytes));
246:
247: /* Explicitly increase the heap size. */
248: /* Returns 0 on failure, 1 on success. */
249: GC_API int GC_expand_hp GC_PROTO((size_t number_of_bytes));
250:
251: /* Limit the heap size to n bytes. Useful when you're debugging, */
252: /* especially on systems that don't handle running out of memory well. */
253: /* n == 0 ==> unbounded. This is the default. */
254: GC_API void GC_set_max_heap_size GC_PROTO((GC_word n));
255:
256: /* Inform the collector that a certain section of statically allocated */
257: /* memory contains no pointers to garbage collected memory. Thus it */
258: /* need not be scanned. This is sometimes important if the application */
259: /* maps large read/write files into the address space, which could be */
260: /* mistaken for dynamic library data segments on some systems. */
261: GC_API void GC_exclude_static_roots GC_PROTO((GC_PTR start, GC_PTR finish));
262:
263: /* Clear the set of root segments. Wizards only. */
264: GC_API void GC_clear_roots GC_PROTO((void));
265:
266: /* Add a root segment. Wizards only. */
267: GC_API void GC_add_roots GC_PROTO((char * low_address,
268: char * high_address_plus_1));
269:
270: /* Add a displacement to the set of those considered valid by the */
271: /* collector. GC_register_displacement(n) means that if p was returned */
272: /* by GC_malloc, then (char *)p + n will be considered to be a valid */
273: /* pointer to n. N must be small and less than the size of p. */
274: /* (All pointers to the interior of objects from the stack are */
275: /* considered valid in any case. This applies to heap objects and */
276: /* static data.) */
277: /* Preferably, this should be called before any other GC procedures. */
278: /* Calling it later adds to the probability of excess memory */
279: /* retention. */
280: /* This is a no-op if the collector was compiled with recognition of */
281: /* arbitrary interior pointers enabled, which is now the default. */
282: GC_API void GC_register_displacement GC_PROTO((GC_word n));
283:
284: /* The following version should be used if any debugging allocation is */
285: /* being done. */
286: GC_API void GC_debug_register_displacement GC_PROTO((GC_word n));
287:
288: /* Explicitly trigger a full, world-stop collection. */
289: GC_API void GC_gcollect GC_PROTO((void));
290:
291: /* Trigger a full world-stopped collection. Abort the collection if */
292: /* and when stop_func returns a nonzero value. Stop_func will be */
293: /* called frequently, and should be reasonably fast. This works even */
294: /* if virtual dirty bits, and hence incremental collection is not */
295: /* available for this architecture. Collections can be aborted faster */
296: /* than normal pause times for incremental collection. However, */
297: /* aborted collections do no useful work; the next collection needs */
298: /* to start from the beginning. */
299: /* Return 0 if the collection was aborted, 1 if it succeeded. */
300: typedef int (* GC_stop_func) GC_PROTO((void));
301: GC_API int GC_try_to_collect GC_PROTO((GC_stop_func stop_func));
302:
303: /* Return the number of bytes in the heap. Excludes collector private */
304: /* data structures. Includes empty blocks and fragmentation loss. */
305: /* Includes some pages that were allocated but never written. */
306: GC_API size_t GC_get_heap_size GC_PROTO((void));
307:
1.2 ! noro 308: /* Return a lower bound on the number of free bytes in the heap. */
! 309: GC_API size_t GC_get_free_bytes GC_PROTO((void));
! 310:
1.1 noro 311: /* Return the number of bytes allocated since the last collection. */
312: GC_API size_t GC_get_bytes_since_gc GC_PROTO((void));
313:
314: /* Enable incremental/generational collection. */
315: /* Not advisable unless dirty bits are */
316: /* available or most heap objects are */
317: /* pointerfree(atomic) or immutable. */
318: /* Don't use in leak finding mode. */
319: /* Ignored if GC_dont_gc is true. */
320: GC_API void GC_enable_incremental GC_PROTO((void));
321:
322: /* Perform some garbage collection work, if appropriate. */
323: /* Return 0 if there is no more work to be done. */
324: /* Typically performs an amount of work corresponding roughly */
325: /* to marking from one page. May do more work if further */
326: /* progress requires it, e.g. if incremental collection is */
327: /* disabled. It is reasonable to call this in a wait loop */
328: /* until it returns 0. */
329: GC_API int GC_collect_a_little GC_PROTO((void));
330:
331: /* Allocate an object of size lb bytes. The client guarantees that */
332: /* as long as the object is live, it will be referenced by a pointer */
333: /* that points to somewhere within the first 256 bytes of the object. */
334: /* (This should normally be declared volatile to prevent the compiler */
335: /* from invalidating this assertion.) This routine is only useful */
336: /* if a large array is being allocated. It reduces the chance of */
337: /* accidentally retaining such an array as a result of scanning an */
338: /* integer that happens to be an address inside the array. (Actually, */
339: /* it reduces the chance of the allocator not finding space for such */
340: /* an array, since it will try hard to avoid introducing such a false */
341: /* reference.) On a SunOS 4.X or MS Windows system this is recommended */
342: /* for arrays likely to be larger than 100K or so. For other systems, */
343: /* or if the collector is not configured to recognize all interior */
344: /* pointers, the threshold is normally much higher. */
345: GC_API GC_PTR GC_malloc_ignore_off_page GC_PROTO((size_t lb));
346: GC_API GC_PTR GC_malloc_atomic_ignore_off_page GC_PROTO((size_t lb));
347:
348: #if defined(__sgi) && !defined(__GNUC__) && _COMPILER_VERSION >= 720
349: # define GC_ADD_CALLER
350: # define GC_RETURN_ADDR (GC_word)__return_address
351: #endif
352:
353: #ifdef GC_ADD_CALLER
354: # define GC_EXTRAS GC_RETURN_ADDR, __FILE__, __LINE__
1.2 ! noro 355: # define GC_EXTRA_PARAMS GC_word ra, GC_CONST char * descr_string,
! 356: int descr_int
1.1 noro 357: #else
358: # define GC_EXTRAS __FILE__, __LINE__
1.2 ! noro 359: # define GC_EXTRA_PARAMS GC_CONST char * descr_string, int descr_int
1.1 noro 360: #endif
361:
362: /* Debugging (annotated) allocation. GC_gcollect will check */
363: /* objects allocated in this way for overwrites, etc. */
364: GC_API GC_PTR GC_debug_malloc
365: GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
366: GC_API GC_PTR GC_debug_malloc_atomic
367: GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
368: GC_API GC_PTR GC_debug_malloc_uncollectable
369: GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
370: GC_API GC_PTR GC_debug_malloc_stubborn
371: GC_PROTO((size_t size_in_bytes, GC_EXTRA_PARAMS));
372: GC_API void GC_debug_free GC_PROTO((GC_PTR object_addr));
373: GC_API GC_PTR GC_debug_realloc
374: GC_PROTO((GC_PTR old_object, size_t new_size_in_bytes,
375: GC_EXTRA_PARAMS));
376:
377: GC_API void GC_debug_change_stubborn GC_PROTO((GC_PTR));
378: GC_API void GC_debug_end_stubborn_change GC_PROTO((GC_PTR));
379: # ifdef GC_DEBUG
380: # define GC_MALLOC(sz) GC_debug_malloc(sz, GC_EXTRAS)
381: # define GC_MALLOC_ATOMIC(sz) GC_debug_malloc_atomic(sz, GC_EXTRAS)
382: # define GC_MALLOC_UNCOLLECTABLE(sz) GC_debug_malloc_uncollectable(sz, \
383: GC_EXTRAS)
384: # define GC_REALLOC(old, sz) GC_debug_realloc(old, sz, GC_EXTRAS)
385: # define GC_FREE(p) GC_debug_free(p)
386: # define GC_REGISTER_FINALIZER(p, f, d, of, od) \
387: GC_debug_register_finalizer(p, f, d, of, od)
388: # define GC_REGISTER_FINALIZER_IGNORE_SELF(p, f, d, of, od) \
389: GC_debug_register_finalizer_ignore_self(p, f, d, of, od)
390: # define GC_MALLOC_STUBBORN(sz) GC_debug_malloc_stubborn(sz, GC_EXTRAS);
391: # define GC_CHANGE_STUBBORN(p) GC_debug_change_stubborn(p)
392: # define GC_END_STUBBORN_CHANGE(p) GC_debug_end_stubborn_change(p)
393: # define GC_GENERAL_REGISTER_DISAPPEARING_LINK(link, obj) \
394: GC_general_register_disappearing_link(link, GC_base(obj))
395: # define GC_REGISTER_DISPLACEMENT(n) GC_debug_register_displacement(n)
396: # else
397: # define GC_MALLOC(sz) GC_malloc(sz)
398: # define GC_MALLOC_ATOMIC(sz) GC_malloc_atomic(sz)
399: # define GC_MALLOC_UNCOLLECTABLE(sz) GC_malloc_uncollectable(sz)
400: # define GC_REALLOC(old, sz) GC_realloc(old, sz)
401: # define GC_FREE(p) GC_free(p)
402: # define GC_REGISTER_FINALIZER(p, f, d, of, od) \
403: GC_register_finalizer(p, f, d, of, od)
404: # define GC_REGISTER_FINALIZER_IGNORE_SELF(p, f, d, of, od) \
405: GC_register_finalizer_ignore_self(p, f, d, of, od)
406: # define GC_MALLOC_STUBBORN(sz) GC_malloc_stubborn(sz)
407: # define GC_CHANGE_STUBBORN(p) GC_change_stubborn(p)
408: # define GC_END_STUBBORN_CHANGE(p) GC_end_stubborn_change(p)
409: # define GC_GENERAL_REGISTER_DISAPPEARING_LINK(link, obj) \
410: GC_general_register_disappearing_link(link, obj)
411: # define GC_REGISTER_DISPLACEMENT(n) GC_register_displacement(n)
412: # endif
413: /* The following are included because they are often convenient, and */
414: /* reduce the chance for a misspecifed size argument. But calls may */
415: /* expand to something syntactically incorrect if t is a complicated */
416: /* type expression. */
417: # define GC_NEW(t) (t *)GC_MALLOC(sizeof (t))
418: # define GC_NEW_ATOMIC(t) (t *)GC_MALLOC_ATOMIC(sizeof (t))
419: # define GC_NEW_STUBBORN(t) (t *)GC_MALLOC_STUBBORN(sizeof (t))
420: # define GC_NEW_UNCOLLECTABLE(t) (t *)GC_MALLOC_UNCOLLECTABLE(sizeof (t))
421:
422: /* Finalization. Some of these primitives are grossly unsafe. */
423: /* The idea is to make them both cheap, and sufficient to build */
424: /* a safer layer, closer to PCedar finalization. */
425: /* The interface represents my conclusions from a long discussion */
426: /* with Alan Demers, Dan Greene, Carl Hauser, Barry Hayes, */
427: /* Christian Jacobi, and Russ Atkinson. It's not perfect, and */
428: /* probably nobody else agrees with it. Hans-J. Boehm 3/13/92 */
429: typedef void (*GC_finalization_proc)
430: GC_PROTO((GC_PTR obj, GC_PTR client_data));
431:
432: GC_API void GC_register_finalizer
433: GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
434: GC_finalization_proc *ofn, GC_PTR *ocd));
435: GC_API void GC_debug_register_finalizer
436: GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
437: GC_finalization_proc *ofn, GC_PTR *ocd));
438: /* When obj is no longer accessible, invoke */
439: /* (*fn)(obj, cd). If a and b are inaccessible, and */
440: /* a points to b (after disappearing links have been */
441: /* made to disappear), then only a will be */
442: /* finalized. (If this does not create any new */
443: /* pointers to b, then b will be finalized after the */
444: /* next collection.) Any finalizable object that */
445: /* is reachable from itself by following one or more */
446: /* pointers will not be finalized (or collected). */
447: /* Thus cycles involving finalizable objects should */
448: /* be avoided, or broken by disappearing links. */
449: /* All but the last finalizer registered for an object */
450: /* is ignored. */
451: /* Finalization may be removed by passing 0 as fn. */
452: /* Finalizers are implicitly unregistered just before */
453: /* they are invoked. */
454: /* The old finalizer and client data are stored in */
455: /* *ofn and *ocd. */
456: /* Fn is never invoked on an accessible object, */
457: /* provided hidden pointers are converted to real */
458: /* pointers only if the allocation lock is held, and */
459: /* such conversions are not performed by finalization */
460: /* routines. */
461: /* If GC_register_finalizer is aborted as a result of */
462: /* a signal, the object may be left with no */
463: /* finalization, even if neither the old nor new */
464: /* finalizer were NULL. */
465: /* Obj should be the nonNULL starting address of an */
466: /* object allocated by GC_malloc or friends. */
467: /* Note that any garbage collectable object referenced */
468: /* by cd will be considered accessible until the */
469: /* finalizer is invoked. */
470:
471: /* Another versions of the above follow. It ignores */
472: /* self-cycles, i.e. pointers from a finalizable object to */
473: /* itself. There is a stylistic argument that this is wrong, */
474: /* but it's unavoidable for C++, since the compiler may */
475: /* silently introduce these. It's also benign in that specific */
476: /* case. */
477: GC_API void GC_register_finalizer_ignore_self
478: GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
479: GC_finalization_proc *ofn, GC_PTR *ocd));
480: GC_API void GC_debug_register_finalizer_ignore_self
481: GC_PROTO((GC_PTR obj, GC_finalization_proc fn, GC_PTR cd,
482: GC_finalization_proc *ofn, GC_PTR *ocd));
483:
484: /* The following routine may be used to break cycles between */
485: /* finalizable objects, thus causing cyclic finalizable */
486: /* objects to be finalized in the correct order. Standard */
487: /* use involves calling GC_register_disappearing_link(&p), */
488: /* where p is a pointer that is not followed by finalization */
489: /* code, and should not be considered in determining */
490: /* finalization order. */
491: GC_API int GC_register_disappearing_link GC_PROTO((GC_PTR * /* link */));
492: /* Link should point to a field of a heap allocated */
493: /* object obj. *link will be cleared when obj is */
494: /* found to be inaccessible. This happens BEFORE any */
495: /* finalization code is invoked, and BEFORE any */
496: /* decisions about finalization order are made. */
497: /* This is useful in telling the finalizer that */
498: /* some pointers are not essential for proper */
499: /* finalization. This may avoid finalization cycles. */
500: /* Note that obj may be resurrected by another */
501: /* finalizer, and thus the clearing of *link may */
502: /* be visible to non-finalization code. */
503: /* There's an argument that an arbitrary action should */
504: /* be allowed here, instead of just clearing a pointer. */
505: /* But this causes problems if that action alters, or */
506: /* examines connectivity. */
507: /* Returns 1 if link was already registered, 0 */
508: /* otherwise. */
509: /* Only exists for backward compatibility. See below: */
510:
511: GC_API int GC_general_register_disappearing_link
512: GC_PROTO((GC_PTR * /* link */, GC_PTR obj));
513: /* A slight generalization of the above. *link is */
514: /* cleared when obj first becomes inaccessible. This */
515: /* can be used to implement weak pointers easily and */
516: /* safely. Typically link will point to a location */
517: /* holding a disguised pointer to obj. (A pointer */
518: /* inside an "atomic" object is effectively */
519: /* disguised.) In this way soft */
520: /* pointers are broken before any object */
521: /* reachable from them are finalized. Each link */
522: /* May be registered only once, i.e. with one obj */
523: /* value. This was added after a long email discussion */
524: /* with John Ellis. */
525: /* Obj must be a pointer to the first word of an object */
526: /* we allocated. It is unsafe to explicitly deallocate */
527: /* the object containing link. Explicitly deallocating */
528: /* obj may or may not cause link to eventually be */
529: /* cleared. */
530: GC_API int GC_unregister_disappearing_link GC_PROTO((GC_PTR * /* link */));
531: /* Returns 0 if link was not actually registered. */
532: /* Undoes a registration by either of the above two */
533: /* routines. */
534:
535: /* Auxiliary fns to make finalization work correctly with displaced */
536: /* pointers introduced by the debugging allocators. */
537: GC_API GC_PTR GC_make_closure GC_PROTO((GC_finalization_proc fn, GC_PTR data));
538: GC_API void GC_debug_invoke_finalizer GC_PROTO((GC_PTR obj, GC_PTR data));
539:
540: GC_API int GC_invoke_finalizers GC_PROTO((void));
541: /* Run finalizers for all objects that are ready to */
542: /* be finalized. Return the number of finalizers */
543: /* that were run. Normally this is also called */
544: /* implicitly during some allocations. If */
1.2 ! noro 545: /* GC-finalize_on_demand is nonzero, it must be called */
1.1 noro 546: /* explicitly. */
547:
548: /* GC_set_warn_proc can be used to redirect or filter warning messages. */
549: /* p may not be a NULL pointer. */
550: typedef void (*GC_warn_proc) GC_PROTO((char *msg, GC_word arg));
551: GC_API GC_warn_proc GC_set_warn_proc GC_PROTO((GC_warn_proc p));
552: /* Returns old warning procedure. */
553:
554: /* The following is intended to be used by a higher level */
555: /* (e.g. cedar-like) finalization facility. It is expected */
556: /* that finalization code will arrange for hidden pointers to */
557: /* disappear. Otherwise objects can be accessed after they */
558: /* have been collected. */
559: /* Note that putting pointers in atomic objects or in */
560: /* nonpointer slots of "typed" objects is equivalent to */
561: /* disguising them in this way, and may have other advantages. */
562: # if defined(I_HIDE_POINTERS) || defined(GC_I_HIDE_POINTERS)
563: typedef GC_word GC_hidden_pointer;
564: # define HIDE_POINTER(p) (~(GC_hidden_pointer)(p))
565: # define REVEAL_POINTER(p) ((GC_PTR)(HIDE_POINTER(p)))
566: /* Converting a hidden pointer to a real pointer requires verifying */
567: /* that the object still exists. This involves acquiring the */
568: /* allocator lock to avoid a race with the collector. */
569: # endif /* I_HIDE_POINTERS */
570:
571: typedef GC_PTR (*GC_fn_type) GC_PROTO((GC_PTR client_data));
572: GC_API GC_PTR GC_call_with_alloc_lock
573: GC_PROTO((GC_fn_type fn, GC_PTR client_data));
574:
575: /* Check that p and q point to the same object. */
576: /* Fail conspicuously if they don't. */
577: /* Returns the first argument. */
578: /* Succeeds if neither p nor q points to the heap. */
579: /* May succeed if both p and q point to between heap objects. */
580: GC_API GC_PTR GC_same_obj GC_PROTO((GC_PTR p, GC_PTR q));
581:
582: /* Checked pointer pre- and post- increment operations. Note that */
583: /* the second argument is in units of bytes, not multiples of the */
584: /* object size. This should either be invoked from a macro, or the */
585: /* call should be automatically generated. */
586: GC_API GC_PTR GC_pre_incr GC_PROTO((GC_PTR *p, size_t how_much));
587: GC_API GC_PTR GC_post_incr GC_PROTO((GC_PTR *p, size_t how_much));
588:
589: /* Check that p is visible */
590: /* to the collector as a possibly pointer containing location. */
591: /* If it isn't fail conspicuously. */
592: /* Returns the argument in all cases. May erroneously succeed */
593: /* in hard cases. (This is intended for debugging use with */
594: /* untyped allocations. The idea is that it should be possible, though */
595: /* slow, to add such a call to all indirect pointer stores.) */
596: /* Currently useless for multithreaded worlds. */
597: GC_API GC_PTR GC_is_visible GC_PROTO((GC_PTR p));
598:
599: /* Check that if p is a pointer to a heap page, then it points to */
600: /* a valid displacement within a heap object. */
601: /* Fail conspicuously if this property does not hold. */
602: /* Uninteresting with ALL_INTERIOR_POINTERS. */
603: /* Always returns its argument. */
604: GC_API GC_PTR GC_is_valid_displacement GC_PROTO((GC_PTR p));
605:
606: /* Safer, but slow, pointer addition. Probably useful mainly with */
607: /* a preprocessor. Useful only for heap pointers. */
608: #ifdef GC_DEBUG
609: # define GC_PTR_ADD3(x, n, type_of_result) \
610: ((type_of_result)GC_same_obj((x)+(n), (x)))
611: # define GC_PRE_INCR3(x, n, type_of_result) \
612: ((type_of_result)GC_pre_incr(&(x), (n)*sizeof(*x))
613: # define GC_POST_INCR2(x, type_of_result) \
614: ((type_of_result)GC_post_incr(&(x), sizeof(*x))
615: # ifdef __GNUC__
616: # define GC_PTR_ADD(x, n) \
617: GC_PTR_ADD3(x, n, typeof(x))
618: # define GC_PRE_INCR(x, n) \
619: GC_PRE_INCR3(x, n, typeof(x))
620: # define GC_POST_INCR(x, n) \
621: GC_POST_INCR3(x, typeof(x))
622: # else
623: /* We can't do this right without typeof, which ANSI */
624: /* decided was not sufficiently useful. Repeatedly */
625: /* mentioning the arguments seems too dangerous to be */
626: /* useful. So does not casting the result. */
627: # define GC_PTR_ADD(x, n) ((x)+(n))
628: # endif
629: #else /* !GC_DEBUG */
630: # define GC_PTR_ADD3(x, n, type_of_result) ((x)+(n))
631: # define GC_PTR_ADD(x, n) ((x)+(n))
632: # define GC_PRE_INCR3(x, n, type_of_result) ((x) += (n))
633: # define GC_PRE_INCR(x, n) ((x) += (n))
634: # define GC_POST_INCR2(x, n, type_of_result) ((x)++)
635: # define GC_POST_INCR(x, n) ((x)++)
636: #endif
637:
638: /* Safer assignment of a pointer to a nonstack location. */
639: #ifdef GC_DEBUG
640: # ifdef __STDC__
641: # define GC_PTR_STORE(p, q) \
642: (*(void **)GC_is_visible(p) = GC_is_valid_displacement(q))
643: # else
644: # define GC_PTR_STORE(p, q) \
645: (*(char **)GC_is_visible(p) = GC_is_valid_displacement(q))
646: # endif
647: #else /* !GC_DEBUG */
648: # define GC_PTR_STORE(p, q) *((p) = (q))
649: #endif
650:
651: /* Fynctions called to report pointer checking errors */
652: GC_API void (*GC_same_obj_print_proc) GC_PROTO((GC_PTR p, GC_PTR q));
653:
654: GC_API void (*GC_is_valid_displacement_print_proc)
655: GC_PROTO((GC_PTR p));
656:
657: GC_API void (*GC_is_visible_print_proc)
658: GC_PROTO((GC_PTR p));
659:
660: #if defined(_SOLARIS_PTHREADS) && !defined(SOLARIS_THREADS)
661: # define SOLARIS_THREADS
662: #endif
663:
664: #ifdef SOLARIS_THREADS
665: /* We need to intercept calls to many of the threads primitives, so */
666: /* that we can locate thread stacks and stop the world. */
667: /* Note also that the collector cannot see thread specific data. */
668: /* Thread specific data should generally consist of pointers to */
669: /* uncollectable objects, which are deallocated using the destructor */
670: /* facility in thr_keycreate. */
671: # include <thread.h>
672: # include <signal.h>
673: int GC_thr_create(void *stack_base, size_t stack_size,
674: void *(*start_routine)(void *), void *arg, long flags,
675: thread_t *new_thread);
676: int GC_thr_join(thread_t wait_for, thread_t *departed, void **status);
677: int GC_thr_suspend(thread_t target_thread);
678: int GC_thr_continue(thread_t target_thread);
679: void * GC_dlopen(const char *path, int mode);
680:
681: # ifdef _SOLARIS_PTHREADS
682: # include <pthread.h>
683: extern int GC_pthread_create(pthread_t *new_thread,
684: const pthread_attr_t *attr,
685: void * (*thread_execp)(void *), void *arg);
686: extern int GC_pthread_join(pthread_t wait_for, void **status);
687:
688: # undef thread_t
689:
690: # define pthread_join GC_pthread_join
691: # define pthread_create GC_pthread_create
692: #endif
693:
694: # define thr_create GC_thr_create
695: # define thr_join GC_thr_join
696: # define thr_suspend GC_thr_suspend
697: # define thr_continue GC_thr_continue
698: # define dlopen GC_dlopen
699:
700: # endif /* SOLARIS_THREADS */
701:
702:
1.2 ! noro 703: #if defined(IRIX_THREADS) || defined(LINUX_THREADS) || defined(HPUX_THREADS)
1.1 noro 704: /* We treat these similarly. */
705: # include <pthread.h>
706: # include <signal.h>
707:
708: int GC_pthread_create(pthread_t *new_thread,
709: const pthread_attr_t *attr,
710: void *(*start_routine)(void *), void *arg);
711: int GC_pthread_sigmask(int how, const sigset_t *set, sigset_t *oset);
712: int GC_pthread_join(pthread_t thread, void **retval);
713:
714: # define pthread_create GC_pthread_create
715: # define pthread_sigmask GC_pthread_sigmask
716: # define pthread_join GC_pthread_join
717:
718: #endif /* IRIX_THREADS || LINUX_THREADS */
719:
720: # if defined(PCR) || defined(SOLARIS_THREADS) || defined(WIN32_THREADS) || \
721: defined(IRIX_THREADS) || defined(LINUX_THREADS) || \
1.2 ! noro 722: defined(IRIX_JDK_THREADS) || defined(HPUX_THREADS)
1.1 noro 723: /* Any flavor of threads except SRC_M3. */
724: /* This returns a list of objects, linked through their first */
725: /* word. Its use can greatly reduce lock contention problems, since */
726: /* the allocation lock can be acquired and released many fewer times. */
727: /* lb must be large enough to hold the pointer field. */
728: GC_PTR GC_malloc_many(size_t lb);
729: #define GC_NEXT(p) (*(GC_PTR *)(p)) /* Retrieve the next element */
730: /* in returned list. */
731: extern void GC_thr_init(); /* Needed for Solaris/X86 */
732:
733: #endif /* THREADS && !SRC_M3 */
734:
735: /*
736: * If you are planning on putting
737: * the collector in a SunOS 5 dynamic library, you need to call GC_INIT()
738: * from the statically loaded program section.
739: * This circumvents a Solaris 2.X (X<=4) linker bug.
740: */
741: #if defined(sparc) || defined(__sparc)
742: # define GC_INIT() { extern end, etext; \
743: GC_noop(&end, &etext); }
744: #else
745: # if defined(__CYGWIN32__) && defined(GC_USE_DLL)
746: /*
747: * Similarly gnu-win32 DLLs need explicit initialization
748: */
749: # define GC_INIT() { GC_add_roots(DATASTART, DATAEND); }
750: # else
751: # define GC_INIT()
752: # endif
753: #endif
754:
755: #if (defined(_MSDOS) || defined(_MSC_VER)) && (_M_IX86 >= 300) \
756: || defined(_WIN32)
757: /* win32S may not free all resources on process exit. */
758: /* This explicitly deallocates the heap. */
759: GC_API void GC_win32_free_heap ();
760: #endif
761:
762: #ifdef __cplusplus
763: } /* end of extern "C" */
764: #endif
765:
766: #endif /* _GC_H */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gc.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib2 / asir2000 / gc / include