Attachment 'gc_interface.txt'Download
1 /** 2 * @file 3 * GC interface exposed to VM. 4 * 5 * 6 * In order to eliminate dependency on certain types such as (VTable *) we 7 * have eliminated them from this interface and replace them with (void *). 8 * While this might appear to be unfortunate it allows us to eliminate any 9 * knowledge of the class and VTable structures that are not of interest 10 * to the GC. 11 */ 12 13 14 /* 15 * ***** 16 * * 17 * * Routines to support the initialization and termination of GC. 18 * * 19 * ***** 20 */ 21 22 /** 23 * Is called by VM to start GC initialization sequence. 24 * 25 * This function is expected to initialize the GC internal data structures. 26 * The VM should call this *before* any other calls to this interface 27 * The GC assumes that the VM is ready to support a GC if it 28 * calls this function. 29 */ 30 GCExport void gc_init(); 31 32 /** 33 * may be called at various points the VM decides are GC-safe. 34 * The GC may ignore this, or it may force a root set enumeration, or it may 35 * execute a full GC. 36 * 37 * @note Optional debug interface. 38 */ 39 GCExport void gc_test_safepoint(); 40 41 42 43 44 /** 45 * If the GC supports a "bump-the-pointer" style allocation, where the GC's 46 * thread-local information contains a "current" pointer and a "limit" pointer, 47 * then it should return TRUE, and it should set *offset_of_current to be the 48 * offset into the GC thread block of the "current" pointer, and similar for 49 * *offset_of_limit and the "limit" pointer. If not, then it should return 50 * FALSE. 51 */ 52 GCExport Boolean gc_supports_frontier_allocation(unsigned *offset_of_current, unsigned *offset_of_limit); 53 54 55 56 57 /** 58 * This API is used by the VM to notify the GC that the 59 * VM has completed bootstrapping and initialization, and 60 * is henceforth ready to field requests for enumerating 61 * live references. 62 * 63 * Prior to this function being called the GC might see some 64 * strange sights such as NULL or incomplete vtables. The GC will 65 * need to consider these as normal and work with the VM to ensure 66 * that bootstrapping works. This means that the GC will make few 67 * demands on the VM prior to this routine being called. 68 * 69 * However, once called the GC will feel free to do 70 * stop-the-world collections and will assume that the entire 71 * gc_import.h interface is available and fully functioning. 72 * 73 * If this routine is called twice the result is undefined. 74 */ 75 GCExport void gc_vm_initialized(); 76 77 78 79 /** 80 * This is called once the VM has no use for the heap or the 81 * garbage collector data structures. The assumption is that the 82 * VM is exiting but needs to give the GC time to run destructors 83 * and free up memory it has gotten from the OS. 84 * After this routine has been called the VM can not relie on any 85 * data structures created by the GC. 86 * 87 * Errors: If gc_enumerate_finalizable_objects has been called and 88 * gc_wrapup gc discovers an object that has not had it 89 * finalizer run then it will attempt to report an error. 90 */ 91 GCExport void gc_wrapup(); 92 93 94 95 /** 96 * Is called by the VM to enumerate the root reference. 97 */ 98 GCExport void gc_add_root_set_entry(Managed_Object_Handle *ref, Boolean is_pinned); 99 100 /** 101 * Resembles gc_add_root_set_entry() but is passed the address of a slot 102 * containing a compressed reference. 103 */ 104 GCExport void gc_add_compressed_root_set_entry(uint32 *ref, Boolean is_pinned); 105 106 /** 107 * Is called by the VM to enumerate weak root reference. 108 * 109 * @param slot An pointer to the slot, containing the weak root 110 * @param is_pinned TRUE denotes that object pointed-to from this slot 111 * should not be moved during garbage collection. 112 * @param is_short_weak TRUE means that the weak root must be cleared 113 * before object becomes eligible for finalization. 114 */ 115 GCExport void gc_add_weak_root_set_entry(Managed_Object_Handle *slot, 116 Boolean is_pinned, Boolean is_short_weak); 117 118 /* 119 * ***** 120 * * 121 * * Routines to support the allocation and initialization of objects. 122 * * 123 * ***** 124 */ 125 126 127 /** 128 * This routine is the primary routine used to allocate objects. 129 * It assumes nothing about the state of the VM internal data 130 * structures or the runtime stack. If gc_malloc_or_null is able 131 * to allocate the object without invoking a GC or calling the VM 132 * then it does so. It places p_vtable into the object, ensures 133 * that the object is zeroed and then returns a ManagedObject 134 * pointer to the object. If it is not able to allocate the object 135 * without invoking a GC then it returns NULL. 136 * 137 * @param size - the size of the object to allocate. If the high bit 138 * set then various constraints as described above are 139 * placed on the allocation of this object. 140 * @param type - a pointer to the vtable of the class being 141 * allocated. This routine will place this value 142 * in the appropriate slot of the new object. 143 * @param thread_pointer - a pointer to the GC's thread-local space. 144 * 145 * This is like gc_malloc_or_null, except that it passes a pointer to 146 * the thread's GC-specific space as a third argument. This prevents 147 * the GC from having to immediately call vm_get_thread_curr_alloc_block() 148 * as its first task. 149 * 150 * @note rename of gc_malloc_with_thread_pointer() 151 */ 152 GCExport Managed_Object_Handle gc_alloc_fast(unsigned size, 153 Allocation_Handle type, 154 void *thread_pointer); 155 156 /** 157 * This routine is used to allocate an object. See the above 158 * discussion on the overloading of size. {link allocation} 159 * 160 * @param size - the size of the object to allocate. If the high bit 161 * set then various constraints as described above are 162 * placed on the allocation of this object. 163 * @param type - a pointer to the vtable of the class being allocated. 164 * This routine will place this value in the 165 * appropriate slot of the new object. 166 * @param thread_pointer - a pointer to the GC's thread-local space. 167 * 168 * @note rename of gc_malloc_or_null_with_thread_pointer() 169 */ 170 GCExport Managed_Object_Handle gc_alloc(unsigned size, 171 Allocation_Handle type, 172 void *thread_pointer); 173 174 175 /** 176 * For bootstrapping situations, when we still don't have 177 * a class for the object. This routine is only available prior to 178 * a call to the call gc_vm_initialized. If it is called after 179 * the call to gc_vm_initialized then the results are undefined. 180 * The GC places NULL in the vtable slot of the newly allocated 181 * object. 182 * 183 * The object allocated will be pinned, not finalizable and not an array. 184 * 185 * @param size - the size of the object to allocate. The high bit 186 * will never be set on this argument. 187 * @return The newly allocated object 188 * 189 * @note Will be renamed to gc_alloc_pinned_noclass() to comply with 190 * accepted naming conventions. 191 */ 192 GCExport Managed_Object_Handle gc_pinned_malloc_noclass(unsigned size); 193 194 195 /* 196 * ***** 197 * * 198 * * Routines to support write barriers. 199 * * 200 * ***** 201 */ 202 203 /** 204 * Returns TRUE if the GC requires write barriers before every store to 205 * a field of a reference tpe. 206 */ 207 GCExport Boolean gc_requires_barriers(); 208 209 210 211 /* 212 * ***** 213 * * 214 * * Routines to support threads. 215 * * 216 * ***** 217 */ 218 219 /** 220 * This routine is called during thread startup to set 221 * an initial nursery for the thread. 222 * 223 * @note gc_thread_init and gc_thread_kill assume that 224 * the current thread is the one we are interested in 225 * If we passed in the thread then these things could be 226 * cross inited and cross killed. 227 */ 228 GCExport void gc_thread_init(void *gc_information); 229 230 231 232 /** 233 * This is called just before the thread is reclaimed. 234 */ 235 GCExport void gc_thread_kill(void *gc_information); 236 237 /** 238 * Opaque handle for threads. 239 */ 240 typedef void* Thread_Handle; 241 242 243 /* 244 * ***** 245 * * 246 * * Routines to support the functionality required by the Java language specification. 247 * * 248 * ***** 249 */ 250 251 /** 252 * API for the VM to force a GC, typically in response to a call to 253 * java.lang.Runtime.gc 254 */ 255 GCExport void gc_force_gc(); 256 257 258 259 /** 260 * API for the VM to determine the total GC heap, typically in response to a 261 * call to java.lang.Runtime.totalMemory 262 */ 263 GCExport int64 gc_total_memory(); 264 265 266 267 /** 268 * API for the VM to get an approximate view of the free space, 269 * typically in response to a call to java.lang.Runtime.freeMemory 270 */ 271 GCExport int64 gc_free_memory(); 272 273 274 /** 275 * returns TRUE if the object is pinned. 276 * Routine to support the functionality required by JNI to see if an object is pinned. 277 */ 278 GCExport Boolean gc_is_object_pinned (Managed_Object_Handle obj); 279 280 281 /* 282 * ***** 283 * * 284 * * Routines to handle the GC area in the VTable. 285 * * 286 * ***** 287 */ 288 289 /** 290 * The VM calls this function after a new class has been prepared. 291 * The GC can use a call interface to gather relevant information about 292 * that class and store it in area of the VTable that is reserved for GC. 293 * The information cached in the VTable should be used by the GC in 294 * performance sensitive functions like object scanning. 295 */ 296 GCExport void gc_class_prepared(Class_Handle ch, VTable_Handle vth); 297 298 299 /** 300 * granularity of object alignment. 301 * 302 * Objects are aligned on 4 or 8 bytes. If they are aligned on 8 bytes then 303 * Arrays will be required to start on the indicated alignement. This means that 304 * for 8 byte alignment on the IA32 the header will look like this 305 * 306 * uint32 gc_header_lock_hash 307 * VTable *vt 308 * uint32 array_length 309 * uint32 padding 310 * the array elements. 311 */ 312 #ifdef POINTER64 313 #define GC_OBJECT_ALIGNMENT 8 314 #else 315 #define GC_OBJECT_ALIGNMENT 4 316 #endif 317 318 319 /* 320 * ***** 321 * * 322 * * Routines to support various write barriers. 323 * * 324 * ***** 325 */ 326 327 328 /** 329 * Returns TRUE if references within objects and vector elements are to be 330 * treated as offsets rather than raw pointers. 331 */ 332 GCExport Boolean gc_supports_compressed_references(); 333 334 /** 335 * These interfaces are marked for replacement for the IPF by the following 336 * gc_heap_write_mumble interface. 337 * 338 * @deprecated Will be removed soon. 339 */ 340 GCExport void gc_write_barrier(Managed_Object_Handle p_base_of_obj_with_slot); 341 342 /** 343 * There are two flavors for historical reasons. The compiler for IA32 will 344 * produce code for the version using an offset. 345 * 346 * @deprecated Will be removed soon. 347 */ 348 GCExport void gc_heap_wrote_object (Managed_Object_Handle p_base_of_object_just_written); 349 350 351 /** 352 * by calling this function VM notifies GC that a heap reference was written to 353 * global slot. 354 * 355 * There are some global slots that are shared by different threads. Sapphire 356 * needs to know about writes to these slots. One example of such slots is in 357 * the string pools used by the class loader. 358 */ 359 GCExport void gc_heap_write_global_slot(Managed_Object_Handle *p_slot, 360 Managed_Object_Handle value); 361 362 /** 363 * VM should call this function on heap reference writes to global slots. 364 * 365 * The "compressed" versions of the functions support updates to slots containing 366 * compressed references that are heap offsets; these functions handle details of 367 * converting raw reference pointers to compressed references before updating slots. 368 */ 369 GCExport void gc_heap_write_global_slot_compressed(uint32 *p_slot, 370 Managed_Object_Handle value); 371 372 /** 373 * VM should call this function on heap reference writes to heap objects. 374 */ 375 GCExport void gc_heap_write_ref (Managed_Object_Handle p_base_of_object_with_slot, 376 unsigned offset, 377 Managed_Object_Handle value); 378 /** 379 * @copydoc gc_heap_write_ref() 380 */ 381 GCExport void gc_heap_slot_write_ref (Managed_Object_Handle p_base_of_object_with_slot, 382 Managed_Object_Handle *p_slot, 383 Managed_Object_Handle value); 384 385 /** 386 * @copydoc gc_heap_write_ref() 387 */ 388 GCExport void gc_heap_slot_write_ref_compressed (Managed_Object_Handle p_base_of_object_with_slot, 389 uint32 *p_slot, 390 Managed_Object_Handle value); 391 392 393 394 /** 395 * Pin object. 396 */ 397 GCExport void gc_pin_object (Managed_Object_Handle* p_object); 398 399 /** 400 * Unpin object. 401 */ 402 GCExport void gc_unpin_object (Managed_Object_Handle* p_object); 403 404 405 406 /* 407 * ***** 408 * * 409 * * Routines to support soft, weak, and phantom reference objects. 410 * * 411 * ***** 412 */ 413 414 /** 415 * @return the base address of the heap. 416 * 417 * API for VM to determine the starting and ending adddresses of the heap 418 */ 419 GCExport void *gc_heap_base_address(); 420 421 /** 422 * @return the top address of the heap. 423 */ 424 GCExport void *gc_heap_ceiling_address(); 425 426 GCExport void gc_register_delinquent_regions(void **, int); 427 GCExport void *gc_get_latest_path_information(); 428 GCExport Boolean gc_is_heap_object(void *p_obj); 429 GCExport Boolean gc_is_object_long_lived(void *p_obj);.