1 /* 2 * Copyright (c) 1994 by Xerox Corporation. All rights reserved. 3 * Copyright (c) 1996 by Silicon Graphics. All rights reserved. 4 * Copyright (c) 1998 by Fergus Henderson. All rights reserved. 5 * Copyright (c) 2000-2009 by Hewlett-Packard Development Company. 6 * All rights reserved. 7 * 8 * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED 9 * OR IMPLIED. ANY USE IS AT YOUR OWN RISK. 10 * 11 * Permission is hereby granted to use or copy this program 12 * for any purpose, provided the above notices are retained on all copies. 13 * Permission to modify the code and to distribute modified code is granted, 14 * provided the above notices are retained, and a notice that the code was 15 * modified is included with the above copyright notice. 16 */ 17 18 /* 19 * This is a simple API to implement pointer back tracing, i.e. 20 * to answer questions such as "who is pointing to this" or 21 * "why is this object being retained by the collector" 22 * 23 * Most of these calls yield useful information on only after 24 * a garbage collection. Usually the client will first force 25 * a full collection and then gather information, preferably 26 * before much intervening allocation. 27 * 28 * The implementation of the interface is only about 99.9999% 29 * correct. It is intended to be good enough for profiling, 30 * but is not intended to be used with production code. 31 * 32 * Results are likely to be much more useful if all allocation is 33 * accomplished through the debugging allocators. 34 * 35 * The implementation idea is due to A. Demers. 36 */ 37 38 #ifndef GC_BACKPTR_H 39 #define GC_BACKPTR_H 40 41 #ifndef GC_H 42 # include "gc.h" 43 #endif 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /* Store information about the object referencing dest in *base_p */ 50 /* and *offset_p. */ 51 /* If multiple objects or roots point to dest, the one reported */ 52 /* will be the last on used by the garbage collector to trace the */ 53 /* object. */ 54 /* source is root ==> *base_p = address, *offset_p = 0 */ 55 /* source is heap object ==> *base_p != 0, *offset_p = offset */ 56 /* Returns 1 on success, 0 if source couldn't be determined. */ 57 /* Dest can be any address within a heap object. */ 58 typedef enum { 59 GC_UNREFERENCED, /* No reference info available. */ 60 GC_NO_SPACE, /* Dest not allocated with debug alloc. */ 61 GC_REFD_FROM_ROOT, /* Referenced directly by root *base_p. */ 62 GC_REFD_FROM_REG, /* Referenced from a register, i.e. */ 63 /* a root without an address. */ 64 GC_REFD_FROM_HEAP, /* Referenced from another heap obj. */ 65 GC_FINALIZER_REFD /* Finalizable and hence accessible. */ 66 } GC_ref_kind; 67 68 GC_API GC_ref_kind GC_CALL GC_get_back_ptr_info(void * /* dest */, 69 void ** /* base_p */, size_t * /* offset_p */) 70 GC_ATTR_NONNULL(1); 71 72 /* Generate a random heap address. */ 73 /* The resulting address is in the heap, but */ 74 /* not necessarily inside a valid object. */ 75 GC_API void * GC_CALL GC_generate_random_heap_address(void); 76 77 /* Generate a random address inside a valid marked heap object. */ 78 GC_API void * GC_CALL GC_generate_random_valid_address(void); 79 80 /* Force a garbage collection and generate a backtrace from a */ 81 /* random heap address. */ 82 /* This uses the GC logging mechanism (GC_printf) to produce */ 83 /* output. It can often be called from a debugger. The */ 84 /* source in dbg_mlc.c also serves as a sample client. */ 85 GC_API void GC_CALL GC_generate_random_backtrace(void); 86 87 /* Print a backtrace from a specific address. Used by the */ 88 /* above. The client should call GC_gcollect() immediately */ 89 /* before invocation. */ 90 GC_API void GC_CALL GC_print_backtrace(void *) GC_ATTR_NONNULL(1); 91 92 #ifdef __cplusplus 93 } /* extern "C" */ 94 #endif 95 96 #endif /* GC_BACKPTR_H */ 97