1 /*
2 * Copyright (c) 2007-2011 by Hewlett-Packard Company. All rights reserved.
3 *
4 * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
5 * OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
6 *
7 * Permission is hereby granted to use or copy this program
8 * for any purpose, provided the above notices are retained on all copies.
9 * Permission to modify the code and to distribute modified code is granted,
10 * provided the above notices are retained, and a notice that the code was
11 * modified is included with the above copyright notice.
12 */
13 14 #ifndef GC_DISCLAIM_H
15 #define GC_DISCLAIM_H
16 17 #include "gc.h"
18 19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 23 /*
24 * This API is defined only if the library has been suitably compiled
25 * (i.e. with `ENABLE_DISCLAIM` macro defined).
26 */
27 28 /**
29 * Prepare the object kind used by `GC_finalized_malloc`. Call it from
30 * your initialization code or, at least, at some point before using
31 * finalized allocations. The function is thread-safe.
32 */
33 GC_API void GC_CALL GC_init_finalized_malloc(void);
34 35 /** Type of a disclaim callback. Called with the allocator lock held. */
36 typedef int(GC_CALLBACK *GC_disclaim_proc)(void * /* `obj` */);
37 38 /**
39 * Register `proc` to be called on each object (of given `kind`) ready
40 * to be reclaimed. If `proc()` returns a nonzero value, the
41 * collector will not reclaim the object on this collection cycle
42 * (`proc()` should not try to resurrect the object otherwise); objects
43 * reachable from `proc()` (including the referred closure object) will
44 * be protected from collection if `mark_from_all` is nonzero, but at
45 * the expense that long chains of objects will take many cycles to
46 * reclaim. Any call to `GC_free()` deallocates the object (pointed by
47 * the argument) without inquiring `proc()`. Acquires the allocator lock.
48 * No-op in the find-leak mode.
49 */
50 GC_API void GC_CALL GC_register_disclaim_proc(int /* `kind` */,
51 GC_disclaim_proc /* `proc` */,
52 int /* `mark_from_all` */);
53 54 /** The finalizer closure used by `GC_finalized_malloc`. */
55 struct GC_finalizer_closure {
56 GC_finalization_proc proc;
57 void *cd;
58 };
59 60 /**
61 * Allocate an object which is to be finalized by the given closure.
62 * This uses a dedicated object kind with a disclaim procedure, and
63 * is more efficient than `GC_register_finalizer` and friends.
64 * `GC_init_finalized_malloc` must be called before using this.
65 * The collector will reclaim the object during this collection cycle
66 * (thus, `fc->proc()` should not try to resurrect the object).
67 * The other objects reachable from `fc->proc()` (including the closure
68 * object in case it is a heap-allocated one) will be protected from
69 * collection. Note that `GC_size()` (applied to such allocated object)
70 * returns a value slightly bigger than the specified allocation size,
71 * and that `GC_base()` result points to a "pointer-sized" word prior
72 * to the start of the allocated object.
73 * The disclaim procedure is not invoked in the find-leak mode.
74 * There is no debugging variant of this allocation function.
75 */
76 GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void *GC_CALL
77 GC_finalized_malloc(size_t /* `size` */,
78 const struct GC_finalizer_closure * /* `fc` */)
79 GC_ATTR_NONNULL(2);
80 81 #ifdef __cplusplus
82 } /* extern "C" */
83 #endif
84 85 #endif
86