| 1 | /*
|
|---|
| 2 | * This is a simple API to implement pointer back tracing, i.e.
|
|---|
| 3 | * to answer questions such as "who is pointing to this" or
|
|---|
| 4 | * "why is this object being retained by the collector"
|
|---|
| 5 | *
|
|---|
| 6 | * This API assumes that we have an ANSI C compiler.
|
|---|
| 7 | *
|
|---|
| 8 | * Most of these calls yield useful information on only after
|
|---|
| 9 | * a garbage collection. Usually the client will first force
|
|---|
| 10 | * a full collection and then gather information, preferably
|
|---|
| 11 | * before much intervening allocation.
|
|---|
| 12 | *
|
|---|
| 13 | * The implementation of the interface is only about 99.9999%
|
|---|
| 14 | * correct. It is intended to be good enough for profiling,
|
|---|
| 15 | * but is not intended to be used with production code.
|
|---|
| 16 | *
|
|---|
| 17 | * Results are likely to be much more useful if all allocation is
|
|---|
| 18 | * accomplished through the debugging allocators.
|
|---|
| 19 | *
|
|---|
| 20 | * The implementation idea is due to A. Demers.
|
|---|
| 21 | */
|
|---|
| 22 |
|
|---|
| 23 | #ifndef GC_BACKPTR_H
|
|---|
| 24 | #define GC_BACKPTR_H
|
|---|
| 25 | /* Store information about the object referencing dest in *base_p */
|
|---|
| 26 | /* and *offset_p. */
|
|---|
| 27 | /* If multiple objects or roots point to dest, the one reported */
|
|---|
| 28 | /* will be the last on used by the garbage collector to trace the */
|
|---|
| 29 | /* object. */
|
|---|
| 30 | /* source is root ==> *base_p = address, *offset_p = 0 */
|
|---|
| 31 | /* source is heap object ==> *base_p != 0, *offset_p = offset */
|
|---|
| 32 | /* Returns 1 on success, 0 if source couldn't be determined. */
|
|---|
| 33 | /* Dest can be any address within a heap object. */
|
|---|
| 34 | typedef enum { GC_UNREFERENCED, /* No reference info available. */
|
|---|
| 35 | GC_NO_SPACE, /* Dest not allocated with debug alloc */
|
|---|
| 36 | GC_REFD_FROM_ROOT, /* Referenced directly by root *base_p */
|
|---|
| 37 | GC_REFD_FROM_REG, /* Referenced from a register, i.e. */
|
|---|
| 38 | /* a root without an address. */
|
|---|
| 39 | GC_REFD_FROM_HEAP, /* Referenced from another heap obj. */
|
|---|
| 40 | GC_FINALIZER_REFD /* Finalizable and hence accessible. */
|
|---|
| 41 | } GC_ref_kind;
|
|---|
| 42 |
|
|---|
| 43 | GC_ref_kind GC_get_back_ptr_info(void *dest, void **base_p, size_t *offset_p);
|
|---|
| 44 |
|
|---|
| 45 | /* Generate a random heap address. */
|
|---|
| 46 | /* The resulting address is in the heap, but */
|
|---|
| 47 | /* not necessarily inside a valid object. */
|
|---|
| 48 | void * GC_generate_random_heap_address(void);
|
|---|
| 49 |
|
|---|
| 50 | /* Generate a random address inside a valid marked heap object. */
|
|---|
| 51 | void * GC_generate_random_valid_address(void);
|
|---|
| 52 |
|
|---|
| 53 | /* Force a garbage collection and generate a backtrace from a */
|
|---|
| 54 | /* random heap address. */
|
|---|
| 55 | /* This uses the GC logging mechanism (GC_printf) to produce */
|
|---|
| 56 | /* output. It can often be called from a debugger. The */
|
|---|
| 57 | /* source in dbg_mlc.c also serves as a sample client. */
|
|---|
| 58 | void GC_generate_random_backtrace(void);
|
|---|
| 59 |
|
|---|
| 60 | /* Print a backtrace from a specific address. Used by the */
|
|---|
| 61 | /* above. The client should call GC_gcollect() immediately */
|
|---|
| 62 | /* before invocation. */
|
|---|
| 63 | void GC_print_backtrace(void *);
|
|---|
| 64 |
|
|---|
| 65 | #endif /* GC_BACKPTR_H */
|
|---|
