mono/sgen/sgen-client.h

   1 /**
   2  * \file
   3  * SGen client interface.
   4  *
   5  * Copyright (C) 2014 Xamarin Inc
   6  *
   7  * Licensed under the MIT license. See LICENSE file in the project root for full license information.
   8  */
   9
  10 #include "mono/sgen/sgen-pointer-queue.h"
  11
  12 /*
  13  * Init whatever needs initing.  This is called relatively early in SGen initialization.
  14  * Must initialized the small ID for the current thread.
  15  */
  16 void sgen_client_init (void);
  17
  18 /*
  19  * The slow path for getting an object's size.  We're passing in the vtable because we've
  20  * already fetched it.
  21  */
  22 mword sgen_client_slow_object_get_size (GCVTable vtable, GCObject* o);
  23
  24 /*
  25  * Fill the given range with a dummy object.  If the range is too short to be filled with an
  26  * object, null it.  Return `TRUE` if the range was filled with an object, `FALSE` if it was
  27  * nulled.
  28  */
  29 gboolean sgen_client_array_fill_range (char *start, size_t size);
  30
  31 /*
  32  * This is called if the nursery clearing policy at `clear-at-gc`, which is usually only
  33  * used for debugging.  If `size` is large enough for the memory to have been filled with a
  34  * dummy, object, zero its header.  Note that there might not actually be a header there.
  35  */
  36 void sgen_client_zero_array_fill_header (void *p, size_t size);
  37
  38 /*
  39  * Return whether the given object is an array fill dummy object.
  40  */
  41 gboolean sgen_client_object_is_array_fill (GCObject *o);
  42
  43 /*
  44  * Return whether the given finalizable object's finalizer is critical, i.e., needs to run
  45  * after all non-critical finalizers have run.
  46  */
  47 gboolean sgen_client_object_has_critical_finalizer (GCObject *obj);
  48
  49 /*
  50  * Called after an object is enqueued for finalization.  This is a very low-level callback.
  51  * It should almost certainly be a NOP.
  52  *
  53  * FIXME: Can we merge this with `sgen_client_object_has_critical_finalizer()`?
  54  */
  55 void sgen_client_object_queued_for_finalization (GCObject *obj);
  56
  57 /*
  58  * Run the given object's finalizer.
  59  */
  60 void sgen_client_run_finalize (GCObject *obj);
  61
  62 /*
  63  * Is called after a collection if there are objects to finalize.  The world is still
  64  * stopped.  This will usually notify the finalizer thread that it needs to run.
  65  */
  66 void sgen_client_finalize_notify (void);
  67
  68 /*
  69  * Returns TRUE if no ephemerons have been marked.  Will be called again if it returned
  70  * FALSE.  If ephemerons are not supported, just return TRUE.
  71  */
  72 gboolean sgen_client_mark_ephemerons (ScanCopyContext ctx)
  73     MONO_PERMIT (need (sgen_gc_locked));
  74
  75 /*
  76  * Clear ephemeron pairs with unreachable keys.
  77  * We pass the copy func so we can figure out if an array was promoted or not.
  78  */
  79 void sgen_client_clear_unreachable_ephemerons (ScanCopyContext ctx)
  80     MONO_PERMIT (need (sgen_gc_locked));
  81
  82 /*
  83  * May return NULL.  Must be an aligned pointer.
  84  */
  85 gpointer sgen_client_default_metadata (void);
  86 gpointer sgen_client_metadata_for_object (GCObject *obj);
  87
  88 /*
  89  * No action required.
  90  */
  91 void sgen_client_gchandle_created (int handle_type, GCObject *obj, guint32 handle);
  92 void sgen_client_gchandle_destroyed (int handle_type, guint32 handle);
  93 void sgen_client_ensure_weak_gchandles_accessible (void);
  94
  95 /*
  96  * This is called for objects that are larger than one card.  If it's possible to scan only
  97  * parts of the object based on which cards are marked, do so and return TRUE.  Otherwise,
  98  * return FALSE.
  99  */
 100 gboolean sgen_client_cardtable_scan_object (GCObject *obj, guint8 *cards, ScanCopyContext ctx);
 101
 102 /*
 103  * Called after nursery objects have been pinned.  No action is necessary.
 104  */
 105 void sgen_client_nursery_objects_pinned (void **definitely_pinned, int count);
 106
 107 /*
 108  * Called at a semi-random point during minor collections.  No action is necessary.
 109  */
 110 void sgen_client_collecting_minor_report_roots (SgenPointerQueue *fin_ready_queue, SgenPointerQueue *critical_fin_queue);
 111
 112 /*
 113  * Called at semi-random points during major collections.  No action is necessary.
 114  */
 115 void sgen_client_collecting_major_report_roots (SgenPointerQueue *fin_ready_queue, SgenPointerQueue *critical_fin_queue);
 116
 117 /*
 118  * Called after a LOS object has been pinned.  No action is necessary.
 119  */
 120 void sgen_client_pinned_los_object (GCObject *obj);
 121
 122 /*
 123  * Called for each cemented obj
 124  */
 125 void sgen_client_pinned_cemented_object (GCObject *obj);
 126
 127 /*
 128  * Called for each major heap obj pinned
 129  */
 130 void sgen_client_pinned_major_heap_object (GCObject *obj);
 131
 132 void sgen_client_pinning_start (void);
 133 void sgen_client_pinning_end (void);
 134
 135 /*
 136  * Called for every degraded allocation.  No action is necessary.
 137  */
 138 void sgen_client_degraded_allocation (void);
 139
 140 /*
 141  * Called whenever the amount of memory allocated for the managed heap changes.  No action
 142  * is necessary.
 143  */
 144 void sgen_client_total_allocated_heap_changed (size_t allocated_heap_size);
 145
 146 /*
 147  * If the client has registered any internal memory types, this must return a string
 148  * describing the given type.  Only used for debugging.
 149  */
 150 const char* sgen_client_description_for_internal_mem_type (int type);
 151
 152 /*
 153  * Only used for debugging.  `sgen_client_vtable_get_namespace()` may return NULL.
 154  */
 155 gboolean sgen_client_vtable_is_inited (GCVTable vtable);
 156 const char* sgen_client_vtable_get_namespace (GCVTable vtable);
 157 const char* sgen_client_vtable_get_name (GCVTable vtable);
 158
 159 /*
 160  * Called before starting collections.  The world is already stopped.  No action is
 161  * necessary.
 162  */
 163 void sgen_client_pre_collection_checks (void);
 164
 165 /*
 166  * Must set the thread's thread info to `info`.  If the thread's small ID was not already
 167  * initialized in `sgen_client_init()` (for the main thread, usually), it must be done here.
 168  *
 169  * `stack_bottom_fallback` is the value passed through via `sgen_thread_attach()`.
 170  */
 171 void sgen_client_thread_attach (SgenThreadInfo* info);
 172
 173 void sgen_client_thread_detach_with_lock (SgenThreadInfo *p);
 174
 175 /*
 176  * Called on each worker thread when it starts up.  Must initialize the thread's small ID.
 177  */
 178 void sgen_client_thread_register_worker (void);
 179
 180 /*
 181  * The least this function needs to do is scan all registers and thread stacks.  To do this
 182  * conservatively, use `sgen_conservatively_pin_objects_from()`.
 183  */
 184 void sgen_client_scan_thread_data (void *start_nursery, void *end_nursery, gboolean precise, ScanCopyContext ctx);
 185
 186 /*
 187  * Stop and restart the world, i.e., all threads that interact with the managed heap.  For
 188  * single-threaded programs this is a nop.
 189  */
 190 void sgen_client_stop_world (int generation, gboolean serial_collection)
 191     MONO_PERMIT (need (sgen_gc_locked));
 192 void sgen_client_restart_world (int generation, gboolean serial_collection, gint64 *stw_time)
 193     MONO_PERMIT (need (sgen_gc_locked));
 194
 195 /*
 196  * Must return FALSE.  The bridge is not supported outside of Mono.
 197  */
 198 gboolean sgen_client_bridge_need_processing (void);
 199
 200 /*
 201  * None of these should ever be called.
 202  */
 203 void sgen_client_bridge_reset_data (void);
 204 void sgen_client_bridge_processing_stw_step (void);
 205 void sgen_client_bridge_wait_for_processing (void);
 206 void sgen_client_bridge_processing_finish (int generation);
 207 gboolean sgen_client_bridge_is_bridge_object (GCObject *obj);
 208 void sgen_client_bridge_register_finalized_object (GCObject *object);
 209
 210 /*
 211  * No action is necessary.
 212  */
 213 void sgen_client_mark_togglerefs (char *start, char *end, ScanCopyContext ctx);
 214 void sgen_client_clear_togglerefs (char *start, char *end, ScanCopyContext ctx);
 215
 216 /*
 217  * Called to handle `MONO_GC_PARAMS` and `MONO_GC_DEBUG` options.  The `handle` functions
 218  * must return TRUE if they have recognized and processed the option, FALSE otherwise.
 219  */
 220 gboolean sgen_client_handle_gc_param (const char *opt);
 221 void sgen_client_print_gc_params_usage (void);
 222 gboolean sgen_client_handle_gc_debug (const char *opt);
 223 void sgen_client_print_gc_debug_usage (void);
 224
 225 /*
 226  * Called to obtain an identifier for the current location, such as a method pointer. This
 227  * is used for logging the provenances of allocations with the heavy binary protocol.
 228  */
 229 gpointer sgen_client_get_provenance (void);
 230
 231 /*
 232  * Called by the debugging infrastructure to describe pointers that have an invalid vtable.
 233  * Should usually print to `stdout`.
 234  */
 235 void sgen_client_describe_invalid_pointer (GCObject *ptr);
 236
 237 /*
 238  * Return the weak bitmap for a class
 239  */
 240 gsize *sgen_client_get_weak_bitmap (GCVTable vt, int *nbits);
 241
 242 /*
 243  * Scheduled @cv to be invoked later in the background.
 244  *
 245  * This function is idepotent WRT background execution. Meaning that calling it multiple times with the same funciton pointer before any bg execution happens will only call @cb once.
 246  */
 247 void sgen_client_schedule_background_job (void (*cb)(void));
 248
 249 /*
 250  * These client binary protocol functions are called from the respective binary protocol
 251  * functions.  No action is necessary.  We suggest implementing them as inline functions in
 252  * the client header file so that no overhead is incurred if they don't actually do
 253  * anything.
 254  */
 255
 256 #define TYPE_INT int
 257 #define TYPE_LONGLONG long long
 258 #define TYPE_SIZE size_t
 259 #define TYPE_POINTER gpointer
 260 #define TYPE_BOOL gboolean
 261
 262 #define BEGIN_PROTOCOL_ENTRY0(method) \
 263         void sgen_client_ ## method (void);
 264 #define BEGIN_PROTOCOL_ENTRY_HEAVY0(method) \
 265         void sgen_client_ ## method (void);
 266 #define BEGIN_PROTOCOL_ENTRY1(method,t1,f1) \
 267         void sgen_client_ ## method (t1 f1);
 268 #define BEGIN_PROTOCOL_ENTRY_HEAVY1(method,t1,f1) \
 269         void sgen_client_ ## method (t1 f1);
 270 #define BEGIN_PROTOCOL_ENTRY2(method,t1,f1,t2,f2) \
 271         void sgen_client_ ## method (t1 f1, t2 f2);
 272 #define BEGIN_PROTOCOL_ENTRY_HEAVY2(method,t1,f1,t2,f2) \
 273         void sgen_client_ ## method (t1 f1, t2 f2);
 274 #define BEGIN_PROTOCOL_ENTRY3(method,t1,f1,t2,f2,t3,f3) \
 275         void sgen_client_ ## method (t1 f1, t2 f2, t3 f3);
 276 #define BEGIN_PROTOCOL_ENTRY_HEAVY3(method,t1,f1,t2,f2,t3,f3) \
 277         void sgen_client_ ## method (t1 f1, t2 f2, t3 f3);
 278 #define BEGIN_PROTOCOL_ENTRY4(method,t1,f1,t2,f2,t3,f3,t4,f4) \
 279         void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4);
 280 #define BEGIN_PROTOCOL_ENTRY_HEAVY4(method,t1,f1,t2,f2,t3,f3,t4,f4) \
 281         void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4);
 282 #define BEGIN_PROTOCOL_ENTRY5(method,t1,f1,t2,f2,t3,f3,t4,f4,t5,f5) \
 283         void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4, t5 f5);
 284 #define BEGIN_PROTOCOL_ENTRY_HEAVY5(method,t1,f1,t2,f2,t3,f3,t4,f4,t5,f5) \
 285         void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4, t5 f5);
 286 #define BEGIN_PROTOCOL_ENTRY6(method,t1,f1,t2,f2,t3,f3,t4,f4,t5,f5,t6,f6) \
 287         void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4, t5 f5, t6 f6);
 288 #define BEGIN_PROTOCOL_ENTRY_HEAVY6(method,t1,f1,t2,f2,t3,f3,t4,f4,t5,f5,t6,f6) \
 289         void sgen_client_ ## method (t1 f1, t2 f2, t3 f3, t4 f4, t5 f5, t6 f6);
 290
 291 #define DEFAULT_PRINT()
 292 #define CUSTOM_PRINT(_)
 293
 294 #define IS_ALWAYS_MATCH(_)
 295 #define MATCH_INDEX(_)
 296 #define IS_VTABLE_MATCH(_)
 297
 298 #define END_PROTOCOL_ENTRY
 299 #define END_PROTOCOL_ENTRY_FLUSH
 300 #define END_PROTOCOL_ENTRY_HEAVY
 301
 302 #include "sgen-protocol-def.h"
 303
 304 #undef TYPE_INT
 305 #undef TYPE_LONGLONG
 306 #undef TYPE_SIZE
 307 #undef TYPE_POINTER
 308 #undef TYPE_BOOL
 309
 310 #ifdef SGEN_WITHOUT_MONO
 311 /*
 312  * Get the current thread's thread info.  This will only be called on managed threads.
 313  */
 314 SgenThreadInfo* mono_thread_info_current (void);
 315
 316 /*
 317  * Get the current thread's small ID.  This will be called on managed and worker threads.
 318  */
 319 int mono_thread_info_get_small_id (void);
 320
 321 #endif