/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef _OPEN_VM_GC_H #define _OPEN_VM_GC_H /** * @file * These are the functions that a GC built as a DLL may call. */ #include #include "open/types.h" #ifdef __cplusplus extern "C" { #endif /** * @return The number of bytes allocated by VM in VTable * for use by GC. */ VMEXPORT size_t vm_number_of_gc_bytes_in_vtable(); /** * @return The number of bytes allocated by VM in thread-local * storage for use by GC. */ VMEXPORT size_t vm_number_of_gc_bytes_in_thread_local(); /** * @return The pointer to thread-local area of current thread. */ VMEXPORT void *vm_get_gc_thread_local(); /** * Initializes the lock that guards all GC-related operations in the VM. */ VMEXPORT void vm_gc_lock_init(); /** * Acquire the lock that guards all GC-related operations in the VM. * If the lock can't be acquired the thread waits until the lock is available. * This operation marks the current thread as being safe for root set * enumeration. */ VMEXPORT void vm_gc_lock_enum(); /** * Release the system-wide lock acquired by vm_gc_lock_enum(). * The thread is marked as unsafe for root set enumeration. */ VMEXPORT void vm_gc_unlock_enum(); /** * GC calls this function to command VM to start root set enumeration. * * Root set enumeration for all managed threads. */ VMEXPORT void vm_enumerate_root_set_all_threads(); /** * GC calls this function to restart managed threads after root set * enumeration is complete. * * This function resumes all threads suspended by * vm_enumerate_root_set_all_threads() */ VMEXPORT void vm_resume_threads_after(); /** * GC calls this function in stop the world state when all live objects * are marked. This is the callback to classloader allowing it to * gather needed statics for class unloading. * * @sa gc interface functions: gc_get_next_live_object(void *iterator) */ VMEXPORT void vm_classloader_iterate_objects(void *iterator); /** * GC calls this function during heap iteration to iterate * one object. The GC aborts heap iteration if this function * returns false. * * @return TRUE to continue heap iteration, FALSE to abort * * @sa gc.h#gc_iterate_heap() */ VMEXPORT bool vm_iterate_object(Managed_Object_Handle object); /** * GC calls this function to hint VM that finalizers may need to be run * and references enqueued. This method is guaranteed not to hold global * GC lock. * * @note The function introduced as a workaround for running finalizers * until a complete solution with finalizer thread is implemented. */ VMEXPORT void vm_hint_finalize(); VMEXPORT bool is_it_finalize_thread(); /** * thread state as concerns root set enumeration. */ enum safepoint_state { nill = 0, /** * Thread is stopped for root set enumeration, * as is the whole world (all managed threads). */ enumerate_the_universe, /** * Thread is stopped for root set enumeration */ java_suspend_one_thread, /** * Thread is stopped by java debugger. */ java_debugger }; /** * @return TRUE if no apparent trash was found in the object. * * Used for debugging. */ VMEXPORT Boolean verify_object_header(void *ptr); /** * Routines to support lifecycle management of resources associated * with a java object */ VMEXPORT void vm_notify_obj_alive(void *); VMEXPORT void vm_reclaim_native_objs(); /* * ***** * * * * Routines to support finalization of objects. * * * ***** */ //@{ /** * GC should call this function when an object becomes * "f-reachable, finalizable" * The VM later finalizes those objects in a way that * is not part of this interface. * * VM must not call finalizer immediately to prevent * deadlocks in user code, because this functions * may be called during the stop-the-world phase. */ VMEXPORT void vm_finalize_object(Managed_Object_Handle p_obj); VMEXPORT void set_native_finalizer_thread_flag(Boolean flag); VMEXPORT void vm_heavy_finalizer_block_mutator(void); //@} /** * GC should call this function when an phantom reference object * is to be enqueued, i.e. when the reference is not reachable anymore. */ VMEXPORT void vm_enqueue_reference(Managed_Object_Handle p_obj); VMEXPORT void set_native_ref_enqueue_thread_flag(Boolean flag); /* * Returns handle of a class for a specified vtable * * @param vh - handle of vtable to retrieve class for * * @return class handle for a specified vtable */ VMEXPORT Class_Handle vtable_get_class(VTable_Handle vh); /** * GC calls this function for each live object it finds in heap. * This is used for finding unreferenced class loaders for class * unloading. * Notifies VM that live object of this class was found in the heap * * @param clss - class of live object in Java heap */ VMEXPORT void vm_notify_live_object_class(Class_Handle clss); #define CL_PROP_ALIGNMENT_MASK 0x00FFF ///< @sa class_properties #define CL_PROP_NON_REF_ARRAY_MASK 0x01000 ///< @sa class_properties #define CL_PROP_ARRAY_MASK 0x02000 ///< @sa class_properties #define CL_PROP_PINNED_MASK 0x04000 ///< @sa class_properties #define CL_PROP_FINALIZABLE_MASK 0x08000 ///< @sa class_properties /** * @section class_properties Class properties flags * 3322|2222|2222|1111|1111|1100|0000|0000 * 1098|7654|3210|9876|5432|1098|7654|3210 * ^^^^^^^^^^^^^^------ CL_PROP_ALIGNMENT_MASK * ^--------------------- CL_PROP_NON_REF_ARRAY_MASK * ^---------------------- CL_PROP_ARRAY_MASK * ^----------------------- CL_PROP_PINNED_MASK * ^------------------------ CL_PROP_FINALIZABLE_MASK */ /** * extract the recursion counter from object lockword. */ #define P_RECURSION_BYTE(x) ( (U_8 *)(((x)->get_obj_info_addr())) + 1 ) #ifdef GC_PUBLIC_PRIVATE /** * mask of recursion counter */ #define RECURSION_MASK 0x7f /** * mask of recursion counter shifted to its position in lockword. */ #define RECURSION_MASK_SHIFTED 0x7f00 #define PUBLIC_PRIVATE_MASK 0x80 #endif /* #ifdef GC_PUBLIC_PRIVATE */ #ifdef __cplusplus } #endif /** * \page vm_finalization_and_weak_refs Design of finalization and weak references in VM. * * @author Salikh Zakirov * @version written on 2005-05-31 * * \section vm_finalization_interactions Object Finalization * * As described elsewhere, VM calls function gc_class_prepared() * as a mandatory step of class preparation process, in order that GC * have a chance to create its own class-specific structure (known as GCVT). * During this call, GC can call class_is_finalizable() to find out * whether the instances of this class require finalizers to be run. * The result is stored in GCVT for later use. * * At a later stage, when VM requests an object to be allocated by calling * gc_alloc(), or gc_alloc_fast(), GC consults its GCVT to find out whether * this class of objects needs to be finalized, and if so, adds the object * reference in the finalizable queue, maintained by the GC. Allocation * of finalizable objects is guarded from being handled by the inlined * fast path by object size overloading hack (see \ref allocation). * This is needed due to the optimized nature of allocation fast path: * fast path assumes that objects don't need any special handling, * and we must ensure fast path fails for all object that do require * special handling such as finalization. * * Later, when the garbage is being collected, GC walks over the finalizable * object list and checks if the objects became eligible for finalization (i.e. * not reachable otherwise). The GC side of the story is described in more detail * in \ref gc_finalization_and_weak_refs Object chosen for finalization are then "revived" * and reported to the VM using vm_finalize_object(). Reviving is performed by * marking the object in order to prevent it from being collected before the * finalizer has been run. VM places all reported objects to its internal * finalization queue and runs the finalizers in a separate thread at a later * (unspecified) time. Note, that while running finalization in a dedicated * thread is not directly required by the java specification, it is highly * desirable in order to improve overall VM robustness, because finalizers may * contain user code of arbitrary complexity, including synchronization with * other user threads. Thus, running finalizers as a step of garbage collection * process while other user threads are suspended will introduce a risk of * deadlock and thus must be avoided. * * As finalization queue stores direct references to java heap, it is * must be handled properly during heap compaction, by adding the locations * of the pointers to the list of the slots updated during compaction. * * \section vm_finalization_requirements Finalization requirements * * The process described above places following requirements * \li Finalizable objects must be allocated by calling into GC, that is * not by the inlined fast path. * \li vm_finalize_object() must defer running of finalizers to a later * stage after the user java threads are resumed. * * * \section vm_weak_refs Weak references * * See the description of how weak references work in GC: * \ref gc_finalization_and_weak_refs * */ #endif // _OPEN_VM_GC_H