Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@harmony.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r680122 -
 /harmony/enhanced/drlvm/trunk/vm/gc_gen/javasrc/org/apache/harmony/drlvm/gc_gen/GCHelper.java
Date: Sun, 27 Jul 2008 15:14:49 -0000
To: commits@harmony.apache.org
From: aaf@apache.org
Message-Id: <20080727151449.983752388882@eris.apache.org>

Author: aaf
Date: Sun Jul 27 08:14:49 2008
New Revision: 680122

URL: http://svn.apache.org/viewvc?rev=680122&view=rev
Log:
Committed HARMONY-5908 [drlvm][gc_gen] Java VM/GC Interface Documentation.

Modified:
    harmony/enhanced/drlvm/trunk/vm/gc_gen/javasrc/org/apache/harmony/drlvm/gc_gen/GCHelper.java

Modified: harmony/enhanced/drlvm/trunk/vm/gc_gen/javasrc/org/apache/harmony/drlvm/gc_gen/GCHelper.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/gc_gen/javasrc/org/apache/harmony/drlvm/gc_gen/GCHelper.java?rev=680122&r1=680121&r2=680122&view=diff
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/gc_gen/javasrc/org/apache/harmony/drlvm/gc_gen/GCHelper.java (original)
+++ harmony/enhanced/drlvm/trunk/vm/gc_gen/javasrc/org/apache/harmony/drlvm/gc_gen/GCHelper.java Sun Jul 27 08:14:49 2008
@@ -24,6 +24,17 @@
 import org.vmmagic.unboxed.*;
 import org.vmmagic.pragma.*;
 
+/**
+ * GCHelper contains GC methods written in Java, that can be jitted by JIT as
+ * normal Java code. The GC helper supports common GC functionalities such as
+ * allocation and write barriers. The GC module is built into a shared object
+ * binary exporting a set of well defined VM/GC interface. Symbols in dynamic
+ * shared objects can only be accessed indirectly, which leads to a runtime 
+ * overhead of indirect function calling and parameter serializing. The GC
+ * helper is designed to solve these boundary crossing problem.
+ *
+ * @author Xiao-Feng Li
+ */
 public class GCHelper {
 
     static {
@@ -35,16 +46,59 @@
         helperCallback();
     }
 
+    /** Offset from the base pointer of the GC's Thread Local Storage Structure. */
     public static final int TLS_GC_OFFSET = TLSGCOffset();
+
+    /** 
+     * Number of Bytes prefetched in advance. The default prefetch distance is 1KB.
+     * The prefetch distance can be set using the -XX:gc.prefetch_distance=N JRE
+     * Option. N is the number of bytes. 
+     */
     public static final int PREFETCH_DISTANCE = getPrefetchDist();    
+
+    /**
+     * Number of bytes cleared in forward direction when allocating a new memory block
+     * for a thread. The default zeroing size is 2KB. The zeroing size can be set using
+     * the -XX:gc.zeroing_size=N JRE Option. N is the number of bytes.
+     */
     public static final int ZEROING_SIZE = getZeroingSize();
+
+    /**
+     * The number of bytes of prefetch stride. The default prefetch stride is 64 bytes.
+     * The prefetch stride can be set using the -XX:gc.prefetch_stride=N JRE Option.
+     * N is the number of bytes.
+     */
     public static final int PREFETCH_STRIDE = getPrefetchStride();
 
+    /**
+     * Offset of member free of the Allocator structure.
+     */
     public static final int TLA_FREE_OFFSET = getTlaFreeOffset();
+
+    /**
+     * Offset of member ceiling of the Allocator structure.
+     */
     public static final int TLA_CEILING_OFFSET = getTlaCeilingOffset();
+
+    /**
+     * Offset of member end of the Allocator structure.
+     */
     public static final int TLA_END_OFFSET = getTlaEndOffset();
 
+    /**
+     * Large Object Size Threshold value. Objects that are of size greater than this
+     * threshold value are allocated in LOS (large object space). This value is used
+     * to divide the heap into spaces.
+     */
     public static final int LARGE_OBJECT_SIZE = getLargeObjectSize();
+
+    /**
+     * States whether allocation prefetch is enabled or disabled. Allocation prefetch is
+     * disabled by default. However, enabling it may improve application performance.
+     * Enabling/Disabling prefetch is done by the -XX:gc.prefetch=true|false JRE Option.
+     * To enable prefetching a platform-specific distance ahead when allocating in the
+     * Thread Local Allocation buffer, set the -XX:gc.prefetch option to true.
+     */
     public static final boolean PREFETCH_ENABLED = isPrefetchEnabled();
 
 
@@ -96,6 +150,21 @@
         return VMHelper.newResolvedUsingAllocHandleAndSize(objSize, allocationHandle);    
     }
 
