Return to backptr.h CVS log

Up to [local] / OpenXM_contrib / gc / include

Annotation of OpenXM_contrib/gc/include/backptr.h, Revision 1.1.1.2

1.1       maekawa     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: /* Store information about the object referencing dest in *base_p     */
                     24: /* and *offset_p.                                                     */
                     25: /* If multiple objects or roots point to dest, the one reported              */
                     26: /* will be the last on used by the garbage collector to trace the     */
                     27: /* object.                                                           */
                     28: /*   source is root ==> *base_p = address, *offset_p = 0             */
                     29: /*   source is heap object ==> *base_p != 0, *offset_p = offset       */
                     30: /*   Returns 1 on success, 0 if source couldn't be determined.        */
                     31: /* Dest can be any address within a heap object.                      */
1.1.1.2 ! maekawa    32: typedef enum {  GC_UNREFERENCED, /* No reference info available.       */
1.1       maekawa    33:                GC_NO_SPACE,    /* Dest not allocated with debug alloc  */
                     34:                GC_REFD_FROM_ROOT, /* Referenced directly by root *base_p */
1.1.1.2 ! maekawa    35:                GC_REFD_FROM_REG,  /* Referenced from a register, i.e.  */
        !            36:                                   /* a root without an address.        */
1.1       maekawa    37:                GC_REFD_FROM_HEAP, /* Referenced from another heap obj. */
                     38:                GC_FINALIZER_REFD /* Finalizable and hence accessible.  */
                     39: } GC_ref_kind;
                     40:
                     41: GC_ref_kind GC_get_back_ptr_info(void *dest, void **base_p, size_t *offset_p);
                     42:
                     43: /* Generate a random heap address.            */
                     44: /* The resulting address is in the heap, but  */
                     45: /* not necessarily inside a valid object.     */
                     46: void * GC_generate_random_heap_address(void);
                     47:
                     48: /* Generate a random address inside a valid marked heap object. */
                     49: void * GC_generate_random_valid_address(void);
                     50:
                     51: /* Force a garbage collection and generate a backtrace from a */
                     52: /* random heap address.                                       */
                     53: /* This uses the GC logging mechanism (GC_printf) to produce  */
                     54: /* output.  It can often be called from a debugger.  The      */
                     55: /* source in dbg_mlc.c also serves as a sample client.       */
                     56: void GC_generate_random_backtrace(void);
1.1.1.2 ! maekawa    57:
        !            58: /* Print a backtrace from a specific address.  Used by the     */
        !            59: /* above.  The client should call GC_gcollect() immediately    */
        !            60: /* before invocation.                                          */
        !            61: void GC_print_backtrace(void *);
1.1       maekawa    62:
                     63: