Return to gc_backptr.h CVS log

Up to [local] / OpenXM_contrib2 / asir2000 / gc / include

Annotation of OpenXM_contrib2/asir2000/gc/include/gc_backptr.h, Revision 1.3

1.1       noro        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 */