/** * @file * GC interface exposed to VM. * * * In order to eliminate dependency on certain types such as (VTable *) we * have eliminated them from this interface and replace them with (void *). * While this might appear to be unfortunate it allows us to eliminate any * knowledge of the class and VTable structures that are not of interest * to the GC. */ /* * ***** * * * * Routines to support the initialization and termination of GC. * * * ***** */ /** * Is called by VM to start GC initialization sequence. * * This function is expected to initialize the GC internal data structures. * The VM should call this *before* any other calls to this interface * The GC assumes that the VM is ready to support a GC if it * calls this function. */ GCExport void gc_init(); /** * may be called at various points the VM decides are GC-safe. * The GC may ignore this, or it may force a root set enumeration, or it may * execute a full GC. * * @note Optional debug interface. */ GCExport void gc_test_safepoint(); /** * If the GC supports a "bump-the-pointer" style allocation, where the GC's * thread-local information contains a "current" pointer and a "limit" pointer, * then it should return TRUE, and it should set *offset_of_current to be the * offset into the GC thread block of the "current" pointer, and similar for * *offset_of_limit and the "limit" pointer. If not, then it should return * FALSE. */ GCExport Boolean gc_supports_frontier_allocation(unsigned *offset_of_current, unsigned *offset_of_limit); /** * This API is used by the VM to notify the GC that the * VM has completed bootstrapping and initialization, and * is henceforth ready to field requests for enumerating * live references. * * Prior to this function being called the GC might see some * strange sights such as NULL or incomplete vtables. The GC will * need to consider these as normal and work with the VM to ensure * that bootstrapping works. This means that the GC will make few * demands on the VM prior to this routine being called. * * However, once called the GC will feel free to do * stop-the-world collections and will assume that the entire * gc_import.h interface is available and fully functioning. * * If this routine is called twice the result is undefined. */ GCExport void gc_vm_initialized(); /** * This is called once the VM has no use for the heap or the * garbage collector data structures. The assumption is that the * VM is exiting but needs to give the GC time to run destructors * and free up memory it has gotten from the OS. * After this routine has been called the VM can not relie on any * data structures created by the GC. * * Errors: If gc_enumerate_finalizable_objects has been called and * gc_wrapup gc discovers an object that has not had it * finalizer run then it will attempt to report an error. */ GCExport void gc_wrapup(); /** * Is called by the VM to enumerate the root reference. */ GCExport void gc_add_root_set_entry(Managed_Object_Handle *ref, Boolean is_pinned); /** * Resembles gc_add_root_set_entry() but is passed the address of a slot * containing a compressed reference. */ GCExport void gc_add_compressed_root_set_entry(uint32 *ref, Boolean is_pinned); /** * Is called by the VM to enumerate weak root reference. * * @param slot An pointer to the slot, containing the weak root * @param is_pinned TRUE denotes that object pointed-to from this slot * should not be moved during garbage collection. * @param is_short_weak TRUE means that the weak root must be cleared * before object becomes eligible for finalization. */ GCExport void gc_add_weak_root_set_entry(Managed_Object_Handle *slot, Boolean is_pinned, Boolean is_short_weak); /* * ***** * * * * Routines to support the allocation and initialization of objects. * * * ***** */ /** * This routine is the primary routine used to allocate objects. * It assumes nothing about the state of the VM internal data * structures or the runtime stack. If gc_malloc_or_null is able * to allocate the object without invoking a GC or calling the VM * then it does so. It places p_vtable into the object, ensures * that the object is zeroed and then returns a ManagedObject * pointer to the object. If it is not able to allocate the object * without invoking a GC then it returns NULL. * * @param size - the size of the object to allocate. If the high bit * set then various constraints as described above are * placed on the allocation of this object. * @param type - a pointer to the vtable of the class being * allocated. This routine will place this value * in the appropriate slot of the new object. * @param thread_pointer - a pointer to the GC's thread-local space. * * This is like gc_malloc_or_null, except that it passes a pointer to * the thread's GC-specific space as a third argument. This prevents * the GC from having to immediately call vm_get_thread_curr_alloc_block() * as its first task. * * @note rename of gc_malloc_with_thread_pointer() */ GCExport Managed_Object_Handle gc_alloc_fast(unsigned size, Allocation_Handle type, void *thread_pointer); /** * This routine is used to allocate an object. See the above * discussion on the overloading of size. {link allocation} * * @param size - the size of the object to allocate. If the high bit * set then various constraints as described above are * placed on the allocation of this object. * @param type - a pointer to the vtable of the class being allocated. * This routine will place this value in the * appropriate slot of the new object. * @param thread_pointer - a pointer to the GC's thread-local space. * * @note rename of gc_malloc_or_null_with_thread_pointer() */ GCExport Managed_Object_Handle gc_alloc(unsigned size, Allocation_Handle type, void *thread_pointer); /** * For bootstrapping situations, when we still don't have * a class for the object. This routine is only available prior to * a call to the call gc_vm_initialized. If it is called after * the call to gc_vm_initialized then the results are undefined. * The GC places NULL in the vtable slot of the newly allocated * object. * * The object allocated will be pinned, not finalizable and not an array. * * @param size - the size of the object to allocate. The high bit * will never be set on this argument. * @return The newly allocated object * * @note Will be renamed to gc_alloc_pinned_noclass() to comply with * accepted naming conventions. */ GCExport Managed_Object_Handle gc_pinned_malloc_noclass(unsigned size); /* * ***** * * * * Routines to support write barriers. * * * ***** */ /** * Returns TRUE if the GC requires write barriers before every store to * a field of a reference tpe. */ GCExport Boolean gc_requires_barriers(); /* * ***** * * * * Routines to support threads. * * * ***** */ /** * This routine is called during thread startup to set * an initial nursery for the thread. * * @note gc_thread_init and gc_thread_kill assume that * the current thread is the one we are interested in * If we passed in the thread then these things could be * cross inited and cross killed. */ GCExport void gc_thread_init(void *gc_information); /** * This is called just before the thread is reclaimed. */ GCExport void gc_thread_kill(void *gc_information); /** * Opaque handle for threads. */ typedef void* Thread_Handle; /* * ***** * * * * Routines to support the functionality required by the Java language specification. * * * ***** */ /** * API for the VM to force a GC, typically in response to a call to * java.lang.Runtime.gc */ GCExport void gc_force_gc(); /** * API for the VM to determine the total GC heap, typically in response to a * call to java.lang.Runtime.totalMemory */ GCExport int64 gc_total_memory(); /** * API for the VM to get an approximate view of the free space, * typically in response to a call to java.lang.Runtime.freeMemory */ GCExport int64 gc_free_memory(); /** * returns TRUE if the object is pinned. * Routine to support the functionality required by JNI to see if an object is pinned. */ GCExport Boolean gc_is_object_pinned (Managed_Object_Handle obj); /* * ***** * * * * Routines to handle the GC area in the VTable. * * * ***** */ /** * The VM calls this function after a new class has been prepared. * The GC can use a call interface to gather relevant information about * that class and store it in area of the VTable that is reserved for GC. * The information cached in the VTable should be used by the GC in * performance sensitive functions like object scanning. */ GCExport void gc_class_prepared(Class_Handle ch, VTable_Handle vth); /** * granularity of object alignment. * * Objects are aligned on 4 or 8 bytes. If they are aligned on 8 bytes then * Arrays will be required to start on the indicated alignement. This means that * for 8 byte alignment on the IA32 the header will look like this * * uint32 gc_header_lock_hash * VTable *vt * uint32 array_length * uint32 padding * the array elements. */ #ifdef POINTER64 #define GC_OBJECT_ALIGNMENT 8 #else #define GC_OBJECT_ALIGNMENT 4 #endif /* * ***** * * * * Routines to support various write barriers. * * * ***** */ /** * Returns TRUE if references within objects and vector elements are to be * treated as offsets rather than raw pointers. */ GCExport Boolean gc_supports_compressed_references(); /** * These interfaces are marked for replacement for the IPF by the following * gc_heap_write_mumble interface. * * @deprecated Will be removed soon. */ GCExport void gc_write_barrier(Managed_Object_Handle p_base_of_obj_with_slot); /** * There are two flavors for historical reasons. The compiler for IA32 will * produce code for the version using an offset. * * @deprecated Will be removed soon. */ GCExport void gc_heap_wrote_object (Managed_Object_Handle p_base_of_object_just_written); /** * by calling this function VM notifies GC that a heap reference was written to * global slot. * * There are some global slots that are shared by different threads. Sapphire * needs to know about writes to these slots. One example of such slots is in * the string pools used by the class loader. */ GCExport void gc_heap_write_global_slot(Managed_Object_Handle *p_slot, Managed_Object_Handle value); /** * VM should call this function on heap reference writes to global slots. * * The "compressed" versions of the functions support updates to slots containing * compressed references that are heap offsets; these functions handle details of * converting raw reference pointers to compressed references before updating slots. */ GCExport void gc_heap_write_global_slot_compressed(uint32 *p_slot, Managed_Object_Handle value); /** * VM should call this function on heap reference writes to heap objects. */ GCExport void gc_heap_write_ref (Managed_Object_Handle p_base_of_object_with_slot, unsigned offset, Managed_Object_Handle value); /** * @copydoc gc_heap_write_ref() */ GCExport void gc_heap_slot_write_ref (Managed_Object_Handle p_base_of_object_with_slot, Managed_Object_Handle *p_slot, Managed_Object_Handle value); /** * @copydoc gc_heap_write_ref() */ GCExport void gc_heap_slot_write_ref_compressed (Managed_Object_Handle p_base_of_object_with_slot, uint32 *p_slot, Managed_Object_Handle value); /** * Pin object. */ GCExport void gc_pin_object (Managed_Object_Handle* p_object); /** * Unpin object. */ GCExport void gc_unpin_object (Managed_Object_Handle* p_object); /* * ***** * * * * Routines to support soft, weak, and phantom reference objects. * * * ***** */ /** * @return the base address of the heap. * * API for VM to determine the starting and ending adddresses of the heap */ GCExport void *gc_heap_base_address(); /** * @return the top address of the heap. */ GCExport void *gc_heap_ceiling_address(); GCExport void gc_register_delinquent_regions(void **, int); GCExport void *gc_get_latest_path_information(); GCExport Boolean gc_is_heap_object(void *p_obj); GCExport Boolean gc_is_object_long_lived(void *p_obj);