2 * sgen-client.h: SGen client interface.
4 * Copyright (C) 2014 Xamarin Inc
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License 2.0 as published by the Free Software Foundation;
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
15 * You should have received a copy of the GNU Library General Public
16 * License 2.0 along with this library; if not, write to the Free
17 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
20 #include "mono/sgen/sgen-pointer-queue.h"
23 * Init whatever needs initing. This is called relatively early in SGen initialization.
24 * Must initialized the small ID for the current thread.
26 void sgen_client_init (void);
29 * The slow path for getting an object's size. We're passing in the vtable because we've
32 mword sgen_client_slow_object_get_size (GCVTable vtable, GCObject* o);
35 * Fill the given range with a dummy object. If the range is too short to be filled with an
36 * object, null it. Return `TRUE` if the range was filled with an object, `FALSE` if it was
39 gboolean sgen_client_array_fill_range (char *start, size_t size);
42 * This is called if the nursery clearing policy at `clear-at-gc`, which is usually only
43 * used for debugging. If `size` is large enough for the memory to have been filled with a
44 * dummy, object, zero its header. Note that there might not actually be a header there.
46 void sgen_client_zero_array_fill_header (void *p, size_t size);
49 * Return whether the given object is an array fill dummy object.
51 gboolean sgen_client_object_is_array_fill (GCObject *o);
54 * Return whether the given finalizable object's finalizer is critical, i.e., needs to run
55 * after all non-critical finalizers have run.
57 gboolean sgen_client_object_has_critical_finalizer (GCObject *obj);
60 * Called after an object is enqueued for finalization. This is a very low-level callback.
61 * It should almost certainly be a NOP.
63 * FIXME: Can we merge this with `sgen_client_object_has_critical_finalizer()`?
65 void sgen_client_object_queued_for_finalization (GCObject *obj);
68 * Run the given object's finalizer.
70 void sgen_client_run_finalize (GCObject *obj);
73 * Is called after a collection if there are objects to finalize. The world is still
74 * stopped. This will usually notify the finalizer thread that it needs to run.
76 void sgen_client_finalize_notify (void);
79 * Returns TRUE if no ephemerons have been marked. Will be called again if it returned
80 * FALSE. If ephemerons are not supported, just return TRUE.
82 gboolean sgen_client_mark_ephemerons (ScanCopyContext ctx);
85 * Clear ephemeron pairs with unreachable keys.
86 * We pass the copy func so we can figure out if an array was promoted or not.
88 void sgen_client_clear_unreachable_ephemerons (ScanCopyContext ctx);
91 * May return NULL. Must be an aligned pointer.
93 gpointer sgen_client_default_metadata (void);
94 gpointer sgen_client_metadata_for_object (GCObject *obj);
99 void sgen_client_gchandle_created (int handle_type, GCObject *obj, guint32 handle);
100 void sgen_client_gchandle_destroyed (int handle_type, guint32 handle);
101 void sgen_client_ensure_weak_gchandles_accessible (void);
104 * This is called for objects that are larger than one card. If it's possible to scan only
105 * parts of the object based on which cards are marked, do so and return TRUE. Otherwise,
108 gboolean sgen_client_cardtable_scan_object (GCObject *obj, mword block_obj_size, guint8 *cards, gboolean mod_union, ScanCopyContext ctx);
111 * Called after nursery objects have been pinned. No action is necessary.
113 void sgen_client_nursery_objects_pinned (void **definitely_pinned, int count);
116 * Called at a semi-random point during minor collections. No action is necessary.
118 void sgen_client_collecting_minor (SgenPointerQueue *fin_ready_queue, SgenPointerQueue *critical_fin_queue);
121 * Called at semi-random points during major collections. No action is necessary.
123 void sgen_client_collecting_major_1 (void);
124 void sgen_client_collecting_major_2 (void);
125 void sgen_client_collecting_major_3 (SgenPointerQueue *fin_ready_queue, SgenPointerQueue *critical_fin_queue);
128 * Called after a LOS object has been pinned. No action is necessary.
130 void sgen_client_pinned_los_object (GCObject *obj);
133 * Called for every degraded allocation. No action is necessary.
135 void sgen_client_degraded_allocation (size_t size);
138 * Called whenever the amount of memory allocated for the managed heap changes. No action
141 void sgen_client_total_allocated_heap_changed (size_t allocated_heap_size);
144 * Called when an object allocation fails. The suggested action is to abort the program.
146 * FIXME: Don't we want to return a BOOL here that indicates whether to retry the
149 void sgen_client_out_of_memory (size_t size);
152 * If the client has registered any internal memory types, this must return a string
153 * describing the given type. Only used for debugging.
155 const char* sgen_client_description_for_internal_mem_type (int type);
158 * Only used for debugging. `sgen_client_vtable_get_namespace()` may return NULL.
160 gboolean sgen_client_vtable_is_inited (GCVTable vtable);
161 const char* sgen_client_vtable_get_namespace (GCVTable vtable);
162 const char* sgen_client_vtable_get_name (GCVTable vtable);
165 * Called before starting collections. The world is already stopped. No action is
168 void sgen_client_pre_collection_checks (void);
171 * Must set the thread's thread info to `info`. If the thread's small ID was not already
172 * initialized in `sgen_client_init()` (for the main thread, usually), it must be done here.
174 * `stack_bottom_fallback` is the value passed through via `sgen_thread_register()`.
176 void sgen_client_thread_register (SgenThreadInfo* info, void *stack_bottom_fallback);
178 void sgen_client_thread_unregister (SgenThreadInfo *p);
181 * Called on each worker thread when it starts up. Must initialize the thread's small ID.
183 void sgen_client_thread_register_worker (void);
186 * The least this function needs to do is scan all registers and thread stacks. To do this
187 * conservatively, use `sgen_conservatively_pin_objects_from()`.
189 void sgen_client_scan_thread_data (void *start_nursery, void *end_nursery, gboolean precise, ScanCopyContext ctx);
192 * Stop and restart the world, i.e., all threads that interact with the managed heap. For
193 * single-threaded programs this is a nop.
195 void sgen_client_stop_world (int generation);
196 void sgen_client_restart_world (int generation, GGTimingInfo *timing);
199 * Must return FALSE. The bridge is not supported outside of Mono.
201 gboolean sgen_client_bridge_need_processing (void);
204 * None of these should ever be called.
206 void sgen_client_bridge_reset_data (void);
207 void sgen_client_bridge_processing_stw_step (void);
208 void sgen_client_bridge_wait_for_processing (void);
209 void sgen_client_bridge_processing_finish (int generation);
210 gboolean sgen_client_bridge_is_bridge_object (GCObject *obj);
211 void sgen_client_bridge_register_finalized_object (GCObject *object);
214 * No action is necessary.
216 void sgen_client_mark_togglerefs (char *start, char *end, ScanCopyContext ctx);
217 void sgen_client_clear_togglerefs (char *start, char *end, ScanCopyContext ctx);
220 * Called after collections, reporting the amount of time they took. No action is
223 void sgen_client_log_timing (GGTimingInfo *info, mword last_major_num_sections, mword last_los_memory_usage);
226 * Called to handle `MONO_GC_PARAMS` and `MONO_GC_DEBUG` options. The `handle` functions
227 * must return TRUE if they have recognized and processed the option, FALSE otherwise.
229 gboolean sgen_client_handle_gc_param (const char *opt);
230 void sgen_client_print_gc_params_usage (void);
231 gboolean sgen_client_handle_gc_debug (const char *opt);
232 void sgen_client_print_gc_debug_usage (void);
235 * Called to obtain an identifier for the current location, such as a method pointer. This
236 * is used for logging the provenances of allocations with the heavy binary protocol.
238 gpointer sgen_client_get_provenance (void);
241 * Called by the debugging infrastructure to describe pointers that have an invalid vtable.
242 * Should usually print to `stdout`.
244 void sgen_client_describe_invalid_pointer (GCObject *ptr);
247 * These client binary protocol functions are called from the respective binary protocol
248 * functions. No action is necessary. We suggest implementing them as inline functions in
249 * the client header file so that no overhead is incurred if they don't actually do
254 #define TYPE_LONGLONG long long
255 #define TYPE_SIZE size_t
256 #define TYPE_POINTER gpointer
257 #define TYPE_BOOL gboolean
259 #define BEGIN_PROTOCOL_ENTRY0(method) \
260 void sgen_client_ ## method (void);
261 #define BEGIN_PROTOCOL_ENTRY_HEAVY0(method) \
262 void sgen_client_ ## method (void);
263 #define BEGIN_PROTOCOL_ENTRY1(method,t1,f1) \
264 void sgen_client_ ## method (t1 f1);
265 #define BEGIN_PROTOCOL_ENTRY_HEAVY1(method,t1,f1) \
266 void sgen_client_ ## method (t1 f1);
267 #define BEGIN_PROTOCOL_ENTRY2(method,t1,f1,t2,f2) \
268 void sgen_client_ ## method (t1 f1, t2 f2);
269 #define BEGIN_PROTOCOL_ENTRY_HEAVY2(method,t1,f1,t2,f2) \
270 void sgen_client_ ## method (t1 f1, t2 f2);
271 #define BEGIN_PROTOCOL_ENTRY3(method,t1,f1,t2,f2,t3,f3) \
272 void sgen_client_ ## method (t1 f1, t2 f2, t3 f3);
273 #define BEGIN_PROTOCOL_ENTRY_HEAVY3(method,t1,f1,t2,f2,t3,f3) \
274 void sgen_client_ ## method (t1 f1, t2 f2, t3 f3);
275 #define BEGIN_PROTOCOL_ENTRY4(method,t1,f1,t2,f2,t3,f3,t4,f4) \
276 void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4);
277 #define BEGIN_PROTOCOL_ENTRY_HEAVY4(method,t1,f1,t2,f2,t3,f3,t4,f4) \
278 void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4);
279 #define BEGIN_PROTOCOL_ENTRY5(method,t1,f1,t2,f2,t3,f3,t4,f4,t5,f5) \
280 void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4, t5 f5);
281 #define BEGIN_PROTOCOL_ENTRY_HEAVY5(method,t1,f1,t2,f2,t3,f3,t4,f4,t5,f5) \
282 void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4, t5 f5);
283 #define BEGIN_PROTOCOL_ENTRY6(method,t1,f1,t2,f2,t3,f3,t4,f4,t5,f5,t6,f6) \
284 void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4, t5 f5, t6 f6);
285 #define BEGIN_PROTOCOL_ENTRY_HEAVY6(method,t1,f1,t2,f2,t3,f3,t4,f4,t5,f5,t6,f6) \
286 void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4, t5 f5, t6 f6);
288 #define DEFAULT_PRINT()
289 #define CUSTOM_PRINT(_)
291 #define IS_ALWAYS_MATCH(_)
292 #define MATCH_INDEX(_)
293 #define IS_VTABLE_MATCH(_)
295 #define END_PROTOCOL_ENTRY
296 #define END_PROTOCOL_ENTRY_FLUSH
297 #define END_PROTOCOL_ENTRY_HEAVY
299 #include "sgen-protocol-def.h"
307 #ifdef SGEN_WITHOUT_MONO
309 * Get the current thread's thread info. This will only be called on managed threads.
311 SgenThreadInfo* mono_thread_info_current (void);
314 * Get the current thread's small ID. This will be called on managed and worker threads.
316 int mono_thread_info_get_small_id (void);