+    /**
+     * Allocates memory requested by a Java Class. This method uses a class handle
+     * to obtain the allocation handle and size of object to allocate. Once memory
+     * has been allocated for the object, the address at which memory was allocated
+     * is returned.
+     *
+     * @param classHandle The C native struct corresponding to java.lang.Class
+     *                    uses a class handle to refer to a specific instance of a
+     *                    java.lang.Class. In here we pass in the class handle of
+     *                    corresponding java.lang.Class to which we wish to allocate
+     *                    memory.
+     * @return            Address of the allocated block of memory as seen by the
+     *                    java side of this interface.
+     * @see               Address
+     */
     @Inline
     public static Address alloc(Address classHandle) {
         int objSize = VMHelper.getTypeSize(classHandle);
@@ -107,6 +176,32 @@
     private static final int ARRAY_LEN_OFFSET = 8;
     private static final int GC_OBJECT_ALIGNMENT = getGCObjectAlignment();
 
+    /**
+     * Allocates memory requested by a Java Array Class or Java Vector Class. This 
+     * method uses a element class handle to obtain the handle of the array (or vector)
+     * class corresponding to the given element. The handle of the array (or vector) is 
+     * used to obtain the allocation handle and the size of an element of the array (or 
+     * vector). It then allocates enough memory to hold arrayLen number of elements. If 
+     * arrayLen is negative a new Vector is obtained by using the allocation handle and 
+     * if not a new Array is obtained. Once memory has been allocated for the objects,
+     * the address at which memory was allocated is returned.
+     *
+     * @param elemClassHandle The C native struct corresponding to java.lang.Class
+     *                        uses a class handle to refer to a specific instance of a
+     *                        java.lang.Class. In here we pass in the class handle of
+     *                        the element of the type which corresponds to the desired
+     *                        array (or vector) class.
+     * @param arrayLen        If greater than or equal to zero, this indicates the 
+     *                        number of elements in the array. Else, it indicates the 
+     *                        number of elements in the vector.
+     * @return                Address of the allocated block of memory as seen by the
+     *                        java side of this interface. This is the address of the 
+     *                        array class for a arrayLen greater than or equal to zero,
+     *                        or is the address of a vector created using the allocation 
+     *                        handle.
+     * @see                   Address
+     * @see                   VMHelper#newVectorUsingAllocHandle(int, int)
+     */
     @Inline
     public static Address allocArray(Address elemClassHandle, int arrayLen) {
         Address arrayClassHandle = VMHelper.getArrayClass(elemClassHandle);
@@ -129,9 +224,23 @@
        be a constant in future.
     */
 
+    /** Address of Boundary of the NOS (nursery object space). */
     public static Address NOS_BOUNDARY = Address.fromLong(getNosBoundary());
+
+    /** 
+     * States whether GC is in Generational Mode.
+     * True if GC is in Generational Mode or False if GC is in Non-Generational Mode
+     */
     public static boolean GEN_MODE = getGenMode();
 
+    /**
+     * Write Barrier for GC. This method is used to update the slot with the value 
+     * provided. 
+     *
+     * @param p_target  This contains the value being written to the given slot.
+     * @param p_objSlot Address of a memory location being written to.
+     * @param p_objBase Address of the base of the object (or array) being written to.
+     */
     @Inline
     public static void write_barrier_slot_rem(Address p_target, Address p_objSlot, Address p_objBase) {