Back to index

plt-scheme  4.2.1
gc_backptr.h
Go to the documentation of this file.
00001 /*
00002  * This is a simple API to implement pointer back tracing, i.e.
00003  * to answer questions such as "who is pointing to this" or
00004  * "why is this object being retained by the collector"
00005  *
00006  * This API assumes that we have an ANSI C compiler.
00007  *
00008  * Most of these calls yield useful information on only after
00009  * a garbage collection.  Usually the client will first force
00010  * a full collection and then gather information, preferably
00011  * before much intervening allocation.
00012  *
00013  * The implementation of the interface is only about 99.9999%
00014  * correct.  It is intended to be good enough for profiling,
00015  * but is not intended to be used with production code.
00016  *
00017  * Results are likely to be much more useful if all allocation is
00018  * accomplished through the debugging allocators.
00019  *
00020  * The implementation idea is due to A. Demers.
00021  */
00022 
00023 #ifndef GC_BACKPTR_H
00024 #define GC_BACKPTR_H
00025 /* Store information about the object referencing dest in *base_p     */
00026 /* and *offset_p.                                                     */
00027 /* If multiple objects or roots point to dest, the one reported             */
00028 /* will be the last on used by the garbage collector to trace the     */
00029 /* object.                                                    */
00030 /*   source is root ==> *base_p = address, *offset_p = 0             */
00031 /*   source is heap object ==> *base_p != 0, *offset_p = offset       */
00032 /*   Returns 1 on success, 0 if source couldn't be determined.        */
00033 /* Dest can be any address within a heap object.                      */
00034 typedef enum {  GC_UNREFERENCED, /* No reference info available.      */
00035               GC_NO_SPACE,  /* Dest not allocated with debug alloc  */
00036               GC_REFD_FROM_ROOT, /* Referenced directly by root *base_p */
00037               GC_REFD_FROM_REG,  /* Referenced from a register, i.e.  */
00038                                /* a root without an address.   */
00039               GC_REFD_FROM_HEAP, /* Referenced from another heap obj. */
00040               GC_FINALIZER_REFD /* Finalizable and hence accessible.  */
00041 } GC_ref_kind;
00042 
00043 GC_ref_kind GC_get_back_ptr_info(void *dest, void **base_p, size_t *offset_p);
00044 
00045 /* Generate a random heap address.            */
00046 /* The resulting address is in the heap, but  */
00047 /* not necessarily inside a valid object.     */
00048 void * GC_generate_random_heap_address(void);
00049 
00050 /* Generate a random address inside a valid marked heap object. */
00051 void * GC_generate_random_valid_address(void);
00052 
00053 /* Force a garbage collection and generate a backtrace from a */
00054 /* random heap address.                                       */
00055 /* This uses the GC logging mechanism (GC_printf) to produce  */
00056 /* output.  It can often be called from a debugger.  The      */
00057 /* source in dbg_mlc.c also serves as a sample client.        */
00058 void GC_generate_random_backtrace(void);
00059 
00060 /* Print a backtrace from a specific address.  Used by the     */
00061 /* above.  The client should call GC_gcollect() immediately    */
00062 /* before invocation.                                          */
00063 void GC_print_backtrace(void *);
00064 
00065 #endif /* GC_BACKPTR_H */