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.1

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.                      */
                     32: typedef enum {  GC_UNREFERENCED, /* No refence info available.         */
                     33:                GC_NO_SPACE,    /* Dest not allocated with debug alloc  */
                     34:                GC_REFD_FROM_ROOT, /* Referenced directly by root *base_p */
                     35:                GC_REFD_FROM_HEAP, /* Referenced from another heap obj. */
                     36:                GC_FINALIZER_REFD /* Finalizable and hence accessible.  */
                     37: } GC_ref_kind;
                     38:
                     39: GC_ref_kind GC_get_back_ptr_info(void *dest, void **base_p, size_t *offset_p);
                     40:
                     41: /* Generate a random heap address.            */
                     42: /* The resulting address is in the heap, but  */
                     43: /* not necessarily inside a valid object.     */
                     44: void * GC_generate_random_heap_address(void);
                     45:
                     46: /* Generate a random address inside a valid marked heap object. */
                     47: void * GC_generate_random_valid_address(void);
                     48:
                     49: /* Force a garbage collection and generate a backtrace from a */
                     50: /* random heap address.                                       */
                     51: /* This uses the GC logging mechanism (GC_printf) to produce  */
                     52: /* output.  It can often be called from a debugger.  The      */
                     53: /* source in dbg_mlc.c also serves as a sample client.       */
                     54: void GC_generate_random_backtrace(void);
                     55:
                     56: