1 /*
2 * Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
3 * Copyright (c) 1991-1995 by Xerox Corporation. All rights reserved.
4 * Copyright 1996-1999 by Silicon Graphics. All rights reserved.
5 * Copyright 1999 by Hewlett-Packard Company. All rights reserved.
6 *
7 * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
8 * OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
9 *
10 * Permission is hereby granted to use or copy this program
11 * for any purpose, provided the above notices are retained on all copies.
12 * Permission to modify the code and to distribute modified code is granted,
13 * provided the above notices are retained, and a notice that the code was
14 * modified is included with the above copyright notice.
15 */
16 17 /*
18 * This file assumes the collector has been compiled with `GC_GCJ_SUPPORT`
19 * macro defined.
20 */
21 22 /*
23 * We allocate objects whose first element contains a pointer to a structure
24 * describing the object type. This structure contains a garbage collector
25 * mark descriptor at offset `GC_GCJ_MARK_DESCR_OFFSET`.
26 * Alternatively, the objects may be marked by the mark procedure passed
27 * to `GC_init_gcj_malloc_mp()`.
28 */
29 30 #ifndef GC_GCJ_H
31 #define GC_GCJ_H
32 33 #ifndef GC_H
34 # include "gc.h"
35 #endif
36 37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40 41 /*
42 * The offset of the garbage collector mark descriptor inside the
43 * structure describing the object type ("vtable"). `gcj` keeps the
44 * mark descriptor as the second "pointer-sized" word of "vtable".
45 * Probably this needs to be adjusted for other clients. It is assumed
46 * that this offset is not smaller than the size of a pointer (the
47 * assumption allows objects on the free list to be marked normally).
48 */
49 #ifndef GC_GCJ_MARK_DESCR_OFFSET
50 # define GC_GCJ_MARK_DESCR_OFFSET GC_SIZEOF_PTR
51 #endif
52 53 /**
54 * This function must be called before the `gcj` allocators are invoked.
55 * `mp_index` and `mp` are the index and mark procedure (see `gc_mark.h`
56 * file), respectively, for the allocated objects. `mp` will be used to
57 * build the descriptor for objects allocated through the debugging
58 * interface; it will be invoked on all such objects with an `env` value
59 * of 1. The client may choose to use the same mark procedure (`mp`) for
60 * some of its generated mark descriptors. In that case, it should use
61 * a different `env` value to detect the presence or absence of the debug
62 * header. `mp` is really of type `GC_mark_proc`, as defined in `gc_mark.h`
63 * file; we do not want to include that here for namespace pollution reasons.
64 * Passing in `mp_index` here instead of having `GC_init_gcj_malloc()`
65 * internally call `GC_new_proc()` is quite ugly, but in typical usage
66 * scenarios a compiler also has to know about `mp_index`, so generating it
67 * dynamically is not acceptable. The `mp_index` will typically be
68 * an integer less than `RESERVED_MARK_PROCS`, so that it does not collide
69 * with indices allocated by `GC_new_proc()`. If the application needs
70 * no other reserved indices, zero (`GC_GCJ_RESERVED_MARK_PROC_INDEX` in
71 * `gc_mark.h` file) is an obvious choice. Deprecated, portable clients
72 * should include `gc_mark.h` file and use `GC_init_gcj_malloc_mp()` instead.
73 */
74 GC_API GC_ATTR_DEPRECATED void GC_CALL GC_init_gcj_malloc(int /* `mp_index` */,
75 void * /* `mp` */);
76 77 /**
78 * Allocate an object, clear it, and store the pointer to the type
79 * structure ("vtable" in `gcj`). This adds a byte at the end of the
80 * object if `GC_malloc()` would. In case of out of memory,
81 * `GC_oom_fn()` is called and its result is returned.
82 */
83 GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void *GC_CALL
84 GC_gcj_malloc(size_t /* `lb` */, const void * /* `vtable_ptr` */);
85 86 /**
87 * Similar to `GC_gcj_malloc`, but add the debug info. This is allocated
88 * with `GC_gcj_debug_kind`.
89 */
90 GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void *GC_CALL
91 GC_debug_gcj_malloc(size_t /* `lb` */, const void * /* `vtable_ptr` */,
92 GC_EXTRA_PARAMS);
93 94 /**
95 * Similar to `GC_gcj_malloc`, but assumes that a pointer to near the
96 * beginning (i.e. within the first heap block) of the allocated object
97 * is always maintained.
98 */
99 GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void *GC_CALL
100 GC_gcj_malloc_ignore_off_page(size_t /* `lb` */,
101 const void * /* `vtable_ptr` */);
102 103 /**
104 * The kind numbers of normal and debug `gcj` objects. Useful only for
105 * debug support, we hope.
106 */
107 GC_API int GC_gcj_kind;
108 GC_API int GC_gcj_debug_kind;
109 110 #ifdef GC_DEBUG
111 # define GC_GCJ_MALLOC(s, d) GC_debug_gcj_malloc(s, d, GC_EXTRAS)
112 # define GC_GCJ_MALLOC_IGNORE_OFF_PAGE(s, d) GC_GCJ_MALLOC(s, d)
113 #else
114 # define GC_GCJ_MALLOC(s, d) GC_gcj_malloc(s, d)
115 # define GC_GCJ_MALLOC_IGNORE_OFF_PAGE(s, d) \
116 GC_gcj_malloc_ignore_off_page(s, d)
117 #endif
118 119 #ifdef __cplusplus
120 } /* extern "C" */
121 #endif
122 123 #endif /* GC_GCJ_H */
124