/libs/headers/gc/gc_backptr.h

 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.                      */
34typedef 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
43GC_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.     */
48void * GC_generate_random_heap_address(void);
49
50/* Generate a random address inside a valid marked heap object. */
51void * 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.	      */
58void 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.						*/
63void GC_print_backtrace(void *);
64
65#endif /* GC_BACKPTR_H */