You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@harmony.apache.org by Salikh Zakirov <Sa...@Intel.com> on 2006/07/11 19:19:17 UTC
Re: [DRLVM] GC/VM interface discussion - [PATCH] cleanup in progress
Weldon Washburn wrote:
> As a first step to improving DRLVM's GC/VM interface, it would be
> great to cleanup drlvm/trunk/vm/include/open/vm_gc.h and gc.h.
> Basically the concept is to start by removing unused APIs and fixing
> the comments.
A heads up for people going to pursue this task to prevent potential
change conflicts.
I have been working on cleaning up the comments in gc.h and gc_vm.h.
The result is not finalized yet, as I need to address several issues
in the grouping and formatting doxygen-generated documentation.
Generally, I am trying to make the doxygen-generated documentation
more readable and better structured.
I've put the preliminary diff at the end of the message.
Please let me if you have any comments or objections.
> A second step would be to modify these files to accommodate different
> GCs such as MMTk.
I would rather suggest that experience of porting MMTk to DRLVM
used as input for furhter GC interface refactoring
> GCExport void gc_test_safepoint();
+1 to remove.
As far as I am aware, this API wasn't actually used for the last 1.5 years
of DRLVM development. The techniques of running some verification pass
each safepoint may be efficient in finding enumeration bugs, but it requires
very specific provisions, and can perfectly be implemented in VM directly,
without this interface. And this function is completely useless for a production
(non-debug) GC implementations.
> GCExport void gc_add_root_set_entry_managed_pointer();
+1 to remove.
> GCExport Managed_Object_Handle gc_alloc_pinned();
This function implements the concept of "fixed" space:
the objects are never moved, but collected.
As far as I know, this API is not used now, but there exist some ideas,
which may require this kind of API: e.g. storing VTables and Class structures
in java heap to facilitate their reclamation on class unloading.
-----------------------------------------------------------
Below is my work-in-progress on cleaning up documentation comments
in gc.h and vm_gc.h. Apply to Harmony drlvm trunk with 'patch -p1'
-----------------------------------------------------------
--- a/vm/include/open/gc.h
+++ b/vm/include/open/gc.h
@@ -13,32 +13,30 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
- * @author Intel, Salikh Zakirov
- * @version $Revision: 1.1.2.1.4.3 $
- */
#ifndef _OPEN_GC_H
#define _OPEN_GC_H
/**
* @file
- * GC interface exposed to VM.
+ * GC interface exposed to VM
*
- * These are the functions that a GC built as a DLL must export.
- * Some functions may be optional and are marked as such.
+ * Any garbage collector built as a DLL must export functions of this
+ * interface to be able to work in DRLVM.
+ * Some of the functions are optional and are marked as part of the #Extended interface.
*
- * This is a global include file which provides to the VM an interface to the
- * GC. This interface is the only supported interface that the VM should call
- * to talk to the GC. All routines in this C interface will begin with "gc_"
+ * This is a global include file, which provides an interface to GC for VM.
+ * This interface is the only supported interface that VM must call
+ * to interact with GC. All routines in this C interface begin with the prefix "gc_".
*
- * The GC expects that there is a vm_gc.h file holding the only
- * interface that the GC will use to talk to the VM.
+ * The garbage collector expects that VM has a vm_gc.h file representing the interface
+ * that GC can use to interact with VM. GC also uses other functions exported
+ * by VM in the <code>VM Generic</code> interface.
*
- * In order to eliminate dependency on certain types such as (VTable *) we
- * have eliminated them from this interface and replace them with (void *).
+ * To eliminate the dependency on certain types, such as <code>(VTable *)</code>,
+ * these have been replaced with <code>(void *)</code>.
* 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
+ * knowledge of the Class and VTable structures that are not of interest
* to the GC.
*/
@@ -50,9 +48,12 @@ extern "C" {
#endif
+/** @defgroup gc_public GC public interface functions
+ * This module includes groups of functions making up the exported interface
+ * of the garbage collector. */
/**
- * GCExport is used to declare functions exported by GC.
+ * Used to declare functions exported by the garbage collector.
*/
#ifndef PLATFORM_POSIX
#ifdef BUILDING_VM
@@ -65,52 +66,69 @@ #define GCExport
#endif /* #ifndef PLATFORM_POSIX */
+/** @defgroup gc_init Routines to support the initialization and termination of GC
+ * @ingroup gc_public */
+/**
+ * @ingroup gc_init
+ * Granularity of object alignment
+ *
+ * Objects are aligned on 4 or 8 bytes. If they are aligned on 8 bytes, then
+ * arrays are required to start on the indicated alignement. This means that
+ * for 8-byte alignment on the IA-32 architecture, the header has the following
+ * format:
+ * <pre>
+ * uint32 gc_header_lock_hash
+ * VTable *vt
+ * uint32 array_length
+ * uint32 padding
+ * the array elements
+ * </pre>
+ */
+#ifdef POINTER64
+#define GC_OBJECT_ALIGNMENT 8
+#else
+#define GC_OBJECT_ALIGNMENT 4
+#endif
-#if defined(USE_GC_STATIC) || defined(BUILDING_GC)
+#if defined(USE_GC_STATIC) || defined(BUILDING_GC)
-/*
- * *****
- * *
- * * Routines to support the initialization and termination of GC.
- * *
- * *****
- */
-/**
- * Is called by VM to start GC initialization sequence.
+/**
+ * @ingroup gc_init
+ * Starts the 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
+ * VM must call this function *before* any other calls to this interface
+ * except gc_get_property().
+ * The garbage collector assumes that VM is ready to support a collection 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.
+ * @ingroup gc_alloc
+ * Checks whether GC supports the <i>bump-the-pointer</i> style
+ * allocation.
+ *
+ * With this allocation, the GC thread-local information contains a
+ * <i>current</i> pointer and a <i>limit</i> pointer.
+ *
+ * @param[out] offset_of_current - the offset of the <code>current</code> pointer in the GC
+ * thread-local data
+ * @param[out] offset_of_limit - the offset of the <code>limit</code> pointer in the GC
+ * thread-local data
+ * @return <code>TRUE</code> if GC supports the bump-the-pointer style allocation
+ * and sets <i>*offset_of_current<i> as the offset into the GC thread block
+ * of the <i>current</i> pointer and <code>*offset_of_limit</code> as the offset
+ * into the GC thread block of the <i>limit</i> pointer.
+ * Otherwise, returns <code>FALSE</code>.
*
- * @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);
@@ -118,183 +136,165 @@ GCExport Boolean gc_supports_frontier_al
/**
- * 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.
+ * @ingroup gc_init
+ * Notifies GC that VM has completed bootstrapping and initialization
+ * and is 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.
+ * Before calls to this function, the garbage collector might receive
+ * unexpected data, such as <code>NULL</code> values or incomplete
+ * VTable structures. GC needs to consider these normal and work
+ * with VM to ensure that bootstrapping works. This means that GC
+ * will make few requests to VM before this function is 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.
+ * Once the function is called, GC do stop-the-world collections
+ * and assume that the entire vm_gc.h interface is available
+ * and fully functional.
*
- * If this routine is called twice the result is undefined.
+ * If the function 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.
+ * @ingroup gc_init
+ * Requests GC shutdown when VM has no use for the heap or the garbage collector
+ * data structures.
+ *
+ * It is assumed that VM is exiting but needs to give GC time to run
+ * destructors and to free memory that it has gotten from the operating system.
+ * After this function has been called, VM cannot rely on any data structures
+ * created by GC.
+ *
+ * @warning 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.
*
- * 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();
+/** @defgroup gc_rse Root set enumeration functions
+ * @ingroup gc_public */
/**
- * Is called by the VM to enumerate the root reference.
+ * @ingroup gc_rse
+ * Requests GC to enumerate root reference.
+ *
+ * @param[in] root - the pointer to the location of the root reference
+ * @param[in] is_pinned - the parameter indicating whether the reference can or cannot
+ * be moved in the next garbage collection
*/
-GCExport void gc_add_root_set_entry(Managed_Object_Handle *ref, Boolean is_pinned);
+GCExport void gc_add_root_set_entry(Managed_Object_Handle *root, Boolean is_pinned);
/**
- * Resembles gc_add_root_set_entry() but is passed the address of a slot
- * containing a compressed reference.
+ * @ingroup gc_rse
+ * Resembles gc_add_root_set_entry() but gets the address of the slot
+ * containing the compressed reference.
+ *
+ * @param[in] root - the pointer to the location of the root reference
+ * @param[in] is_pinned - the parameter indicating whether the reference can or cannot
+ * be moved in the next garbage collection
*/
-GCExport void gc_add_compressed_root_set_entry(uint32 *ref, Boolean is_pinned);
+GCExport void gc_add_compressed_root_set_entry(uint32 *root, Boolean is_pinned);
/**
- * Is called by the VM to enumerate weak root reference.
+ * @ingroup gc_rse
+ * Requests enumeration of the 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);
-
-/*
- * Enumerate a managed pointer.
- * The pointer can be declared as pinned. The pointer can
- * point to the managed heap or any other area where data can be stored: stack
- * or static fields. It is the responsibility of the GC to ignore pointers
- * that are not in the managed heap.
+ * @param[in] root - the pointer to the slot containing the weak root reference
+ * @param[in] is_pinned - the parameter indicating whether the reference can or cannot
+ * be moved in the next garbage collection
+ * @param[in] is_short_weak - the parameter indicating whether the weak reference
+ * must be cleared before the object becomes eligible for finalization.
*
- * @note Is this function needed for Java? -salikh
*/
-GCExport void gc_add_root_set_entry_managed_pointer(void **slot,
- Boolean is_pinned);
-
+GCExport void gc_add_weak_root_set_entry(Managed_Object_Handle *root,
+ Boolean is_pinned, Boolean is_short_weak);
/**
- * Call from the VM to the gc to enumerate an interior pointer. **ref is a
- * slot holding a pointer into the interior of an object. The base of the
- * object is located at *ref - offset. The strategy employed is to place the
- * slot, the object base and the offset into a slot_base_offset table. We then
- * call gc_add_root_set_entry with the slot in the table holding the base of
- * the object. Upon completion of the garbage collection the routine
- * fixup_interior_pointers is called and the slot_base_offset table is
- * traversed and the new interior pointer is calculated by adding the base of
- * the object and the offset. This new interior pointer value is then placed
- * into the slot.
+ * @ingroup gc_rse
+ * Requests enumeration of the interior pointer.
*
- * This routine can be called multiple times with the same interiour pointer
- * without any problems. The offset is checked to make sure it is positive but
+ * Interior roots may be used by advanced just-in-time compilers
+ * for compiling array handling loops.
+ *
+ * In this algorithm, <code>*root</code> is a slot holding a pointer
+ * into the interior of an object. The base of the object is located at
+ * <code>(*root - offset)</code>. The strategy employed is to place the slot,
+ * the object base, and the offset into a <code>slot_base_offset</code> table.
+ * The function gc_add_root_set_entry() is then with the slot in the table
+ * holding the base of the object.
+ *
+ * When a garbage collection completes, the function fixup_interior_pointers() is called
+ * and the <code>slot_base_offset</code> table is traversed. At this step, the new interior
+ * pointer is calculated by adding the base of the object and the offset, and
+ * placed into the slot.
+ *
+ * The offset is checked to make sure it is positive but
* the logic is not dependent on this fact.
*
- * @note Optional function, never called by Java virtual machine.
+ *
+ * @param[in] root - the pointer to the location of interior object pointer
+ * @param[in] offset - the offset of the interior pointer, so the actual
+ * root reference is <code>*root - offset</code>
+ * @param[in] is_pinned - the parameter indicating whether the object corresponding to
+ * this root reference can or cannot be moved during next garbage collection
+ *
*/
-GCExport void gc_add_root_set_entry_interior_pointer (void **slot, int offset, Boolean is_pinned);
+GCExport void gc_add_root_set_entry_interior_pointer (void **root, int offset, Boolean is_pinned);
-/*
- * *****
- * *
- * * Routines to support the allocation and initialization of objects.
- * *
- * *****
- */
+/** @defgroup gc_alloc Routines to support the allocation and initialization of objects
+ * @ingroup gc_public */
-/**
- * @page allocation Allocation of objects.
- *
- * There is a tension between fast allocation of objects and
- * honoring various constraints the VM might place on the object.
- * These constraints include registering the objects for
- * finalization, aligning the objects on multiple word boundaries,
- * pinning objects for performance reasons, registering objects
- * related to weak pointers and so forth.
- *
- * We have tried to resolve this tension by overloading the
- * size argument that is passed to the allocation routine. If
- * the size of the argument has a high bit of 0, then the
- * allocation routine will assume that no constraints exist
- * on the allocation of this object and allocation can potentially
- * be made very fast. If on the other hand the size is large then
- * the routine will query the class data structure to determine
- * what constraints are being made on the allocation of this object.
- *
- * The gc_import.h interface will provide the following masks
- * to allow the gc to quickly determine the constraints.
- * <PRE>
- * CL_PROP_NON_REF_ARRAY_MASK 0x1000
- * CL_PROP_ARRAY_MASK 0x2000
- * CL_PROP_PINNED_MASK 0x4000
- * CL_PROP_FINALIZABLE_MASK 0x8000
- * CL_PROP_ALIGNMENT_MASK 0x0FFF
- * </PRE>
- */
/**
- * 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.
+ * @ingroup gc_alloc
+ * Allocates an object of the specified size or returns <code>NULL</code>; never
+ * triggers a garbage collection.
+ *
+ * This routine is primary for object allocation. The function
+ * uses no assumptions on the state of the VM internal data structures or
+ * the run-time stack.
+ * This function tries allocating the given object without invoking GC or
+ * calling the VM. The function places <i>type</i> into
+ * the appropriate slot in the new object, ensures that the object is zeroed
+ * and returns a pointer to the object.
+ *
+ * @param[in] size - the size of the object to allocate
+ * @param[in] type - the pointer to the VTable structure of the allocated class
+ * @param[in] thread_pointer - the pointer to the GC thread-local storage
*
- * 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.
+ * @return The pointer to the allocated object or <code>NULL</code> if allocation fails.
*
- * @note rename of gc_malloc_with_thread_pointer()
+ * @note If the high bit set, various constraints are placed
+ * on the allocation of this object, as described above.
*/
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}
+ * @ingroup gc_alloc
+ * Allocates an object of the specified size, triggers garbage collection
+ * if needed.
+ * The function places <i>type</i> into the appropriate slot in the new object.
*
- * @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.
+ * @param size - the size of the object to allocate
+ * @param type - the pointer to the vtable of the class being allocated
+ * @param thread_pointer - the pointer to the GC thread-local storage
+ *
+ * @return The pointer to the allocated object or <code>NULL</code> in case
+ * of an out-of-memory condition, that is, when allocation failed
+ * after the garbage collection.
+ *
+ * @note If the high bit set, various constraints are placed
+ * on the allocation of this object, as described above.
*
- * @note rename of gc_malloc_or_null_with_thread_pointer()
*/
GCExport Managed_Object_Handle gc_alloc(unsigned size,
Allocation_Handle type,
@@ -302,105 +302,130 @@ GCExport Managed_Object_Handle gc_alloc(
/**
- * 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.
+ * @ingroup gc_alloc
+ * Allocates an object without installing the VTable pointer.
+ *
+ * This function can be used during bootstrapping with no class for the object.
+ * This routine is only available prior to a call to gc_vm_initialized().
+ * If the function is called after the call to gc_vm_initialized(),
+ * the results are undefined.
*
- * The object allocated will be pinned, not finalizable and not an array.
+ * The allocated object is pinned, not finalizable and not an array.
+ *
+ * @param size - the size of the object to allocate
*
- * @param size - the size of the object to allocate. The high bit
- * will never be set on this argument.
- * @return The newly allocated object
+ * @return The pointer to the newly allocated object with <code>NULL</code>
+ * in the VTable slot of the newly allocated object.
+ *
+ * @note The high bit is never set on the <i>size</i> argument.
*
- * @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);
+GCExport Managed_Object_Handle gc_alloc_pinned_noclass(unsigned size);
/**
- * Allocate pinned forever object
+ * @ingroup gc_alloc
+ * Allocates a permanently pinned object.
+ *
+ * This routine place the <i>type</i> value in the appropriate slot of the new object.
+ *
+ * @param size - the size of the object to allocate
+ * @param type - the pointer to the VTable structure of the class being allocated
+ * @param thread_pointer - the pointer to the GC thread-local storage
+ *
+ * @return The pointer to the newly allocated object.
*
- * @note Not implemented.
*/
GCExport Managed_Object_Handle gc_alloc_pinned(unsigned size, Allocation_Handle type, void *thread_pointer);
-
-
-/*
- * *****
- * *
- * * Routines to support write barriers.
- * *
- * *****
- */
-
/**
- * Returns TRUE if the GC requires write barriers before every store to
- * a field of a reference tpe.
+ * @ingroup gc_init
+ * Checks whethter write barriers are required before every store operation
+ * to a field of a reference type.
+ *
+ * @return <code>TRUE</code> if the GC requires write barriers for these operations;
+ * otherwise, <code>FALSE</code>.
+ *
*/
GCExport Boolean gc_requires_barriers();
+/** @defgroup gc_event Event callback functions
+ * @ingroup gc_public
+ * This group of functions is responsible for TBD */
-/*
- * *****
- * *
- * * Routines to support threads.
- * *
- * *****
- */
/**
- * This routine is called during thread startup to set
- * an initial nursery for the thread.
+ * @ingroup gc_event
+ * Notifies GC that a new Java thread has been started.
+ *
+ * This function is called from the context of the new thread
+ * and can be used to set up an initial nursery for the thread.
+ *
+ * @param gc_information - the pointer to the GC-specific thread local
+ * data structure
*
- * @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.
+ * @ingroup gc_event
+ * Notifies GC that a Java thread terminates.
+ *
+ * This function is called from the context of the new thread
+ * and can be used to set up an initial nursery for the thread.
+ *
+ * @param gc_information - the pointer to the GC-specific thread local
+ * data structure
+ *
*/
GCExport void gc_thread_kill(void *gc_information);
+/** @defgroup gc_thread Functions providing individual thread control
+ * @ingroup gc_public */
+
/**
* Opaque handle for threads.
+ *
+ * @ingroup gc_thread
*/
typedef void* Thread_Handle;
/**
- * GC may call this function asynchronously any time it wants to get thread list.
- * This function signals VM to obtain thread lock and start thread iteration.
+ * @ingroup gc_thread
+ * Requests VM to iterate over Java threads
+ * by calling gc_iterate_thread() repeatedly.
+ *
+ * GC can call this function asynchronously any time it needs to get thread list.
+ * This function signals VM to obtain the thread lock and to start thread iteration.
+ * The procedure goes in the following order:
*
- * \li vm obtains thread lock
- * \li vm repeatedly calls gc_iterate_thread(thread)
- * \li vm releases thread lock
+ * \li VM obtains the thread lock.
+ * \li VM repeatedly calls gc_iterate_thread().
+ * \li VM releases the thread lock.
*
* @note Not implemented.
*/
VMEXPORT void vm_iterate_threads();
/**
- * VM calls this method repeatedly to iterate over the list of java threads,
- * initiated earlier by calling vm_iterate_threads()
+ * @ingroup gc_thread
+ * Passes a thread handle to GC during iteration
+ * over Java threads initiated earlier with vm_iterate_threads().
*
* Thread creation and termination is locked during this iteration.
*
- * gc may do one of the following:
- * 1. store thread handle for later use
- * 2. enumerate thread right now, while
- * holding thread lock (using vm_suspend_thread(thread) and
- * vm_enumerate_thread_root_set(thread)).
+ * The GC may do one of the following:
+ *
+ * \li Store the thread handle for later use
+ * \li Enumerate the thread at the stop while
+ * holding thread lock using vm_suspend_thread() and
+ * vm_enumerate_thread_root_set()
+ *
+ * @param thread - the handle of the thread being iterated
*
* @note Not implemented.
*/
@@ -408,77 +433,87 @@ GCExport void gc_iterate_thread(Thread_H
/**
- * GC calls this method to request VM to
- * suspend an individual thread.
- * After the thread is suspended,
- * 0 is returned on success
+ * @ingroup gc_thread
+ * Requests VM to suspend the specified thread.
*
- * Thread may have been terminated already,
- * in this case non-zero value is returned,
- * and no additional actions are taken.
+ * GC calls this function when it needs to suspend a thread
+ * for stack enumeration or a read- / write- barrier change.
*
- * GC calls this VM function when it wants a thread
- * to be suspended for stack enumeration or
- * read/write barrier change
*
- * blocks until synchronously call gc_thread_suspended(thread)
+ * The function may block synchronously until VM
+ * calls gc_thread_suspended() in the same thread
* or asynchronously delegate enumeration to thread
- * (self-enumeration)
+ * (self-enumeration).
*
- * @note we need a way to signal that process of thread suspension
- * is complete.
+ * @param thread - a handle of the thread to suspend
+ * @return 0 is returned on success, a non-zero value otherwise.
*
* @note Not implemented.
+ *
+ * @note If the thread has been terminated already,
+ * a non-zero value is returned and no action taken.
+ *
*/
-VMEXPORT void vm_suspend_thread(Thread_Handle thread);
+VMEXPORT int vm_suspend_thread(Thread_Handle thread);
/**
- * VM calls this GC callback when it's accomplished the requested
+ * @ingroup gc_thread
+ * Notifies GC that a single thread has been suspended.
+ *
+ * VM calls this callback when it has accomplished the
* operation of suspending a thread in gc-safe point
+ * requested by vm_suspend_thread().
*
- * may be called synchronously from the same context
- * as vm_suspend_thread() in case of cross-enumeration, or
- * may be called asynchronously from the specified
- * thread context in case of self-enumeration
+ * This function can be called synchronously from the same context as
+ * vm_suspend_thread() in case of cross-enumeration, or in the suspended
+ * thread context in case of self-enumeration.
*
- * after this function completes,
- * the thread is resumed automatically
+ * After this function returns, the thread is resumed automatically.
*
* GC is expected to call a limited subset
* of GC-VM interface functions from this callback:
- * \li vm_enumerate_thread_root_set(thread)
- * \li vm_install_write_barrier(...)
+ * \li vm_enumerate_thread_root_set()
+ * \li vm_install_write_barrier()
* (hypothetical, not designed yet)
* \li make a thread stack snapshot for later analysis
*
+ * @param thread - a handle of the suspened thread
* @note Not implemented.
*/
GCExport void gc_thread_suspended (Thread_Handle thread);
/**
+ * @ingroup gc_thread
+ *
+ * Requests VM to enumerate the root set of the specified
+ * thread.
+ *
* GC calls this function to command VM to enumerate a thread,
- * which was earlier suspenden using vm_suspend_thread().
+ * which was earlier suspended with vm_suspend_thread().
*
- * In response to this call, VM repeatedly calls gc_add_root_set_entry() to
- * enumerate thread stacks and local handles
+ * In response to this call, VM repeatedly calls gc_add_root_set_entry()
+ * and other enumeration functions to enumerate thread stacks and local
+ * handles.
*
+ * @param thread - a handle of the thread to be enumerated
* @note Not implemented.
*/
VMEXPORT void vm_enumerate_thread_root_set(Thread_Handle thread);
/**
- * GC calls this function to command VM to enumerate global slots.
+ * @ingroup gc_thread
+ * Requests VM to enumerate the global root set.
*
- * during enumeration of global root set, either all threads need
- * to be suspended, or write barrier installed.
+ * During enumeration of the global root set, all threads need
+ * to be suspended or write barrier need to be installed.
*
- * Apparently some operations should be blocked in VM, like class loading,
+ * Apparently, some operations must be blocked in VM, such as class loading,
* which itself creates new global reference slots.
* It is not clear to me if we should require stopping the world to use
* this function or introduce new system-wide lock on operations that
* change the number of global reference slots.
*
- * this function calls gc_add_root_set_entry() for all global reference
+ * This function calls gc_add_root_set_entry() for all global reference
* slots.
*
* @note Not implemented.
@@ -486,63 +521,71 @@ VMEXPORT void vm_enumerate_thread_root_s
VMEXPORT void vm_enumerate_global_root_set();
-/*
- * *****
- * *
- * * Routines to support the functionality required by the Java language specification.
- * *
- * *****
- */
+/** @defgroup gc_misc Routines to support the functionality required by the Java language specification
+ * @ingroup gc_public */
/**
- * API for the VM to force a GC, typically in response to a call to
- * java.lang.Runtime.gc
+ * Forces garbage collection.
+ * Used to implement Runtime.gc()
+ *
+ * @ingroup gc_misc
*/
GCExport void gc_force_gc();
/**
- * API for the VM to determine the current GC heap size, typically in response to a
- * call to java.lang.Runtime.totalMemory
+ * Returns the current GC heap size,
+ * used to implement Runtime.totalMemory().
+ *
+ * @ingroup gc_misc
*/
GCExport int64 gc_total_memory();
/**
- * API for the VM to determine the maximum GC heap size, typically in response to a
- * call to java.lang.Runtime.maxMemory
+ * Returns the maximum GC heap size,
+ * used to implement Runtime.maxMemory().
+ *
+ * @ingroup gc_misc
*/
GCExport int64 gc_max_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
+ * Returns an approximation of the amount of free space in bytes,
+ * used to implement Runtime.freeMemory().
+ *
+ * @ingroup gc_misc
*/
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.
+ * Checks whether the object is pinned.
+ *
+ * This function supports the functionality required by JNI to verify
+ * if an object is pinned.
+ *
+ * @param object - an object pointer
+ *
+ * @return <code>TRUE</code> if the object is pinned.
+ *
+ * @ingroup gc_pinning
*/
-GCExport Boolean gc_is_object_pinned (Managed_Object_Handle obj);
+GCExport Boolean gc_is_object_pinned(Managed_Object_Handle object);
-/*
- * *****
- * *
- * * Routines to handle the GC area in the VTable.
- * *
- * *****
- */
-
/**
- * The VM calls this function after a new class has been prepared.
+ * @ingroup gc_event
+ *
+ * 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
+ * that class and store it in the VTable area reserved for GC.
+ * The information cached in the VTable must be used by the GC in
* performance sensitive functions like object scanning.
+ *
+ * @param ch - the class handle of the prepared class
+ * @param vth - the VTable handle of the prepared class
*/
GCExport void gc_class_prepared(Class_Handle ch, VTable_Handle vth);
@@ -595,24 +638,6 @@ #endif /* #if defined(USE_GC_STATIC) ||
-/**
- * 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
@@ -653,6 +678,12 @@ VMEXPORT extern void * (*gc_heap_ceiling
#else // USE_GC_STATIC
+/**
+ * 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();
+
/*
* *****
@@ -662,80 +693,139 @@ #else // USE_GC_STATIC
* *****
*/
+/** @defgroup gc_barrier Routines to support various write barriers
+ * @ingroup gc_public */
/**
- * 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.
+ * @ingroup gc_barrier
+ *
+ * Notifies GC that an object was written to.
+ *
+ * This function is called after multiple write operations were performed to the
+ * objects, for example, by <code>System.arrayCopy()</code> or <code>Object.clone()</code>.
*
- * @deprecated Will be removed soon.
+ * @param[in] object - the address of the object that write was performed to
*/
-GCExport void gc_write_barrier(Managed_Object_Handle p_base_of_obj_with_slot);
+GCExport void gc_write_barrier(Managed_Object_Handle object);
/**
- * There are two flavors for historical reasons. The compiler for IA32 will
+ * There are two flavors for historical reasons. The compiler for IA-32 will
* produce code for the version using an offset.
*
- * @deprecated Will be removed soon.
+ * @deprecated The same as gc_write_barrier().
+ * @note FIXME: eliminate this function in favor of gc_write_barrier().
+ *
+ * @ingroup gc_barrier
*/
-GCExport void gc_heap_wrote_object (Managed_Object_Handle p_base_of_object_just_written);
+GCExport void gc_heap_wrote_object(Managed_Object_Handle object);
/**
- * by calling this function VM notifies GC that a heap reference was written to
- * global slot.
+ * Notifies GC that a heap reference needs to be written to the global
+ * slot.
+ *
+ * There are some global slots that are shared by different threads, for example,
+ * the string pools used by the class loader. Write barriers needs information on
+ * when threads write data into these slots. These write operations are
+ * performed by GC.
*
- * There are some global slots that are shared by different threads. Write
- * barriers implementation needs to know about writes to these slots. One
- * example of such slots is in the string pools used by the class loader.
+ * @param slot - the address of the slot to write to
+ * @param value - the value to be written
+ *
+ * @ingroup gc_barrier
*/
-GCExport void gc_heap_write_global_slot(Managed_Object_Handle *p_slot,
+GCExport void gc_heap_write_global_slot(Managed_Object_Handle *slot,
Managed_Object_Handle value);
/**
- * VM should call this function on heap reference writes to global slots.
+ * Notifies GC that a compressed heap reference needs to be written
+ * to a global slot. It is reponsibility of the GC to perform the
+ * requested write operation.
*
* The "compressed" versions of the functions support updates to slots containing
- * compressed references that are heap offsets; these functions handle details of
+ * compressed references that are heap offsets. These functions handle details of
* converting raw reference pointers to compressed references before updating slots.
+ *
+ * @param slot - the address of the slot to write to
+ * @param value - the value to be written
+ *
+ * @ingroup gc_barrier
*/
-GCExport void gc_heap_write_global_slot_compressed(uint32 *p_slot,
- Managed_Object_Handle value);
+GCExport void gc_heap_write_global_slot_compressed(uint32 *slot,
+ uint32 value);
/**
- * VM should call this function on heap reference writes to heap objects.
+ * Notifies GC that an object pointer needs to be written to an
+ * object slot. It is responsibility of the GC to perform the requested
+ * write operation.
+ *
+ * @param object - the pointer to the object containing the slot to be
+ * written to
+ * @param offset - the offset of the slot within the object
+ * @param value - the value to be written to the slot
+ *
+ * @ingroup gc_barrier
*/
-GCExport void gc_heap_write_ref (Managed_Object_Handle p_base_of_object_with_slot,
+GCExport void gc_heap_write_ref (Managed_Object_Handle object,
unsigned offset,
Managed_Object_Handle value);
/**
- * @copydoc gc_heap_write_ref()
+ * Notifies GC that a object pointer needs to be written to an
+ * object slot. It is responsibility of the GC to perform the requested
+ * write operation.
+ *
+ * @param object - the pointer to the object containing the slot to be
+ * written to
+ * @param slot - the address of the slot to be written; stored within the object
+ * @param value - the value to be written to the slot
+ *
+ * @ingroup gc_barrier
*/
-GCExport void gc_heap_slot_write_ref (Managed_Object_Handle p_base_of_object_with_slot,
- Managed_Object_Handle *p_slot,
+GCExport void gc_heap_slot_write_ref (Managed_Object_Handle object,
+ Managed_Object_Handle *slot,
Managed_Object_Handle value);
/**
- * @copydoc gc_heap_write_ref()
+ * @ingroup gc_barrier
+ * Notifies GC that a compressed object pointer needs to be written
+ * to an object slot. It is responsibility of the GC to perform the
+ * requested write operation.
+ *
+ * @param object - the pointer to the object containing the slot to be
+ * written to
+ * @param slot - the address of the slot to be written to; stored within the object
+ * @param value - the value to be written to the slot
+ *
*/
-GCExport void gc_heap_slot_write_ref_compressed (Managed_Object_Handle p_base_of_object_with_slot,
- uint32 *p_slot,
+GCExport void gc_heap_slot_write_ref_compressed (Managed_Object_Handle object,
+ uint32 *slot,
Managed_Object_Handle value);
+/** @defgroup gc_pinning Functions to support pinning
+ * @ingroup gc_public */
/**
- * Pin object.
+ * @ingroup gc_pinning
+ * @ingroup Extended
+ *
+ * Requests to pin an object.
+ *
+ * The function is optional, and has no-op default implementation.
+ * The object is not guaranteed to be pinned after call to this function,
+ * success must be checked by calling gc_is_object_pinned().
+ *
*/
GCExport void gc_pin_object (Managed_Object_Handle* p_object);
/**
- * Unpin object.
+ * Cancels the request to keep the object pinned.
+ *
+ * The function is optional, and has no-op default implementation.
+ * The object is not guaranteed to be unpinned the state after call to this
+ * function, the state must be checked by calling gc_is_object_pinned().
+ *
+ * @ingroup gc_pinning
*/
GCExport void gc_unpin_object (Managed_Object_Handle* p_object);
@@ -745,98 +835,46 @@ GCExport void gc_unpin_object (Managed_O
*/
GCExport Managed_Object_Handle gc_get_next_live_object(void *iterator);
+/** @defgroup gc_refs Routines to support soft, weak, and phantom reference objects
+ * @ingroup gc_public */
+
/**
- * Moves all finalizable objects to vm finalization queue
+ * Requests GC to transfer the contents of the live finalization
+ * queue to VM using vm_finalize_object().
+ *
+ * @ingroup gc_refs
*/
GCExport void gc_finalize_on_exit();
-
-/*
- * *****
- * *
- * * Routines to support soft, weak, and phantom reference objects.
- * *
- * *****
- */
-
-// XXX move this elsewhere -salikh
-#ifdef JNIEXPORT
/**
- * reference - the reference object to register.
- * referent - the referent of the reference object that is to be
- * retrieved with the get method.
+ * @ingroup gc_misc
*
- * The weak reference code written in Java and the support code provide by the
- * VM must agree on what the layout of a Java.lang.ref.Reference object looks
- * like and agree that any subclassing will only append fields to the agreed
- * upon layout. This seems reasonable.
- *
- * In addition the support code will have exclusive knowledge and control of a
- * single field (called the_referent) which holds the reference to the target
- * object. The java code will assume that this field is a read only integer
- * and should not be traced by the gc. The Java.lang.ref.ReferenceQueue layout
- * needs to also be known by the supporting code so that it can move reference
- * objects onto the queues at the appropriate times. The Java code uses normal
- * mechanisms to load the Reference classes and to create a reference.
- *
- * The constructor code however needs to call the appropriate register function
- * listed below based upon whether we have a soft, weak, or phantom reference.
- * The VM support code will fill in the referent field. The routine
- * gc_get_referent will return the value in this field. Note that the phantom
- * reference method get will not use the gc_get_referent but instead just
- * return NULL as required by the spec.
- *
- * @note XXX Why are they in gc_export.h? -salikh
- */
-JNIEXPORT void JNICALL
-Java_java_lang_ref_Reference_enqueue_reference (JNIEnv *the_env,
- jobject p_obj);
-
-JNIEXPORT jobject JNICALL
-Java_java_lang_ref_Reference_get (JNIEnv *the_env,
- jobject p_obj);
-
-JNIEXPORT void JNICALL
-Java_java_lang_ref_Reference_register_phantom_ref (JNIEnv *the_env, jobject p_obj,
- jobject referent);
-
-JNIEXPORT void JNICALL
-Java_java_lang_ref_Reference_register_soft_ref (JNIEnv *the_env, jobject p_obj,
- jobject referent);
-
-JNIEXPORT void JNICALL
-Java_java_lang_ref_Reference_register_weak_ref (JNIEnv *the_env, jobject p_obj,
- jobject referent);
-/*******/
-#endif
-
-
-/**
* API for the VM to get the time since the last GC happened.
* Returns an unsigned long value in milliseconds.
- *
- * @note Is this call really needed in GC interface? -salikh 2005-05-12
*/
GCExport unsigned int gc_time_since_last_gc();
-
+
/**
- * @return the base address of the heap.
+ * @ingroup gc_misc
*
- * API for VM to determine the starting and ending adddresses of the heap
+ * Returns the base address of the heap.
+ * It is guaranteed that all valid Java objects are located
+ * above the heap base address.
*/
GCExport void *gc_heap_base_address();
/**
- * @return the top address of the heap.
+ * @ingroup gc_misc
+ *
+ * Returns the ceiling address of the heap.
+ * It is guaranteed that all valid Java objects are located
+ * below the heap ceiling address.
*/
GCExport void *gc_heap_ceiling_address();
#endif // USE_GC_STATIC
-#ifdef __cplusplus
-}
-#endif
/**
* \page gc_finalization_and_weak_refs Finalization and weak references design in GC
@@ -844,6 +882,8 @@ #endif
* @author Salikh Zakirov
* @version written on 2005-05-31
*
+ * This is the GC view on finalization.
+ * \subpage vm_finalization_and_weak_refs provides a more detailed view on the VM side
* \section gc_finalization Finalization
*
* According to the JVM specification, VM must call non-trivial finalization methods
@@ -854,7 +894,7 @@ #endif
* bit more by specifying global weak references strength to be about the same as
* phantom reference strengh, however, without requiring any particular interaction
* from them. (In the code we sometimes refer to weak references as <i>short weak
- * references<i>, and call JNI weak global references <i>long weak references</i>.
+ * references</i>, and call JNI weak global references <i>long weak references</i>.
* See gc_add_weak_root_set_entry() for more details).
*
* The requirements described above can be met using following algorithm.
@@ -934,8 +974,43 @@ files. These include:
<LI>Read and Write barrier interface, gc_heap_write_ref() and others.
</UL>
-The conceptual overview of the interface is given in @link guide GC Writers'
-guide @endlink
*/
+
+/**
+ * @page gc_allocation Allocation of objects
+ *
+ * There is a tension between fast allocation of objects and
+ * honoring various constraints VM might place on the object.
+ * These constraints include registering the objects for
+ * finalization, aligning the objects on multiple word boundaries,
+ * pinning objects for performance reasons, registering objects
+ * related to weak pointers and so forth.
+ *
+ * We have tried to resolve this tension by overloading the
+ * size argument that is passed to the allocation routine. If
+ * the size of the argument has a high bit of 0, then the
+ * allocation routine will assume that no constraints exist
+ * on the allocation of this object and allocation can potentially
+ * be made very fast. If on the other hand the size is large then
+ * the routine will query the class data structure to determine
+ * what constraints are being made on the allocation of this object.
+ *
+ * The vm_gc.h interface provides the following masks
+ * to allow the gc to quickly determine the constraints.
+ * <PRE>
+ * #CL_PROP_NON_REF_ARRAY_MASK 0x1000
+ * #CL_PROP_ARRAY_MASK 0x2000
+ * #CL_PROP_PINNED_MASK 0x4000
+ * #CL_PROP_FINALIZABLE_MASK 0x8000
+ * #CL_PROP_ALIGNMENT_MASK 0x0FFF
+ * </PRE>
+ */
+
+
+
+#ifdef __cplusplus
+}
+#endif
+
#endif // _OPEN_GC_H
diff --git a/vm/include/open/vm_gc.h b/vm/include/open/vm_gc.h
old mode 100644
new mode 100755
index db409ed..ee8c72e
--- a/vm/include/open/vm_gc.h
+++ b/vm/include/open/vm_gc.h
@@ -13,21 +13,15 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
- * @author Intel, Salikh Zakirov
- * @version $Revision: 1.1.2.1.4.3 $
- */
-
#ifndef _OPEN_VM_GC_H
#define _OPEN_VM_GC_H
/**
* @file
- * These are the functions that a GC built as a DLL may call.
+ * VM interface provided specifically for the GC operation.
*/
-
-#include <stdio.h>
+#include <stdio.h>
#include "open/types.h"
#ifdef __cplusplus
@@ -37,53 +31,63 @@ #endif
/**
- * @return the number of bytes allocated by VM in VTable
- * for use by GC.
+ * Returns the number of bytes allocated by VM in VTable for GC purposes.
*/
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.
+ * Returns the number of bytes allocated by VM in the thread-local storage
+ * for GC purposes.
+ *
+ * The GC does not work with the thread-local storage directly. Instead,
+ * the callers pass the pointer to the thread-local GC data structure
+ * directly to GC functions, such as gc_alloc() or gc_thread_init().
+ * The GC can also use the function vm_get_gc_thread_local() to
+ * get the GC thread-local structure.
*/
VMEXPORT size_t vm_number_of_gc_bytes_in_thread_local();
/**
- * @return the pointer to thread-local area of current thread.
+ * Returns the pointer to GC thread-local area of the current thread.
*/
VMEXPORT void *vm_get_gc_thread_local();
/**
- * 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.
+ * Acquires the lock that guards all GC-related operations in VM.
+ *
+ * If the lock cannot be acquired, the thread waits until the lock is available.
* This operation marks the current thread as being safe for root set
- * enumeration.
+ * enumeration, so must be called from suspend-safe points only.
*/
VMEXPORT void vm_gc_lock_enum();
/**
- * Release the system-wide lock acquired by vm_gc_lock_enum().
+ * Releases 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.
+ * Requests VM to suspend all Java threads and start root set
+ * enumeration.
+ *
+ * To call this function, the GC must obtain a global GC lock
+ * using vm_gc_lock_enum().
*
- * Root set enumeration for all managed threads.
+ * @see vm_resume_threads_after()
*/
VMEXPORT void vm_enumerate_root_set_all_threads();
/**
- * GC calls this function to restart managed threads after root set
- * enumeration is complete.
+ * Requests VM to resume threads suspended by
+ * vm_enumerate_root_set_all_threads().
*
- * This function resumes all threads suspended by
- * vm_enumerate_root_set_all_threads()
+ * The GC must not release the global GC lock before
+ * resuming the threads.
*/
VMEXPORT void vm_resume_threads_after();
@@ -96,12 +100,12 @@ VMEXPORT void vm_resume_threads_after();
VMEXPORT void vm_classloader_iterate_objects(void *iterator);
/**
- * 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.
+ * Informs VM that finalizers may need to be run
+ * and references enqueued. This function 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.
+ * @note The function is introduced as a workaround for running finalizers
+ * until a complete solution with the finalizer thread is implemented.
*/
VMEXPORT void vm_hint_finalize();
@@ -113,13 +117,13 @@ VMEXPORT bool is_it_finalize_thread();
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,
@@ -142,88 +146,102 @@ VMEXPORT enum safepoint_state get_global
*/
VMEXPORT Boolean verify_object_header(void *ptr);
+/** * @defgroup vm_finalize Routines to support finalization of objects and
+ * weak reference support. */
-/*
- * *****
- * *
- * * Routines to support finalization of objects.
- * *
- * *****
+/**
+ * @ingroup vm_finalize
+ * Passes the object eligible for finalization to VM.
+ *
+ * GC calls this function when an object becomes "f-reachable,
+ * finalizable". VM later finalizes these objects in a way that is
+ * not part of this interface.
+ *
+ * Because the finalizer function can be called during the stop-the-world
+ * garbage collection phase, VM must not call the function immediately
+ * to prevent deadlocks in user code, because this functions may be called
+ * phase.
+ *
+ * @param object - object to be finalized
*/
+VMEXPORT void vm_finalize_object(Managed_Object_Handle object);
/**
- * 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.
+ * @ingroup vm_finalize
+ * Passes the weak reference object to VM to call its enqueue()
+ * method.
+ *
+ * GC calls this function when a weak reference object needs
+ * to be enqueued, that is, when the reference cannot be reached anymore.
+ *
+ * @param object - weak reference object to be enqueued
*/
-VMEXPORT void vm_finalize_object(Managed_Object_Handle p_obj);
+VMEXPORT void vm_enqueue_reference(Managed_Object_Handle object);
/**
- * GC should call this function when an phantom reference object
- * is to be enqueued, i.e. when the reference is not reachable anymore.
+ * Weak reference types.
*/
-VMEXPORT void vm_enqueue_reference(Managed_Object_Handle p_obj);
-
enum WeakReferenceType {
- NOT_REFERENCE = 0,
- WEAK_REFERENCE,
- SOFT_REFERENCE,
- PHANTOM_REFERENCE
+ NOT_REFERENCE = 0, ///< ordinary object type
+ WEAK_REFERENCE, ///< weak reference type
+ SOFT_REFERENCE, ///< soft reference type
+ PHANTOM_REFERENCE ///< phantom reference type
};
/**
- * Returns non-zero value if the class represented by Class_Handle
- * is a descendant of java.lang.ref.Reference. The particular type
- * of reference (weak, soft or phantom) is encoded by the return
+ * @ingroup vm_finalize
+ * Returns a non-zero value if the class represented by <i>Class_Handle</i>
+ * is a descendant of <code>java.lang.ref.Reference</code>. The type
+ * of reference (weak, soft or phantom) is encoded by the return
* value of WeakReferenceType.
+ *
+ * @param clss - class handle
*/
VMEXPORT WeakReferenceType class_is_reference(Class_Handle clss);
/**
- * Returns the offset of the referent field
- * in the java.lang.ref.Reference object.
+ * @ingroup vm_finalize
+ * Returns the offset of the referent field
+ * in the <code>java.lang.ref.Reference</code> object.
*
- * clss is assumed to represent the reference object,
- * i.e. class_is_reference() returned non-zero value.
+ * @note The function assumes that <code>clss</code> represents
+ * the reference object, that is, class_is_reference() must return
+ * a non-zero value.
*
- * @note the returned value is most probably a constant,
- * and is not dependent on the clss.
+ * The returned value is most probably a constant and does not depend
+ * on the <code>clss</code> value.
*
- * @note this interface allows only one non-strong (i.e. weak
- * soft or phantom) reference per object.
- * It seems to be sufficient for JVM Spec.
+ * This interface allows only one non-strong (weak, soft or phantom)
+ * reference per object. This seems to be sufficient for JVM Spec.
+ *
+ * @param clss - class handle
*/
VMEXPORT int class_get_referent_offset(Class_Handle clss);
+#define CL_PROP_ALIGNMENT_MASK 0x00FFF ///< @ingroup class_properties
+#define CL_PROP_NON_REF_ARRAY_MASK 0x01000 ///< @ingroup class_properties
+#define CL_PROP_ARRAY_MASK 0x02000 ///< @ingroup class_properties
+#define CL_PROP_PINNED_MASK 0x04000 ///< @ingroup class_properties
+#define CL_PROP_FINALIZABLE_MASK 0x08000 ///< @ingroup class_properties
-#define CL_PROP_ALIGNMENT_MASK 0x00FFF ///< @see class_properties
-#define CL_PROP_NON_REF_ARRAY_MASK 0x01000 ///< @see class_properties
-#define CL_PROP_ARRAY_MASK 0x02000 ///< @see class_properties
-#define CL_PROP_PINNED_MASK 0x04000 ///< @see class_properties
-#define CL_PROP_FINALIZABLE_MASK 0x08000 ///< @see class_properties
-
-
-/**
- * @section class_properties Class properties flags
+/** * @defgroup class_properties Class properties flags
+ *
+ *
+ * <pre>
* 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
- */
+ * ^------------------------ CL_PROP_FINALIZABLE_MASK
+ * </pre> */
/**
- * extract the recursion counter from object lockword.
+ * Extracts the recursion counter from the object lockword structure.
*/
-#define P_RECURSION_BYTE(x) ( (uint8 *)(((x)->get_obj_info_addr())) + 1 )
+#define P_RECURSION_BYTE(x) ( (uint8 *)(((x)->get_obj_info_addr())) + 1 )
#ifdef GC_PUBLIC_PRIVATE
@@ -240,10 +258,6 @@ #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.
*
@@ -262,9 +276,9 @@ #endif
* 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
+ * 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).
+ * fast path by object size overloading hack (see \ref gc_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
@@ -274,7 +288,7 @@ #endif
* 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
+ * and reported to 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
@@ -293,7 +307,7 @@ #endif
* \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
+ * \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.
@@ -301,11 +315,13 @@ #endif
*
* \section vm_weak_refs Weak references
*
- * See the description of how weak references work in GC:
+ * See the description of how weak references work in GC:
* \ref gc_finalization_and_weak_refs
- *
+ *
*/
-
+#ifdef __cplusplus
+}
+#endif
#endif // _OPEN_VM_GC_H
---------------------------------------------------------------------
Terms of use : http://incubator.apache.org/harmony/mailing.html
To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
For additional commands, e-mail: harmony-dev-help@incubator.apache.org