mono/sgen/sgen-client.h

   1 /*
   2  * sgen-client.h: SGen client interface.
   3  *
   4  * Copyright (C) 2014 Xamarin Inc
   5  *
   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;
   9  *
  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.
  14  *
  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.
  18  */
  19
  20 #include "mono/sgen/sgen-pointer-queue.h"
  21
  22 /*
  23  * Init whatever needs initing.  This is called relatively early in SGen initialization.
  24  * Must initialized the small ID for the current thread.
  25  */
  26 void sgen_client_init (void);
  27
  28 /*
  29  * The slow path for getting an object's size.  We're passing in the vtable because we've
  30  * already fetched it.
  31  */
  32 mword sgen_client_slow_object_get_size (GCVTable vtable, GCObject* o);
  33
  34 /*
  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
  37  * nulled.
  38  */
  39 gboolean sgen_client_array_fill_range (char *start, size_t size);
  40
  41 /*
  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.
  45  */
  46 void sgen_client_zero_array_fill_header (void *p, size_t size);
  47
  48 /*
  49  * Return whether the given object is an array fill dummy object.
  50  */
  51 gboolean sgen_client_object_is_array_fill (GCObject *o);
  52
  53 /*
  54  * Return whether the given finalizable object's finalizer is critical, i.e., needs to run
  55  * after all non-critical finalizers have run.
  56  */
  57 gboolean sgen_client_object_has_critical_finalizer (GCObject *obj);
  58
  59 /*
  60  * Called after an object is enqueued for finalization.  This is a very low-level callback.
  61  * It should almost certainly be a NOP.
  62  *
  63  * FIXME: Can we merge this with `sgen_client_object_has_critical_finalizer()`?
  64  */
  65 void sgen_client_object_queued_for_finalization (GCObject *obj);
  66
  67 /*
  68  * Run the given object's finalizer.
  69  */
  70 void sgen_client_run_finalize (GCObject *obj);
  71
  72 /*
  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.
  75  */
  76 void sgen_client_finalize_notify (void);
  77
  78 /*
  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.
  81  */
  82 gboolean sgen_client_mark_ephemerons (ScanCopyContext ctx);
  83
  84 /*
  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.
  87  */
  88 void sgen_client_clear_unreachable_ephemerons (ScanCopyContext ctx);
  89
  90 /*
  91  * May return NULL.  Must be an aligned pointer.
  92  */
  93 gpointer sgen_client_default_metadata (void);
  94 gpointer sgen_client_metadata_for_object (GCObject *obj);
  95
  96 /*
  97  * No action required.
  98  */
  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);
 102
 103 /*
 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,
 106  * return FALSE.
 107  */
 108 gboolean sgen_client_cardtable_scan_object (GCObject *obj, mword block_obj_size, guint8 *cards, gboolean mod_union, ScanCopyContext ctx);
 109
 110 /*
 111  * Called after nursery objects have been pinned.  No action is necessary.
 112  */
 113 void sgen_client_nursery_objects_pinned (void **definitely_pinned, int count);
 114
 115 /*
 116  * Called at a semi-random point during minor collections.  No action is necessary.
 117  */
 118 void sgen_client_collecting_minor (SgenPointerQueue *fin_ready_queue, SgenPointerQueue *critical_fin_queue);
 119
 120 /*
 121  * Called at semi-random points during major collections.  No action is necessary.
 122  */
 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);
 126
 127 /*
 128  * Called after a LOS object has been pinned.  No action is necessary.
 129  */
 130 void sgen_client_pinned_los_object (GCObject *obj);
 131
 132 /*
 133  * Called for every degraded allocation.  No action is necessary.
 134  */
 135 void sgen_client_degraded_allocation (size_t size);
 136
 137 /*
 138  * Called whenever the amount of memory allocated for the managed heap changes.  No action
 139  * is necessary.
 140  */
 141 void sgen_client_total_allocated_heap_changed (size_t allocated_heap_size);
 142
 143 /*
 144  * Called when an object allocation fails.  The suggested action is to abort the program.
 145  *
 146  * FIXME: Don't we want to return a BOOL here that indicates whether to retry the
 147  * allocation?
 148  */
 149 void sgen_client_out_of_memory (size_t size);
 150
 151 /*
 152  * If the client has registered any internal memory types, this must return a string
 153  * describing the given type.  Only used for debugging.
 154  */
 155 const char* sgen_client_description_for_internal_mem_type (int type);
 156
 157 /*
 158  * Only used for debugging.  `sgen_client_vtable_get_namespace()` may return NULL.
 159  */
 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);
 163
 164 /*
 165  * Called before starting collections.  The world is already stopped.  No action is
 166  * necessary.
 167  */
 168 void sgen_client_pre_collection_checks (void);
 169
 170 /*
 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.
 173  *
 174  * `stack_bottom_fallback` is the value passed through via `sgen_thread_register()`.
 175  */
 176 void sgen_client_thread_register (SgenThreadInfo* info, void *stack_bottom_fallback);
 177
 178 void sgen_client_thread_unregister (SgenThreadInfo *p);
 179
 180 /*
 181  * Called on each worker thread when it starts up.  Must initialize the thread's small ID.
 182  */
 183 void sgen_client_thread_register_worker (void);
 184
 185 /*
 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()`.
 188  */
 189 void sgen_client_scan_thread_data (void *start_nursery, void *end_nursery, gboolean precise, ScanCopyContext ctx);
 190
 191 /*
 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.
 194  */
 195 void sgen_client_stop_world (int generation);
 196 void sgen_client_restart_world (int generation, GGTimingInfo *timing);
 197
 198 /*
 199  * Must return FALSE.  The bridge is not supported outside of Mono.
 200  */
 201 gboolean sgen_client_bridge_need_processing (void);
 202
 203 /*
 204  * None of these should ever be called.
 205  */
 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);
 212
 213 /*
 214  * No action is necessary.
 215  */
 216 void sgen_client_mark_togglerefs (char *start, char *end, ScanCopyContext ctx);
 217 void sgen_client_clear_togglerefs (char *start, char *end, ScanCopyContext ctx);
 218
 219 /*
 220  * Called after collections, reporting the amount of time they took.  No action is
 221  * necessary.
 222  */
 223 void sgen_client_log_timing (GGTimingInfo *info, mword last_major_num_sections, mword last_los_memory_usage);
 224
 225 /*
 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.
 228  */
 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);
 233
 234 /*
 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.
 237  */
 238 gpointer sgen_client_get_provenance (void);
 239
 240 /*
 241  * Called by the debugging infrastructure to describe pointers that have an invalid vtable.
 242  * Should usually print to `stdout`.
 243  */
 244 void sgen_client_describe_invalid_pointer (GCObject *ptr);
 245
 246 /*
 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
 250  * anything.
 251  */
 252
 253 #define TYPE_INT int
 254 #define TYPE_LONGLONG long long
 255 #define TYPE_SIZE size_t
 256 #define TYPE_POINTER gpointer
 257 #define TYPE_BOOL gboolean
 258
 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);
 287
 288 #define DEFAULT_PRINT()
 289 #define CUSTOM_PRINT(_)
 290
 291 #define IS_ALWAYS_MATCH(_)
 292 #define MATCH_INDEX(_)
 293 #define IS_VTABLE_MATCH(_)
 294
 295 #define END_PROTOCOL_ENTRY
 296 #define END_PROTOCOL_ENTRY_FLUSH
 297 #define END_PROTOCOL_ENTRY_HEAVY
 298
 299 #include "sgen-protocol-def.h"
 300
 301 #undef TYPE_INT
 302 #undef TYPE_LONGLONG
 303 #undef TYPE_SIZE
 304 #undef TYPE_POINTER
 305 #undef TYPE_BOOL
 306
 307 #ifdef SGEN_WITHOUT_MONO
 308 /*
 309  * Get the current thread's thread info.  This will only be called on managed threads.
 310  */
 311 SgenThreadInfo* mono_thread_info_current (void);
 312
 313 /*
 314  * Get the current thread's small ID.  This will be called on managed and worker threads.
 315  */
 316 int mono_thread_info_get_small_id (void);
 317 #endif