Index: trunk/vm/include/jit_import_rt.h
===================================================================
--- trunk/vm/include/jit_import_rt.h (revision 487512)
+++ trunk/vm/include/jit_import_rt.h (working copy)
@@ -14,16 +14,12 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
- * @author Intel, Alexei Fedotov
- * @version $Revision: 1.1.2.1.4.3 $
- */
+/**
+ * @file
+ * These are the functions that a JIT built as a DLL may call.
+ */
-//
-// These are the functions that a JIT built as a DLL may call.
-//
-
#ifndef _JIT_IMPORT_RT_H
#define _JIT_IMPORT_RT_H
@@ -34,38 +30,44 @@
#ifdef __cplusplus
extern "C" {
#endif
-
-
-///////////////////////////////////////////////////////
-// begin root set enumeration functions.
-
-
-// Enumerate a root entry. The argument is a pointer to the memory
-// location that contains a managed reference. The GC may update
-// this location if the object pointed to has been moved during
-// collection.
+/**
+ * Begin root set enumeration functions.
+ *
+ * Enumerate a root entry. The argument is a pointer to the memory
+ * location that contains a managed reference. The GC may update
+ * this location if the object pointed to has been moved during
+ * collection.
+ */
VMEXPORT void vm_enumerate_root_reference(Managed_Object_Handle *ref, Boolean is_pinned);
-// Resembles vm_enumerate_root_reference() but is passed the address of
-// a slot containing a compressed reference.
+/**
+ * Resembles vm_enumerate_root_reference(), but is passed the
+ * address of a slot containing a compressed reference.
+ */
VMEXPORT void vm_enumerate_compressed_root_reference(uint32 *ref, Boolean is_pinned);
-// Like vm_enumerate_root_reference() but the first argument points
-// to a location that contains a pointer to an inside of an object.
+/**
+ * Like vm_enumerate_root_reference(), but the first argument
+ * points to a location that contains a pointer to an inside of an object.
+ */
VMEXPORT void vm_enumerate_root_interior_pointer(void **slot, int offset, Boolean is_pinned);
-// The JIT enumerates 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 runtime system to ignore pointers that are not in the managed heap.
+/**
+ * The JIT enumerates 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 runtime system to ignore pointers that are not in the managed heap.
+ */
VMEXPORT void vm_enumerate_root_pointer(void **ptr, Boolean is_pinned);
-// end root set enumeration functions.
-///////////////////////////////////////////////////////
+/**
+ * End root set enumeration functions.
+ */
-///////////////////////////////////////////////////////
-//enumerates alive references for owned monitor calculation
+/**
+ * Enumerates alive references for owned monitor calculation.
+ */
VMEXPORT void vm_check_if_monitor(void **reference,
void **base_reference,
Index: trunk/vm/include/jit_runtime_support.h
===================================================================
--- trunk/vm/include/jit_runtime_support.h (revision 487512)
+++ trunk/vm/include/jit_runtime_support.h (working copy)
@@ -14,31 +14,24 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
- * @author Intel, Evgueni Brevnov, Ivan Volosyuk
- * @version $Revision: 1.1.2.2.4.4 $
- */
-
-
-
#ifndef _JIT_RUNTIME_SUPPORT_H_
#define _JIT_RUNTIME_SUPPORT_H_
#include "open/types.h"
-//
-// This is a complete set of functions used by the code generated by the JIT.
-// The address of a function is obtained from the VM by invoking the
-// function vm_get_rt_support_addr (see below).
-//
+/**
+ * This is a complete set of functions used by the code generated by the JIT.
+ * The address of a function is obtained from the VM by invoking the
+ * function vm_get_rt_support_addr (see below).
+ *
+ * We should also note which exceptions can be thrown by each
+ * of those function.
+ *
+ * If changes are made to enum VM_RT_SUPPORT below, the list of
+ * JIT support functions in vm_stats.cpp must also be changed.
+ */
-// We should also note which exceptions can be thrown by each
-// of those function.
-
-// If changes are made to enum VM_RT_SUPPORT below, the list of JIT support functions in vm_stats.cpp must also be changed.
-
-
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
@@ -46,378 +39,459 @@
typedef
enum VM_RT_SUPPORT {
- //////////////////////////////////////////////////////////////////////////
- // Object creation routines
- //////////////////////////////////////////////////////////////////////////
+/**
+ * Object creation routines.
+ */
VM_RT_NEW_RESOLVED_USING_VTABLE_AND_SIZE=100,
- // Arguments:
- // - Size of the instance to be created
- // - Allocation_Handle for the class whose instance we want to create
- // Return value:
- // - Reference to the new object
- //
- // Like VM_RT_NEW_VECTOR_USING_VTABLE, allocates a new object of a class, but also takes a
- // size argument. The size can be obtained using class_get_boxed_data_size(Class_Handle).
- // This function should be used for classes which inherit the finalize method
- // of java.lang.Object.
+/**
+ * @param The parameters are the following:
+ * \arg Size of the instance to be created
+ * \arg Allocation_Handle for the class whose instance we want to create
+ *
+ * @return Reference to the new object.
+ *
+ * Like VM_RT_NEW_VECTOR_USING_VTABLE, allocates a new object of
+ * a class, but also takes a size argument. The size can be obtained using
+ * class_get_boxed_data_size(Class_Handle).
+ * This function should be used for classes which inherit the finalize method
+ * of java.lang.Object.
+ */
VM_RT_NEW_VECTOR_USING_VTABLE=101,
- // Arguments:
- // - Allocation_Handle for the vector class
- // - Vector length
- // Return value:
- // - Reference to the new object
- //
- // Like VM_RT_NEW_VECTOR. creates a vector (zero-based, one dimensional array) of the given type,
- // but takes a Allocation_Handle instead of a Class_Handle.
-
+/**
+ * @param The parameters are the following:
+ * \arg Allocation_Handle for the vector class
+ * \arg Vector length
+ *
+ * @return Reference to the new object.
+ *
+ * Like VM_RT_NEW_VECTOR creates a vector
+ * (zero-based, one dimensional array) of the given type,
+ * but takes a Allocation_Handle instead of a
+ * Class_Handle.
+ */
VM_RT_MULTIANEWARRAY_RESOLVED=102,
- // There is a variable # of arguments:
- // - Class handle
- // - Number of dimensions
- // - Count_n
- // - ...
- // - Count_1
- // Return value:
- // - Reference to the new object
- //
- // This is __cdecl function and the caller must pop the arguments.
- // Create a multidimensional Java array
- //
+ /**
+ * There is a variable # of arguments:
+ * \arg Class handle
+ * \arg Number of dimensions
+ * \arg Count_n
+ * \arg ...
+ * \arg Count_1
+ *
+ * @return Reference to the new object.
+ *
+ * This is __cdecl function and the caller must pop the arguments.
+ * Create a multidimensional Java array.
+ */
VM_RT_LDC_STRING=103,
- // Arguments:
- // - Const pool index pointing to a CONSTANT_Class.
- // - Class handle of the class owning the const pool
- // Return value:
- // - Reference to the String object.
- //
- // Returns a reference to the const string represented by an entry in the
- // const pool.
+/**
+ * @param The parameters are the following:
+ * \arg Const pool index pointing to a CONSTANT_Class.
+ * \arg Class handle of the class owning the const pool
+ *
+ * @return \arg Reference to the String object.
+ * \arg Reference to the const string represented by an entry in the
+ * const pool.
+ */
+/////
+// Exception throwing routines
+/////
-
- //////////////////////////////////////////////////////////////////////////
- // Exception throwing routines
- //////////////////////////////////////////////////////////////////////////
-
VM_RT_THROW=200,
- // Arguments:
- // - Object reference
- // Return value: none.
- //
- // The only argument is a reference to the exception to be thrown.
- // Throw the exception without modifying the stack trace associated
- // with the exception object. This function is appropriate for the
- // JVML athrow instruction.
- // This function never returns.
+/**
+ * @param Object reference
+ *
+ * @return None.
+ *
+ * The only argument is a reference to the exception to be thrown.
+ * Throw the exception without modifying the stack trace associated
+ * with the exception object. This function is appropriate for the
+ * JVML athrow instruction.
+ * This function never returns.
+ */
VM_RT_THROW_SET_STACK_TRACE=210,
- // Arguments:
- // - Object reference
- // Return value: none.
- //
- // The only argument is a reference to the exception to be thrown.
- // Throw the exception and set the stack trace associated
- // with the exception object. This function is appropriate for the
- // CIL throw instruction.
- // This function never returns.
+
+
+/**
+ * @param Object reference.
+ *
+ * @return None.
+ *
+ * The only argument is a reference to the exception to be thrown.
+ * Throw the exception and set the stack trace associated
+ * with the exception object. This function is appropriate for the
+ * CIL throw instruction.
+ *
+ *This function never returns.
+ */
-
VM_RT_THROW_LAZY=201,
- // Arguments:
- // - Method handle
- // - ...
- // - arg 2
- // - arg 1
- // - Class handle
- // Return value: none.
- //
- // The arguments to the constructor are pushed the same way they would have
- // been pushed to invoke the constructor, except that the (non-existing)
- // this pointer is replaced with the class handle of the exception.
- // The method handle representing the constructor is pushed last.
- //
- // This function never returns.
+/**
+ * @param The parameters are the following:
+ * \arg Method handle
+ * \arg ...
+ * \arg arg 2
+ * \arg arg 1
+ * \arg Class handle
+ *
+ * @return None.
+ *
+ * The arguments to the constructor are pushed the same way they would have
+ * been pushed to invoke the constructor, except that the (non-existing)
+ * this pointer is replaced with the class handle of the exception.
+ * The method handle representing the constructor is pushed last.
+ *
+ * This function never returns.
+ */
VM_RT_IDX_OUT_OF_BOUNDS=202,
- // Arguments: none
- // Return value: none.
- //
- // Throw the java/lang/ArrayIndexOutOfBoundsException
- // This function never returns.
-
+
+/**
+ * @param none
+ *
+ * @return None.
+ *
+ * Throw the java/lang/ArrayIndexOutOfBoundsException.
+ *
+ * This function never returns.
+ */
VM_RT_NULL_PTR_EXCEPTION=203,
- // Arguments: none
- // Return value: none.
- //
- // Throw the java/lang/NullPointerException
- // This function never returns.
-
+
+/**
+ * @param none
+ *
+ * @return None.
+ *
+ * Throw the java/lang/NullPointerException
+ *
+ * This function never returns.
+ */
VM_RT_DIVIDE_BY_ZERO_EXCEPTION=204,
- // Arguments: none
- // Return value: none.
- //
- // Throw the java/lang/ArithmeticException
- // This function never returns.
+
+/**
+ * @param none
+ *
+ * @return None.
+ *
+ * Throw the java/lang/ArithmeticException.
+ *
+ * This function never returns.
+ */
VM_RT_ARRAY_STORE_EXCEPTION=205,
- // Arguments: none
- // Return value: none.
- //
- // Throw the java/lang/ArrayStoreException
- // This function never returns.
+
+/**
+ * @param none
+ *
+ * @return None.
+ *
+ * Throw the java/lang/ArrayStoreException.
+ *
+ * This function never returns.
+ */
VM_RT_THROW_LINKING_EXCEPTION=206,
- // Arguments:
- // - Const pool index.
- // - Class handle of the class owning the const pool.
- // - Loader exception returned by the VM.
- // Return value: none.
- //
- // Throws a linking exception reported by the VM at compile-time.
+/**
+ * @param The parameters are the following:
+ * \arg Const pool index
+ * \arg Class handle of the class owning the const pool
+ * \arg Loader exception returned by the VM
+ *
+ * @return None.
+ *
+ * Throws a linking exception reported by the VM at compile-time.
+ */
+ ////
+ // Synchronization routines
+ ////
- //////////////////////////////////////////////////////////////////////////
- // Synchronization routines
- //////////////////////////////////////////////////////////////////////////
-
VM_RT_MONITOR_ENTER=300,
- // Arguments:
- // - Object
- // Return value: none.
- //
- // Acquire the monitor associated with the object.
- // Throw java/lang/NullPointerException if the argument is null.
-
+/**
+ * @param Object
+ *
+ * @return None.
+ *
+ * Acquire the monitor associated with the object.
+ * Throw java/lang/NullPointerException, if the argument is null.
+ */
VM_RT_MONITOR_ENTER_NON_NULL=304,
- // Arguments:
- // - Object
- // Return value: none.
- //
- // Acquire the monitor associated with the object.
- // This function is identical to VM_RT_MONITOR_ENTER except that it
- // assumes that the argument is non-null. Passing a null argument
- // will result in undefined behavior.
-
+ /**
+ * @param Object
+ *
+ * @return None.
+ *
+ * Acquire the monitor associated with the object.
+ * This function is identical to VM_RT_MONITOR_ENTER except that it
+ * assumes that the argument is non-null. Passing a null argument
+ * will result in undefined behavior.
+ */
VM_RT_MONITOR_EXIT=301,
- // Arguments:
- // - Object
- // Return value: none.
- //
- // Release the monitor associated with the object.
- // Throw java/lang/NullPointerException if the argument is null.
- // Throw java/lang/IllegalMonitorStateException if the current thread
- // is not the owner of the lock.
-
+/**
+ * @param Object
+ *
+ * @return None.
+ *
+ * Release the monitor associated with the object.
+ * Throw java/lang/NullPointerException, if the argument is null.
+ * Throw java/lang/IllegalMonitorStateException, if the current
+ * thread is not the owner of the lock.
+ */
VM_RT_MONITOR_EXIT_NON_NULL=305,
- // Arguments:
- // - Object
- // Return value: none.
- //
- // Release the monitor associated with the object.
- // This function is identical to VM_RT_MONITOR_EXIT except that it
- // assumes that the argument is non-null. Passing a null argument
- // will result in undefined behavior.
- // Throw java/lang/IllegalMonitorStateException if the current thread
- // is not the owner of the lock.
-
+
+/**
+ * @param Object
+ *
+ * @return None.
+ *
+ * Release the monitor associated with the object.
+ * This function is identical to VM_RT_MONITOR_EXIT except that it
+ * assumes that the argument is non-null. Passing a null argument
+ * will result in undefined behavior.
+ * Throw java/lang/IllegalMonitorStateException, if the current thread
+ * is not the owner of the lock.
+ */
VM_RT_MONITOR_ENTER_STATIC=302,
- // Arguments:
- // - Class handle
- // Return value: none.
- //
- // Acquire the monitor associated with the class passed as the argument.
-
+/**
+ * @param Class handle
+ *
+ * @return None.
+ *
+ * Acquire the monitor associated with the class passed as the argument.
+ */
VM_RT_MONITOR_EXIT_STATIC=303,
- // Arguments:
- // - Class handle
- // Return value: none.
- //
- // Release the monitor associated with the class passed as the argument.
- // Throw java/lang/IllegalMonitorStateException if the current thread
- // is not the owner of the lock.
+/**
+ * @param Class handle
+ *
+ * @return None.
+ *
+ * Release the monitor associated with the class passed as the argument.
+ * Throw java/lang/IllegalMonitorStateException, if the current thread
+ * is not the owner of the lock.
+ */
+////
+// Type access routines
+////
-
-
- //////////////////////////////////////////////////////////////////////////
- // Type access routines
- //////////////////////////////////////////////////////////////////////////
-
VM_RT_CHECKCAST=400,
- // Arguments:
- // - Object
- // - Class
- // Return value:
- // - Object
- //
- // If object can't be cast to class, throw ClassCastException
+/**
+ * @param The parameters are the following:
+ * \arg Object
+ * \arg Class
+ *
+ * @return Object.
+ *
+ * If object can't be cast to class, throw ClassCastException
+ */
-
VM_RT_INSTANCEOF=401,
- // Arguments:
- // - Object
- // - Class
- // Return value:
- // - 1 if object is not null and can be cast to class
- // - 0 otherwise
-
+/**
+ * @param The parameters are the following:
+ * \arg Object
+ * \arg Class
+ *
+ * @return 1 if object is not null and can be cast to class;
+ * 0 otherwise
+ */
VM_RT_AASTORE=402,
- // Arguments:
- // - Element
- // - Index
- // - Array
- // Return value: none.
- //
- // Store a reference element into into an array.
-
+/**
+ * @param The parameters are the following:
+ * \arg Element
+ * \arg Index
+ * \arg Array
+ *
+ * @return None.
+ *
+ * Store a reference element into into an array.
+ */
VM_RT_AASTORE_TEST=403,
- // Arguments:
- // - Element
- // - Array
- // Return value: 1 if the element can be stored in the array, 0 otherwise.
- //
- // Check if a reference element into into an array. If the 'array'
- // argument is null, return 0. This function does not throw exceptions.
-
+/**
+ * @param The parameters are the following:
+ * \arg Element
+ * \arg Array
+ *
+ * @return 1 if the element can be stored in the array; 0 otherwise.
+ *
+ * Check if a reference element into into an array. If the array
+ * argument is null, return 0. This function does not throw exceptions.
+ */
VM_RT_GET_INTERFACE_VTABLE_VER0=404,
- // Arguments:
- // - Object reference
- // - Class handle for the interface
- // Return value:
- // - Interface vtable with method entries for the implementation
- // of that interface by the actual class of the object.
+/**
+ * @param The parameters are the following:
+ * \arg Object reference
+ * \arg Class handle for the interface
+ *
+ * @return Interface vtable with method entries for the implementation
+ * of that interface by the actual class of the object.
+ */
+ /////
+ //Class initialization
+ /////
-
- //////////////////////////////////////////////////////////////////////////
- // Class initialization
- //////////////////////////////////////////////////////////////////////////
-
VM_RT_INITIALIZE_CLASS=500,
- // Arguments:
- // - Class handle
- // Return value: none.
- //
- // If the class hasn't been initialized yet, initialize it.
- //
- // A call to this function must be generated before every putstatic
- // and getstatic unless the JIT can prove that the class would have
- // been already initialized at that point.
+/**
+ * @param Class handle
+ *
+ * @return None.
+ *
+ * If the class hasn't been initialized yet, initialize it.
+ *
+ * A call to this function must be generated before every putstatic
+ * and getstatic unless the JIT can prove that the class would have
+ * been already initialized at that point.
+ */
+ ////
+ // Write barrier routines
+ ////
-
-
- //////////////////////////////////////////////////////////////////////////
- // Write barrier routines
- //////////////////////////////////////////////////////////////////////////
-
VM_RT_GC_HEAP_WRITE_REF=600,
- // Arguments:
- // - Address of the base of the object (or array) being written to.
- // - Address of a memory location being written to
- // - Value being written.
- // Return value: none.
- //
- // Write barrier for GC. Updates the slot with the value provided.
- // The type being written is indicated in the name.
-
+/**
+ * @param The parameters are the following:
+ * \arg Address of the base of the object (or array) being written to
+ * \arg Address of a memory location being written to
+ * \arg Value being written
+ *
+ * @return None.
+ *
+ * Write barrier for GC. Updates the slot with the value provided.
+ * The type being written is indicated in the name.
+ */
VM_RT_GC_SAFE_POINT=601,
- // Arguments: none
- // Return value: none.
- // Use this helper to notify GC about safe point in managed code
-
+/**
+ * @param none
+ *
+ * @return None.
+ *
+ * Use this helper to notify GC about safe point in managed code.
+ */
VM_RT_GC_GET_TLS_BASE=602,
- // Arguments: none
- // Return value: pointer to int-sized suspension request flag
- //
- // When the flag is non zero, managed code should call VM_RT_GC_SAFE_POINT
- // helper.
- // Note: The flag must be used for read only !
+/**
+ * @param none
+ *
+ * @return Pointer to int-sized suspension request flag.
+ *
+ * When the flag is non zero, managed code should call VM_RT_GC_SAFE_POINT
+ * helper.
+ *
+ * @note The flag must be used for read only!
+ */
+
+
+ /////
+ // JVMTI specific routines
+ /////
- //////////////////////////////////////////////////////////////////////////
- // JVMTI specific routines
- //////////////////////////////////////////////////////////////////////////
-
VM_RT_JVMTI_METHOD_ENTER_CALLBACK = 700,
- // Arguments: handle of the method which gets control
- // Return value: none
- //
- // This call-back should be used to notify about method enter event.
- // Do a call-back when such capability is requested only.
-
+/**
+ * @param handle of the method which gets control
+ *
+ * @return None.
+ *
+ * This call-back should be used to notify about method enter event.
+ * Do a call-back when such capability is requested only.
+ */
VM_RT_JVMTI_METHOD_EXIT_CALLBACK = 701,
- // Arguments:
- // - handle of the method which is about to lose control
- // - method's return value
- // Return value: none
- //
- // This call-back should be used to notify about method exit event.
- // Do a call-back when such capability is requested only.
+/**
+ * @param The parameters are the following:
+ * \arg handle of the method which is about to lose control
+ * \arg method's return value
+ *
+ * @return None.
+ *
+ * This call-back should be used to notify about method exit event.
+ * Do a call-back when such capability is requested only.
+ */
+
+ VM_RT_JVMTI_FIELD_ACCESS_CALLBACK = 702,
- VM_RT_JVMTI_FIELD_ACCESS_CALLBACK = 702,
- // Arguments:
- // - handle of the field under access
- // - handle of the method, which accesses field
- // - location of code which accesses field
- // - pointer to the reference of the object, which field is beeng
- // accessed or NULL for static field
- // Return value: none
- //
- // Notifies about field access.
-
+/**
+ * @param The parameters are the following:
+ * arg\ handle of the field under access
+ * arg\ handle of the method, which accesses field
+ * arg\ location of code which accesses field
+ * arg\ pointer to the reference of the object, which field is beeng
+ * accessed or NULL for static field
+ *
+ * @return None.
+ *
+ * Notifies about field access.
+ */
VM_RT_JVMTI_FIELD_MODIFICATION_CALLBACK = 703,
- // Arguments:
- // - handle of the field under modification
- // - handle of the method, which modifies field
- // - location of code which modifies field
- // - pointer to the reference of the object, which field is beeng
- // modified or NULL for static field
- // - pointer to the new value for the field
- // Return value: none
- //
- // Notifies about field modification.
+/**
+ * @param The parameters are the following:
+ * arg\ handle of the field under modification
+ * arg\ handle of the method, which modifies field
+ * arg\ location of code which modifies field
+ * arg\ pointer to the reference of the object, which field is beeng
+ * modified or NULL for static field
+ * arg\ pointer to the new value for the field
+ *
+ * @return none
+ *
+ * Notifies about field modification.
+ */
- //////////////////////////////////////////////////////////////////////////
- // Runtime resolution routine
- //////////////////////////////////////////////////////////////////////////
+ /////
+ /// Runtime resolution routine
+ /////
VM_RT_RESOLVE = 801,
- // Arguments:
- // - Class handle
- // - Constant pool index of an item to be resolved
- // - A java byte code instruction (JavaByteCodes) the resolution
- // is performed for
- //
- // The helper performs resolution of symbolic references during runtime.
- // If resolution failed, the helper throws appropriate LinkageError.
- // Otherwise, the value depends on byte code passed:
- //
- // === JavaByteCodes === === result of call ===
- // OPCODE_INVOKESTATIC: resolve_static_method
- // OPCODE_INVOKEINTERFACE: resolve_interface_method
- // OPCODE_INVOKEVIRTUAL,
- // OPCODE_INVOKESPECIAL: resolve_virtual_method
- // OPCODE_INSTANCEOF,
- // OPCODE_CHECKCAST,
- // OPCODE_MULTIANEWARRAY resolve_class
- // OPCODE_ANEWARRAY: class_get_array_of_class(resolve_class())
- // OPCODE_NEW: resolve_class_new
- // OPCODE_GETFIELD,
- // OPCODE_PUTFIELD: resolve_nonstatic_field
- // OPCODE_PUTSTATIC,
- // OPCODE_GETSTATIC: resolve_static_field
- //
- // The helper initializes class if the class hasn't been initialized yet
- // for PUTSTATIC and GETSTATIC
- //
+
+/**
+ * @param The parameters are the following:
+ * arg\ Class handle
+ * arg\ Constant pool index of an item to be resolved
+ * arg\ A java byte code instruction (JavaByteCodes)
+ * the resolution is performed for
+ *
+ * The helper performs resolution of symbolic references during runtime.
+ * If resolution failed, the helper throws appropriate LinkageError.
+ * Otherwise, the value depends on byte code passed:
+ *
+ * === JavaByteCodes === === result of call ===
+ *
+ * OPCODE_INVOKESTATIC: resolve_static_method
+ *
+ * OPCODE_INVOKEINTERFACE: resolve_interface_method
+ *
+ * OPCODE_INVOKEVIRTUAL,
+ *
+ * OPCODE_INVOKESPECIAL: resolve_virtual_method
+ *
+ * OPCODE_INSTANCEOF,
+ *
+ * OPCODE_CHECKCAST,
+ *
+ * OPCODE_MULTIANEWARRAY resolve_class
+ *
+ * OPCODE_ANEWARRAY: class_get_array_of_class(resolve_class())
+ *
+ * OPCODE_NEW: resolve_class_new
+ *
+ * OPCODE_GETFIELD,
+ *
+ * OPCODE_PUTFIELD: resolve_nonstatic_field
+ *
+ * OPCODE_PUTSTATIC,
+ *
+ * OPCODE_GETSTATIC: resolve_static_field
+ *
+ * The helper initializes class if the class hasn't been initialized yet
+ * for PUTSTATIC and GETSTATIC.
+ */
- //////////////////////////////////////////////////////////////////////////
- // Non-VM specific helpers for the JIT
- //////////////////////////////////////////////////////////////////////////
+ /////
+ // Non-VM specific helpers for the JIT
+ /////
VM_RT_F2I=900,
VM_RT_F2L=901,
@@ -429,16 +503,16 @@
VM_RT_LSHL=910,
VM_RT_LSHR=911,
VM_RT_LUSHR=912,
- // Arguments:
- // (new version)
- // - Long value to be shifted
- // - Int value with count
- // (old version)
- // - (edx:eax) A long value to be shifted
- // - (ecx) Count
- // Return value: (edx:eax)
- // - The shifted value
- //
+ * Arguments:
+ * (new version)
+ * - Long value to be shifted
+ * - Int value with count
+ * (old version)
+ * - (edx:eax) A long value to be shifted
+ * - (ecx) Count
+ * Return value: (edx:eax)
+ * - The shifted value
+ *
VM_RT_LMUL=920,
@@ -464,57 +538,62 @@
// Float/double arithmetic
VM_RT_CHAR_ARRAYCOPY_NO_EXC=950,
- // Arguments:
- // - Object reference for the source array. Must be non-null and refer to an array
- // of 16 bit chars.
- // - int32 containing the starting index of the source array to copy.
- // - Object reference for the destination array. Must be non-null and refer to an array
- // of 16 bit chars.
- // - int32 containing the starting index of the destination array to copy into.
- // - int32 containing the number of 16 bit chars to copy.
- // Return value: none.
- //
- // This runtime helper function provides a specialized implementation for System.arraycopy
- // for the common case where the elements of the arrays are
- // 16 bit characters and the array references are both non-null. The JIT must guarantee
- // that no exceptions will need to be thrown. That is, both array references are non-null,
- // the types match (and are both arrays of 16 bit characters),
- // and the starting indexes and length are such that the copying will only access
- // data in the bounds of the arrays.
+/**
+ * @param The parameters are the following:
+ * arg\ Object reference for the source array. Must be non-null and refer to an array
+ * of 16 bit chars
+ * arg\ int32 containing the starting index of the source array to copy
+ * arg\ Object reference for the destination array. Must be non-null and refer to an array
+ * of 16 bit chars.
+ * arg\ int32 containing the starting index of the destination array to copy into.
+ * arg\ int32 containing the number of 16 bit chars to copy.
+ *
+ * @return None.
+ *
+ * This runtime helper function provides a specialized implementation for System.arraycopy
+ * for the common case where the elements of the arrays are
+ * 16 bit characters and the array references are both non-null. The JIT must guarantee
+ * that no exceptions will need to be thrown. That is, both array references are non-null,
+ * the types match (and are both arrays of 16 bit characters),
+ * and the starting indexes and length are such that the copying will only access
+ * data in the bounds of the arrays.
+ */
+ ////
+ // Deprecated routines
+ ////
-
- //////////////////////////////////////////////////////////////////////////
- // Deprecated routines
- //////////////////////////////////////////////////////////////////////////
-
VM_RT_NEW_RESOLVED=1000,
- // Arguments:
- // - Class handle for the class whose object we want to create
- // Return value:
- // - Reference to the new object
- //
- // Allocates a new object of the class. This function should be used
- // for classes which inherit the finalize method of java.lang.Object.
- // See also VM_RT_NEW_RESOLVED_USING_VTABLE.
-
+/**
+ * @param Class handle for the class whose object we want to create
+ *
+ * @return Reference to the new object.
+ *
+ * Allocates a new object of the class. This function should be used
+ * for classes which inherit the finalize method of java.lang.Object.
+ * See also VM_RT_NEW_RESOLVED_USING_VTABLE.
+ */
VM_RT_NEW_VECTOR=1001,
- // Arguments:
- // - Vector length
- // - Class handle of the vector class
- // Return value:
- // - Reference to the new object
- //
- // Create a vector (zero-based, one dimensional array)
- // of the given type. See also VM_RT_NEW_VECTOR_USING_VTABLE.
-
+/**
+ * @param The parameters are the following:
+ * arg\ Vector length
+ * arg\ Class handle of the vector class
+ *
+ * @return Reference to the new object
+ *
+ * Create a vector (zero-based, one dimensional array)
+ * of the given type. See also VM_RT_NEW_VECTOR_USING_VTABLE.
+ */
VM_RT_WRITE_BARRIER_FASTCALL=1002
- // Arguments:
- // - Address of a memory location being written to
- // - Object reference being written.
- // Return value: none.
- //
- // Write barrier for GC.
+/**
+ * @param The parameters are the following:
+ * arg\ Address of a memory location being written to
+ * arg\ Object reference being written.
+ *
+ * @return None.
+ *
+ * Write barrier for GC.
+ */
} VM_RT_SUPPORT; //VM_RT_SUPPORT
@@ -525,16 +604,18 @@
VMEXPORT void *vm_get_rt_support_addr(VM_RT_SUPPORT f);
-/* temporary interface addition
- * same as vm_get_rt_support_addr, but tries to optimize the stubs it creates,
+/**
+ * Temporary interface addition
+ * same as vm_get_rt_support_addr, but tries to optimize the stubs it creates,
* by specializing them.
*/
VMEXPORT void *vm_get_rt_support_addr_optimized(VM_RT_SUPPORT f, Class_Handle c);
-
-// instead of returning a stub address, this support function returns
-// parsed LIL code.
-typedef struct LilCodeStub LilCodeStub;
+/**
+ * Instead of returning a stub address, this support function returns
+ * parsed LIL code.
+ */
+ typedef struct LilCodeStub LilCodeStub;
VMEXPORT LilCodeStub *vm_get_rt_support_stub(VM_RT_SUPPORT f, Class_Handle c);
Index: trunk/vm/include/open/common.h
===================================================================
--- trunk/vm/include/open/common.h (revision 487512)
+++ trunk/vm/include/open/common.h (working copy)
@@ -14,18 +14,14 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
- * @author Aleksey Ignatenko
- * @version $Revision: 1.1.2.1.4.3 $
- */
// excluding remarks:
#if defined (__INTEL_COMPILER)
-#pragma warning (disable:1684) // conversion from pointer to same-sized integral type (potential portability problem)
-#pragma warning (disable:279) // controlling expression is constant
-#pragma warning (disable:444) // destructor for base class is not virtual
-#pragma warning (disable:981) // operands are evaluated in unspecified order
-#pragma warning (disable:181) // argument is incompatible with corresponding format string conversion (in printf)
+#pragma warning (disable:1684) // conversion from pointer to same-sized integral type (potential portability problem)
+#pragma warning (disable:279) // controlling expression is constant
+#pragma warning (disable:444) // destructor for base class is not virtual
+#pragma warning (disable:981) // operands are evaluated in unspecified order
+#pragma warning (disable:181) // argument is incompatible with corresponding format string conversion (in printf)
#pragma warning (disable:1599) // declaration hides variable "dclazz" (declared at line NN)
#endif // _MSC_VER
@@ -33,7 +29,9 @@
#pragma warning (disable:4800) // forcing value to bool 'true' or 'false' (performance warning)
#endif
-//Warning appears when local variable is defined and not used
+/**
+ * Warning appears when local variable is defined and not used.
+ */
#if defined (__INTEL_COMPILER) && defined(__GNUC__)
#pragma warning (disable:177)
#define UNUSED
@@ -48,7 +46,10 @@
#define UNUSED
#endif // !__GNUC__
-//Warning appears when function parameter is not used in function body
+/**
+ * Warning appears when function parameter is not used in
+ * function body.
+ */
#if defined (__INTEL_COMPILER) && defined(__GNUC__)
#pragma warning (disable:869)
#define UNREF
Index: trunk/vm/include/open/ee_em_intf.h
===================================================================
--- trunk/vm/include/open/ee_em_intf.h (revision 487512)
+++ trunk/vm/include/open/ee_em_intf.h (working copy)
@@ -1,23 +1,20 @@
/*
- * 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
+ * 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
+ * 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.
+ * 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.
*/
-/**
- * @author Mikhail Y. Fursov
- * @version $Revision: 1.1.2.1.4.4 $
- */
+
#ifndef _EE_EM_H_
#define _EE_EM_H_
@@ -44,9 +41,9 @@
* The given method is called only once per JIT instance.
*
* @param[in] jit - the run-time JIT handle used at run-time to refer to
- * the given JIT instance
+ * the given JIT instance
* @param[in] name - the persistent JIT name that the compiler uses to separate
- * its configuration settings from the ones of other JITs
+ * its configuration settings from the ones of other JITs
*/
JITEXPORT void JIT_init(JIT_Handle jit, const char* name);
@@ -86,19 +83,18 @@
* by the role parameter.
* The profile type and the profile collector are defined by the profile
* collector handle.
-
*
* @param[in] jit - the JIT instance
* @param[in] pc - the handle of the profile collector instance
* @param[in] role - the role of JIT in profiling defining whether to collect
- * or to use the profile
+ * or to use the profile
*
* @return TRUE if JIT does profiling of the pc type
- * according the role parameter, FALSE if profiling is not
- * supported.
+ * according to the role parameter; FALSE if
+ * profiling is not supported.
*
* @note The given method is optional. A JIT compiler without profiling
- * support does not need this method.
+ * support does not need this method.
*/
JITEXPORT bool JIT_enable_profiling(JIT_Handle jit, PC_Handle pc, EM_JIT_PC_Role role);
Index: trunk/vm/include/open/hycomp.h
===================================================================
--- trunk/vm/include/open/hycomp.h (revision 487512)
+++ trunk/vm/include/open/hycomp.h (working copy)
@@ -18,36 +18,54 @@
#if !defined(hycomp_h)
#define hycomp_h
-/*
-USE_PROTOTYPES: Use full ANSI prototypes.
-CLOCK_PRIMS: We want the timer/clock prims to be used
-LITTLE_ENDIAN: This is for the intel machines or other
- little endian processors. Defaults to big endian.
-NO_LVALUE_CASTING: This is for compilers that don't like the left side
- of assigns to be cast. It hacks around to do the
- right thing.
-ATOMIC_FLOAT_ACCESS: So that float operations will work.
-LINKED_USER_PRIMITIVES: Indicates that user primitives are statically linked
- with the VM executeable.
-OLD_SPACE_SIZE_DIFF: The 68k uses a different amount of old space.
- This "legitimizes" the change.
-SIMPLE_SIGNAL: For machines that don't use real signals in C.
- (eg: PC, 68k)
-OS_NAME_LOOKUP: Use nlist to lookup user primitive addresses.
-VMCALL: Tag for all functions called by the VM.
-VMAPICALL: Tag for all functions called via the PlatformFunction
- callWith: mechanism.
-
-SYS_FLOAT: For some math functions where extended types (80 or 96 bits) are returned
- Most platforms return as a double
-FLOAT_EXTENDED: If defined, the type name for extended precision floats.
-PLATFORM_IS_ASCII: Must be defined if the platform is ASCII
-EXE_EXTENSION_CHAR: the executable has a delimiter that we want to stop at as part of argv[0].
-*/
-/* By default order doubles in the native (i.e. big/little endian) ordering. */
+/**
+ * USE_PROTOTYPES: Use full ANSI prototypes.
+ *
+ * CLOCK_PRIMS: We want the timer/clock prims to be used
+ *
+ * LITTLE_ENDIAN: This is for the intel machines or other
+ * little endian processors. Defaults to big endian.
+ *
+ * NO_LVALUE_CASTING: This is for compilers that don't like the left side
+ * of assigns to be cast. It hacks around to do the
+ * right thing.
+ *
+ * ATOMIC_FLOAT_ACCESS: So that float operations will work.
+ *
+ * LINKED_USER_PRIMITIVES: Indicates that user primitives are statically linked
+ * with the VM executeable.
+ *
+ * OLD_SPACE_SIZE_DIFF: The 68k uses a different amount of old space.
+ * This "legitimizes" the change.
+ *
+ * SIMPLE_SIGNAL: For machines that don't use real signals in C.
+ * (eg: PC, 68k)
+ *
+ * OS_NAME_LOOKUP: Use nlist to lookup user primitive addresses.
+ *
+ * VMCALL: Tag for all functions called by the VM.
+ *
+ * VMAPICALL: Tag for all functions called via the PlatformFunction
+ * callWith: mechanism.
+ *
+ * SYS_FLOAT: For some math functions where extended types (80 or 96 bits) are returned
+ * Most platforms return as a double
+ *
+ * FLOAT_EXTENDED: If defined, the type name for extended precision floats.
+ *
+ * PLATFORM_IS_ASCII: Must be defined if the platform is ASCII
+ *
+ * EXE_EXTENSION_CHAR: the executable has a delimiter that we want to stop at as part of argv[0].
+ *
+ * By default order doubles in the native (that is big/little endian) ordering.
+ */
+
#define HY_PLATFORM_DOUBLE_ORDER
#if defined(LINUX)
-/* NOTE: Linux supports different processors -- do not assume 386 */
+
+/**
+ * @note Linux supports different processors - do not assume 386.
+ */
#if defined(LINUXPPC64) || defined(POINTER64)
#define DATA_TYPES_DEFINED
typedef unsigned long int UDATA; /* 64bits */
@@ -78,7 +96,9 @@
#define DIR_SEPARATOR '/'
#define DIR_SEPARATOR_STR "/"
-/* no priorities on Linux */
+/**
+ * No priorities on Linux
+ */
#define HY_PRIORITY_MAP {0,0,0,0,0,0,0,0,0,0,0,0}
#if (defined(LINUXPPC) && !defined(LINUXPPC64))
@@ -89,7 +109,9 @@
#define GLOBAL_DATA(symbol) ((void*)&(symbol))
#define GLOBAL_TABLE(symbol) GLOBAL_DATA(symbol)
-/* Win32 - Windows 3.1 & NT using Win32 */
+/**
+ * Win32 - Windows 3.1 & NT using Win32
+ */
#if defined(WIN32)
typedef __int64 I_64;
@@ -104,9 +126,17 @@
#define DIR_SEPARATOR '\\'
#define DIR_SEPARATOR_STR "\\"
-/* Modifications for the Alpha running WIN-NT */
+/**
+ * Modifications for the Alpha running WIN-NT
+ */
+
#if defined(_ALPHA_)
-#undef small /* defined as char in rpcndr.h */
+#undef small
+
+/**
+ * Defined as char in rpcndr.h
+ */
+
typedef double FLOAT_EXTENDED;
#endif
@@ -130,26 +160,39 @@
#define VMAPICALL
#endif
#define PVMCALL VMCALL *
-/* Provide some reasonable defaults for the VM "types":
- UDATA unsigned data, can be used as an integer or pointer storage.
- IDATA signed data, can be used as an integer or pointer storage.
- U_64 / I_64 unsigned/signed 64 bits.
- U_32 / I_32 unsigned/signed 32 bits.
- U_16 / I_16 unsigned/signed 16 bits.
- U_8 / I_8 unsigned/signed 8 bits (bytes -- not to be confused with char)
- BOOLEAN something that can be zero or non-zero.
-*/
+
+/**
+ * Provide some reasonable defaults for the VM types:
+ *
UDATA - unsigned data, can be used as an integer or
+ * pointer storageIDATA - signed data, can be used as an integer or
+ * pointer storageU_64 / I_64 - unsigned/signed 64 bitsU_32 / I_32 - unsigned/signed 32 bitsU_16 / I_16 - unsigned/signed 16 bitsU_8 / I_8 - unsigned/signed 8 bits (bytes -- not to be
+ * confused with char)BOOLEAN - something that can be zero or non-zeroBOOLEAN since it's already def'ed on Win32.
+ */
+
#endif
#ifdef LINUX
#define BOOLEAN UDATA
@@ -160,12 +203,22 @@
#endif
#if !defined(HY_DEFAULT_SCHED)
-/* by default, pthreads platforms use the SCHED_OTHER thread scheduling policy */
+
+/**
+ * By default, pthreads platforms use the SCHED_OTHER thread
+ * scheduling policy.
+ */
+
#define HY_DEFAULT_SCHED SCHED_OTHER
#endif
#if !defined(HY_PRIORITY_MAP)
-/* if no priority map if provided, priorities will be determined algorithmically */
+
+/**
+ * If no priority map if provided, priorities will be determined
+ * algorithmically.
+ */
+
#endif
#if !defined(FALSE)
@@ -190,17 +243,29 @@
#define PROTOTYPE(x) ()
#define VARARGS
#endif
-/* Assign the default line delimiter if it was not set */
+
+/**
+ * Assign the default line delimiter, if it was not set.
+ */
+
#if !defined(PLATFORM_LINE_DELIMITER)
#define PLATFORM_LINE_DELIMITER "\015\012"
#endif
-/* Set the max path length if it was not set */
+
+/**
+ * Set the max path length, if it was not set.
+ */
+
#if !defined(MAX_IMAGE_PATH_LENGTH)
#define MAX_IMAGE_PATH_LENGTH (2048)
#endif
typedef double ESDOUBLE;
typedef float ESSINGLE;
-/* helpers for U_64s */
+
+/**
+ * Helpers for U_64s.
+ */
+
#define CLEAR_U64(u64) (u64 = (U_64)0)
#define LOW_LONG(l) (*((U_32 *) &(l)))
#define HIGH_LONG(l) (*(((U_32 *) &(l)) + 1))
@@ -220,7 +285,11 @@
#define CLASSP(x) ((Class *) (x))
#define CLASSPP(x) ((Class **) (x))
#define BYTEP(x) ((BYTE *) (x))
-/* Test - was conflicting with OS2.h */
+
+/**
+ * Test - was conflicting with OS2.h
+ */
+
#define ESCHAR(x) ((CHARACTER) (x))
#define FLT(x) ((FLOAT) x)
#define FLTP(x) ((FLOAT *) (x))
@@ -262,7 +331,11 @@
#define LFLT(x) FLT((x))
#define LFLTP(x) FLTP((x))
#endif
-/* Macros for converting between words and longs and accessing bits */
+
+/**
+ * Macros for converting between words and longs and accessing bits.
+ */
+
#define HIGH_WORD(x) U16(U32((x)) >> 16)
#define LOW_WORD(x) U16(U32((x)) & 0xFFFF)
#define LOW_BIT(o) (U32((o)) & 1)
@@ -278,24 +351,39 @@
#define HY_CFUNC
#define HY_CDATA
#endif
-/* Macros for tagging functions which read/write the vm thread */
+
+/**
+ * Macros for tagging functions which read/write the vm thread.
+ */
+
#define READSVMTHREAD
#define WRITESVMTHREAD
#define REQUIRESSTACKFRAME
-/* macro for tagging functions which never return */
+
+/**
+ * Macro for tagging functions, which never return.
+ */
+
#if defined(__GNUC__)
-/* on GCC, we can actually pass this information on to the compiler */
+
+/**
+ * On GCC, we can actually pass this information on to the compiler.
+ */
+
#define NORETURN __attribute__((noreturn))
#else
#define NORETURN
#endif
-/* on some systems va_list is an array type. This is probably in
- * violation of the ANSI C spec, but it's not entirely clear. Because of this, we end
- * up with an undesired extra level of indirection if we take the address of a
- * va_list argument.
+
+/**
+ * On some systems va_list is an array type. This is probably in
+ * violation of the ANSI C spec, but it's not entirely clear. Because of this,
+ * we end up with an undesired extra level of indirection if we take the address
+ * of a va_list argument.
*
- * To get it right ,always use the VA_PTR macro
+ * To get it right, always use the VA_PTR macro.
*/
+
#if !defined(VA_PTR)
#define VA_PTR(valist) (&valist)
#endif
@@ -306,7 +394,11 @@
#if !defined(TOC_STORE_TOC)
#define TOC_STORE_TOC(dest,wrappedPointer)
#endif
-/* Macros for accessing I_64 values */
+
+/**
+ * Macros for accessing I_64 values.
+ */
+
#if defined(ATOMIC_LONG_ACCESS)
#define PTR_LONG_STORE(dstPtr, aLongPtr) ((*U32P(dstPtr) = *U32P(aLongPtr)), (*(U32P(dstPtr)+1) = *(U32P(aLongPtr)+1)))
#define PTR_LONG_VALUE(dstPtr, aLongPtr) ((*U32P(aLongPtr) = *U32P(dstPtr)), (*(U32P(aLongPtr)+1) = *(U32P(dstPtr)+1)))
@@ -314,11 +406,19 @@
#define PTR_LONG_STORE(dstPtr, aLongPtr) (*(dstPtr) = *(aLongPtr))
#define PTR_LONG_VALUE(dstPtr, aLongPtr) (*(aLongPtr) = *(dstPtr))
#endif
-/* Macro used when declaring tables which require relocations.*/
+
+/**
+ * Macro used when declaring tables which require relocations.
+ */
+
#if !defined(HYCONST_TABLE)
#define HYCONST_TABLE const
#endif
-/* ANSI qsort is not always available */
+
+/**
+ * ANSI qsort is not always available.
+ */
+
#if !defined(HY_SORT)
#define HY_SORT(base, nmemb, size, compare) qsort((base), (nmemb), (size), (compare))
#endif
Index: trunk/vm/include/open/vm.h
===================================================================
--- trunk/vm/include/open/vm.h (revision 487512)
+++ trunk/vm/include/open/vm.h (working copy)
@@ -1,6 +1,6 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
+ * 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
@@ -14,17 +14,12 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
/**
- * @author Intel, Alexei Fedotov
- * @version $Revision: 1.1.2.2.4.3 $
+ * These are the functions that a VM built as a DLL must export.
+ * Some functions may be optional and are marked as such.
*/
-
-//
-// These are the functions that a VM built as a DLL must export.
-// Some functions may be optional and are marked as such.
-//
-
#ifndef _VM_EXPORT_H
#define _VM_EXPORT_H
@@ -40,8 +35,10 @@
extern "C" {
#endif
-// This structure is meant to be opaque. External modules should not
-// attempt to directly access any of its fields.
+/**
+ * This structure is meant to be opaque. External modules should not.
+ */
+ attempt to directly access any of its fields.
typedef struct ChaClassIterator {
Class_Handle _root_class;
Class_Handle _current;
@@ -49,8 +46,10 @@
} ChaClassIterator;
-// This structure is meant to be opaque. External modules should not
-// attempt to directly access any of its fields.
+/**
+ * This structure is meant to be opaque. External modules should not.
+ */
+ attempt to directly access any of its fields.
typedef struct ChaMethodIterator {
Method_Handle _method;
Method_Handle _current;
@@ -58,629 +57,919 @@
} ChaMethodIterator;
-/////////////////////////////////////////////////////////////////
-// begin class-related functions.
+/**
+ * Begin class-related functions.
+ */
-
-// Returns a handle for the object class. For Java applications, it's
-// java.lang.Object.
+/**
+ * @return A handle for the Object class. For Java applications, it's
+ * java.lang.Object.
+ */
VMEXPORT Class_Handle get_system_object_class();
-// Returns a handle for the class class. For Java applications, it's
-// java.lang.Class.
+/**
+ * @return A handle for the Class class. For Java applications, it's
+ * java.lang.Class.
+ */
VMEXPORT Class_Handle get_system_class_class();
-// Returns a handle for the string class. For Java applications, it's
-// java.lang.String.
+/**
+ * @return A handle for the string class. For Java applications, it's
+ * java.lang.String.
+ */
+
VMEXPORT Class_Handle get_system_string_class();
-// Loads a class of a given name. If a class cannot be loaded, returns NULL
+/**
+ * Loads a class of a given name.
+ *
+ * @return NULL if a class cannot be loaded.
+ */
+
VMEXPORT Class_Handle
class_load_class_by_name_using_bootstrap_class_loader(const char *name);
-// The following three functions will be eventually renamed to
-// class_is_final, class_is_abstract and class_is_interface,
-// but right now that would conflict with the names of some internal macros.
+/**
+ * The following three functions will be eventually renamed to
+ * \arg class_is_final
+ * \arg class_is_abstract
+ * \arg class_is_interface
+ * but right now that would conflict
+ * with the names of some internal macros.
+ */
+
VMEXPORT Boolean class_property_is_final(Class_Handle ch);
VMEXPORT Boolean class_property_is_abstract(Class_Handle ch);
VMEXPORT Boolean class_property_is_interface2(Class_Handle ch);
-// Returns TRUE if th class is likely to be used as an exception object.
-// This is a hint only. If the result is FALSE, the class may still
-// be used for exceptions but it is less likely.
+/**
+ * @return TRUE if the class is likely to be used as an exception object.
+ * This is a hint only. If the result is FALSE, the class may still
+ * be used for exceptions but it is less likely.
+ */
VMEXPORT Boolean class_hint_is_exceptiontype(Class_Handle ch);
-// Returns TRUE if the class is a value type.
-VMEXPORT Boolean class_is_valuetype(Class_Handle ch);
+/**
+ * @return TRUE if the class is a value type.
+ */
+ VMEXPORT Boolean class_is_valuetype(Class_Handle ch);
-// Return TRUE if the class represents an enum. For Java 1.4 always returns FALSE.
+/**
+ * @return TRUE if the class represents an enum.
+ * For Java 1.4 always returns FALSE.
+ */
VMEXPORT Boolean class_is_enum(Class_Handle ch);
-// This function can only be called if (class_is_enum(ch) == TRUE)
-// The returned value is the type of the underlying int type.
+/**
+ * This function can only be called if (class_is_enum(ch) == TRUE)
+ * The returned value is the type of the underlying int type.
+ */
VMEXPORT VM_Data_Type class_get_enum_int_type(Class_Handle ch);
-// Returns TRUE if the class represents a primitive type (int, float, etc.)
-VMEXPORT Boolean class_is_primitive(Class_Handle ch);
+/**
+ * @return TRUE if the class represents a primitive type (int, float, etc.)
+ */
+ VMEXPORT Boolean class_is_primitive(Class_Handle ch);
-// Returns the name of the class.
-VMEXPORT const char *class_get_name(Class_Handle ch);
+/**
+ * @return The name of the class.
+ */
+ VMEXPORT const char *class_get_name(Class_Handle ch);
-// Returns the name of the package containing the class.
-VMEXPORT const char *class_get_package_name(Class_Handle ch);
+/**
+ * @return The name of the package containing the class.
+ */
+ VMEXPORT const char *class_get_package_name(Class_Handle ch);
-// Returns the super class of the current class.
-// Returns NULL for the system object class, i.e.
-// class_get_super_class(get_system_object_class()) == NULL
+/**
+ * The super class of the current class.
+ * @return NULL for the system object class, i.e.
+ * class_get_super_class(get_system_object_class()) == NULL
+ */
VMEXPORT Class_Handle class_get_super_class(Class_Handle ch);
-// Return the vtable handle of the given class.
-VMEXPORT VTable_Handle class_get_vtable(Class_Handle ch);
+/**
+ * @return The vtable handle of the given class.
+ */
+ VMEXPORT VTable_Handle class_get_vtable(Class_Handle ch);
-// Returns the allocation handle to be used for the object allocation
-// routines, given a class handle.
+/**
+ * @return The allocation handle to be used for the object allocation
+ * routines, given a class handle.
+ */
VMEXPORT Allocation_Handle class_get_allocation_handle(Class_Handle ch);
-// Returns the class handle corresponding to a given allocation handle.
+/**
+ * @return The class handle corresponding to a given allocation handle.
+ */
VMEXPORT Class_Handle allocation_handle_get_class(Allocation_Handle ah);
-// Return an VM_Data_Type value for a given class.
-VMEXPORT VM_Data_Type class_get_primitive_type_of_class(Class_Handle ch);
+/**
+ * @return An VM_Data_Type value for a given class.
+ */
+ VMEXPORT VM_Data_Type class_get_primitive_type_of_class(Class_Handle ch);
-// Return a class corresponding to a primitive type. For all primitive types t
-// t == class_get_primitive_type_of_class(class_get_class_of_primitive_type(t))
-VMEXPORT Class_Handle class_get_class_of_primitive_type(VM_Data_Type typ);
+/**
+ * @return A class corresponding to a primitive type. For all primitive types t
+ * t == class_get_primitive_type_of_class(class_get_class_of_primitive_type(t))
+ */
+ VMEXPORT Class_Handle class_get_class_of_primitive_type(VM_Data_Type typ);
-// Returns TRUE is the class is an array.
+/**
+ * @return TRUE is the class is an array.
+ */
VMEXPORT Boolean class_is_array(Class_Handle ch);
-// Returns TRUE if class s is assignment compatible with class t.
+/**
+ * @return TRUE if class s is assignment
+ * compatible with class t.
+ */
VMEXPORT Boolean class_is_instanceof(Class_Handle s, Class_Handle t);
-// Given a class handle cl construct a class handle of the type
-// representing array of cl. If class cl is value type, assume
-// that the element is a reference to a boxed instance of that type.
-VMEXPORT Class_Handle class_get_array_of_class(Class_Handle ch);
+/**
+ * Given a class handle cl construct a class handle of the type
+ * representing array of cl. If class cl is value type, assume
+ * that the element is a reference to a boxed instance of that type.
+ */
+ VMEXPORT Class_Handle class_get_array_of_class(Class_Handle ch);
-// Given a class handle cl construct a class handle of the type
-// representing array of cl. Class cl is assumed to be a
-// value type. Return NULL if cl is not a value type.
-VMEXPORT Class_Handle class_get_array_of_unboxed(Class_Handle ch);
+/**
+ * Given a class handle cl construct a class handle of the type
+ * representing array of cl. Class cl is assumed to be a
+ * value type.
+ *
+ * @return NULL if cl is not a value type.
+ */
+ VMEXPORT Class_Handle class_get_array_of_unboxed(Class_Handle ch);
-// For a class that is an array return the type info for the elements
-// of the array
-VMEXPORT Type_Info_Handle class_get_element_type_info(Class_Handle ch);
+/**
+ * @return For a class that is an array return the type info for the elements
+ * of the array.
+ */
+ VMEXPORT Type_Info_Handle class_get_element_type_info(Class_Handle ch);
-// Returns TRUE if the class is already fully initialized.
-VMEXPORT Boolean class_is_initialized(Class_Handle ch);
+ /**
+ * @return TRUE if the class is already fully initialized.
+ */
+ VMEXPORT Boolean class_is_initialized(Class_Handle ch);
-// Returns TRUE if the class is neither initialized nor in the process
-// of being initialized. The intention is that the JIT will emit a call
-// to VM_RT_INITIALIZE_CLASS before every access to a static field in
-// Java.
-VMEXPORT Boolean class_needs_initialization(Class_Handle ch);
+/**
+ * @return TRUE if the class is neither initialized nor in the process
+ * of being initialized. The intention is that the JIT will emit a call
+ * to VM_RT_INITIALIZE_CLASS before every access to a static
+ * field in Java.
+ */
+ VMEXPORT Boolean class_needs_initialization(Class_Handle ch);
-// For Java returns FALSE.
-VMEXPORT Boolean class_is_before_field_init(Class_Handle ch);
+/**
+ * For Java returns FALSE.
+ */
+ VMEXPORT Boolean class_is_before_field_init(Class_Handle ch);
-// Number of instance fields defined in a class. That doesn't include
-// inherited fields.
-VMEXPORT unsigned class_num_instance_fields(Class_Handle ch);
+/**
+ * Number of instance fields defined in a class. That doesn't include
+ * inherited fields.
+ */
+ VMEXPORT unsigned class_num_instance_fields(Class_Handle ch);
-// Get the handle for a field. If idx is greater than or equal to
-// class_num_instance_fields, return NULL.
-// The value of idx indexes into the fields defined in this class and
-// doesn't include inherited fields.
-VMEXPORT Field_Handle class_get_instance_field(Class_Handle ch, unsigned idx);
+/**
+ * Get the handle for a field. If idx is greater than or equal to
+ * class_num_instance_fields.
+ *
+ * @return NULL
+ *
+ * The value of idx indexes into the fields defined in this class and
+ * doesn't include inherited fields.
+ */
+ VMEXPORT Field_Handle class_get_instance_field(Class_Handle ch, unsigned idx);
-// Number of instance fields defined in a class. This number includes
-// inherited fields.
+/**
+ * Number of instance fields defined in a class. This number includes
+ * inherited fields.
+ */
+
VMEXPORT unsigned class_num_instance_fields_recursive(Class_Handle ch);
-
-// Get the handle for a field. If idx is greater than or equal to
-// class_num_instance_fields_recursive, return NULL.
-// The value of idx indexes into the set of fields that includes both fields
-// defined in this class and inherited fields.
+/**
+ * Get the handle for a field.
+ *
+ * @return NULL if idx is greater than or equal to
+ * class_num_instance_fields_recursive.
+ *
+ * The value of idx indexes into the set of fields that includes both fields
+ * defined in this class and inherited fields.
+ */
VMEXPORT Field_Handle class_get_instance_field_recursive(Class_Handle ch, unsigned idx);
-// Number of methods declared in the class
-VMEXPORT unsigned class_get_number_methods(Class_Handle ch);
+/**
+ * Number of methods declared in the class.
+ */
+ VMEXPORT unsigned class_get_number_methods(Class_Handle ch);
-// Get handle for a method declared in class
-VMEXPORT Method_Handle class_get_method(Class_Handle ch, unsigned index);
+/**
+ * Get handle for a method declared in class.
+ */
+ VMEXPORT Method_Handle class_get_method(Class_Handle ch, unsigned index);
+/**
+ * @return TRUE if all instances of this class are pinned.
+ */
+ VMEXPORT Boolean class_is_pinned(Class_Handle ch);
-// Returns TRUE if all instances of this class are pinned.
-VMEXPORT Boolean class_is_pinned(Class_Handle ch);
+/**
+ * @return TRUE if all instances of this class are pinned.
+ */
+ VMEXPORT void* class_alloc_via_classloader(Class_Handle ch, int32 size);
-// Returns TRUE if all instances of this class are pinned.
-VMEXPORT void* class_alloc_via_classloader(Class_Handle ch, int32 size);
+/**
+ * @return TRUE if this is an array of primitives.
+ */
+ VMEXPORT Boolean class_is_non_ref_array(Class_Handle ch);
-// Returns TRUE if this is an array of primitives.
-VMEXPORT Boolean class_is_non_ref_array(Class_Handle ch);
+/**
+ * @return TRUE if the class has a non-trivial finalizer.
+ */
+ VMEXPORT Boolean class_is_finalizable(Class_Handle ch);
-// Returns TRUE if the class has a non-trivial finalizer.
-VMEXPORT Boolean class_is_finalizable(Class_Handle ch);
-// This exactly what I want.
-// Get the alignment of the class.
-VMEXPORT unsigned class_get_alignment(Class_Handle ch);
+/**
+ * This exactly what I want.
+ * Get the alignment of the class.
+ */
+ VMEXPORT unsigned class_get_alignment(Class_Handle ch);
-// Get the alignment of the class when it's unboxed.
-VMEXPORT unsigned class_get_alignment_unboxed(Class_Handle ch);
+/**
+ * Get the alignment of the class when it's unboxed.
+ */
+ VMEXPORT unsigned class_get_alignment_unboxed(Class_Handle ch);
-// For a class handle that represents and array, return the size of the
-// element of the array.
-VMEXPORT unsigned class_element_size(Class_Handle ch);
+/**
+ * @return For a class handle that represents and array, return the size of the
+ * element of the array.
+ */
+ VMEXPORT unsigned class_element_size(Class_Handle ch);
-// Return the size in bytes of an instance in the heap.
-VMEXPORT unsigned class_get_boxed_data_size(Class_Handle ch);
+/**
+ * @return The size in bytes of an instance in the heap.
+ */
+ VMEXPORT unsigned class_get_boxed_data_size(Class_Handle ch);
-// Return the offset to the start of user data form the start of a boxed
-// instance.
-VMEXPORT unsigned class_get_unboxed_data_offset(Class_Handle ch);
+/**
+ * @return The offset to the start of user data form the start of a boxed
+ * instance.
+ */
+ VMEXPORT unsigned class_get_unboxed_data_offset(Class_Handle ch);
-// Return the class of the array element of the given class.
-// The behavior is undefined if the parameter does not represent
-// an array class.
-VMEXPORT Class_Handle class_get_array_element_class(Class_Handle ch);
+/**
+ * @return The class of the array element of the given class.
+ *
+ * The behavior is undefined if the parameter does not represent
+ * an array class.
+ */
+ VMEXPORT Class_Handle class_get_array_element_class(Class_Handle ch);
-// Returns the offset from the start of the vtable at which the
-// superclass hierarchy is stored. This is for use with fast type
-// checking.
-VMEXPORT int vtable_get_super_array_offset();
+/**
+ * @return The offset from the start of the vtable at which the
+ * superclass hierarchy is stored. This is for use with fast type
+ * checking.
+ */
+ VMEXPORT int vtable_get_super_array_offset();
-// Returns class handle given object's VTable_Handle.
-VMEXPORT Class_Handle vtable_get_class(VTable_Handle vh);
+/**
+ * @return Class handle given object's VTable_Handle.
+ */
+ VMEXPORT Class_Handle vtable_get_class(VTable_Handle vh);
-// Returns the number of superclass hierarchy elements that are
-// stored within the vtable. This is for use with fast type checking.
-VMEXPORT int vm_max_fast_instanceof_depth();
+/**
+ * @return The number of superclass hierarchy elements that are
+ * stored within the vtable. This is for use with fast type checking.
+ */
+ VMEXPORT int vm_max_fast_instanceof_depth();
-/////////////////////////////////////////////////////////////////
+////
// begin class iterator related functions.
+////
-// Initializes the CHA_Class_Iterator, to iterate over all classes that
-// descend from root_class, including root_class itself.
-// Returns TRUE if iteration is supported over root_class, FALSE if not.
-VMEXPORT Boolean class_iterator_initialize(ChaClassIterator*, Class_Handle root_class);
+/**
+ * Initializes the CHA_Class_Iterator, to iterate over all
+ * classes that descend from root_class, including
+ * root_class itself.
+ *
+ * @return TRUE if iteration is supported over
+ * root_class, FALSE if not.
+ */
+ VMEXPORT Boolean class_iterator_initialize(ChaClassIterator*, Class_Handle root_class);
-// Returns the current class of the iterator. NULL is returned if
-// therea are no more classes.
-VMEXPORT Class_Handle class_iterator_get_current(ChaClassIterator*);
+/**
+ * @return The current class of the iterator. NULL if
+ * there are no more classes.
+ */
+ VMEXPORT Class_Handle class_iterator_get_current(ChaClassIterator*);
-// Advances the iterator.
-VMEXPORT void class_iterator_advance(ChaClassIterator*);
+/**
+ * Advances the iterator.
+ */
+ VMEXPORT void class_iterator_advance(ChaClassIterator*);
-
-/////////////////////////////////////////////////////////////////
+////
// begin inner-class related functions.
+///
-// Returns TRUE the number of inner classes
-VMEXPORT unsigned class_number_inner_classes(Class_Handle ch);
+/**
+ * @return TRUE the number of inner classes.
+ */
+ VMEXPORT unsigned class_number_inner_classes(Class_Handle ch);
-// Returns TRUE if an inner class is public
-VMEXPORT Boolean class_is_inner_class_public(Class_Handle ch, unsigned idx);
+/**
+ * @return TRUE if an inner class is public.
+ */
+ VMEXPORT Boolean class_is_inner_class_public(Class_Handle ch, unsigned idx);
-// Return an inner class
-VMEXPORT Class_Handle class_get_inner_class(Class_Handle ch, unsigned idx);
+/**
+ * @return an inner class
+ */
+ VMEXPORT Class_Handle class_get_inner_class(Class_Handle ch, unsigned idx);
-// Return the class that declared this one, or NULL if top-level class
-VMEXPORT Class_Handle class_get_declaring_class(Class_Handle ch);
+/**
+ * @return the class that declared this one, or NULL if top-level class
+ */
+ VMEXPORT Class_Handle class_get_declaring_class(Class_Handle ch);
-// end inner-class related functions.
-/////////////////////////////////////////////////////////////////
+///
+// end class-related functions.
+///
-
+////
// end class-related functions.
-/////////////////////////////////////////////////////////////////
+////
-
-
-/////////////////////////////////////////////////////////////////
+////
// begin field-related functions.
+////
+/**
+ * @return TRUE is the field is static.
+ */
+ VMEXPORT Boolean field_is_static(Field_Handle fh);
-// Returns TRUE is the field is static.
-VMEXPORT Boolean field_is_static(Field_Handle fh);
+/**
+ * @return The type info that represents the type of the field.
+ */
+ VMEXPORT Type_Info_Handle field_get_type_info_of_field_value(Field_Handle fh);
-// Returns the type info that represents the type of the field.
-VMEXPORT Type_Info_Handle field_get_type_info_of_field_value(Field_Handle fh);
+/**
+ * @return The class that represents the type of the field.
+ */
+ VMEXPORT Class_Handle field_get_class_of_field_value(Field_Handle fh);
-// Returns the class that represents the type of the field.
-VMEXPORT Class_Handle field_get_class_of_field_value(Field_Handle fh);
+/**
+ * @return The class that defined that field.
+ */
+ VMEXPORT Class_Handle field_get_class(Field_Handle fh);
-// Returns the class that defined that field.
-VMEXPORT Class_Handle field_get_class(Field_Handle fh);
+/**
+ * @return TRUE if the field is of a reference type.
+ *
+ * This function doesn't cause resolution of the class of the field.
+ */
+ VMEXPORT Boolean field_is_reference(Field_Handle fh);
-// Returns TRUE if the field is of a reference type.
-// This function doesn't cause resolution of the class of the field.
-VMEXPORT Boolean field_is_reference(Field_Handle fh);
+/**
+ * @return TRUE if the field is literal. In Java, it means that the
+ * field had the ConstantValue attribute set (JVMS2, Section 4.7.2).
+ */
+ VMEXPORT Boolean field_is_literal(Field_Handle fh);
-// Returns TRUE if the field is literal. In Java, it means that the
-// field had the ConstantValue attribute set (JVMS2, Section 4.7.2).
-VMEXPORT Boolean field_is_literal(Field_Handle fh);
+/**
+ * For Java always FALSE.
+ */
+ VMEXPORT Boolean field_is_unmanaged_static(Field_Handle fh);
-// For Java always FALSE.
-VMEXPORT Boolean field_is_unmanaged_static(Field_Handle fh);
+/**
+ * @return The offset to an instance field.
+ */
+ VMEXPORT unsigned field_get_offset(Field_Handle fh);
-// Returns the offset to an instance field.
-VMEXPORT unsigned field_get_offset(Field_Handle fh);
+/**
+ * @return An address of a static field.
+ */
+ VMEXPORT void *field_get_address(Field_Handle fh);
-// Returns an address of a static field.
-VMEXPORT void *field_get_address(Field_Handle fh);
+/**
+ * @return A name of the field.
+ */
+ VMEXPORT const char *field_get_name(Field_Handle fh);
-// Returns a name of the field.
-VMEXPORT const char *field_get_name(Field_Handle fh);
+/**
+ * @return The field descriptor. The descriptor is a string representation
+ * of the field types as defined by the JVM spec.
+ */
+ VMEXPORT const char *field_get_descriptor(Field_Handle fh);
-// Returns the field descriptor. The descriptor is a string representation
-// of the field types as defined by the
-// JVM spec.
-VMEXPORT const char *field_get_descriptor(Field_Handle fh);
+/**
+ * @return TRUE if the field is final.
+ */
+ VMEXPORT Boolean field_is_final(Field_Handle fh);
-// Returns TRUE if the field is final.
-VMEXPORT Boolean field_is_final(Field_Handle fh);
+/**
+ * @return TRUE if the field is volatile.
+ */
+ VMEXPORT Boolean field_is_volatile(Field_Handle fh);
-// Returns TRUE if the field is volatile.
-VMEXPORT Boolean field_is_volatile(Field_Handle fh);
+/**
+ * @return TRUE if the field is private.
+ */
+ VMEXPORT Boolean field_is_private(Field_Handle fh);
-// Returns TRUE if the field is private.
-VMEXPORT Boolean field_is_private(Field_Handle fh);
-
/**
- * Returns the address and bit mask, for the flag which determine whether field
- * access event should be sent. JIT may use the following expression to
- * determine if specified field access should be tracked:
- * ( **address & *mask != 0 )
- * @param field - handle of the field
- * @param[out] address - pointer to the address of the byte which contains the flag
- * @param[out] mask - pointer to the bit mask of the flag
+ * @return The address and bit mask, for the flag which determine whether field
+ * access event should be sent. JIT may use the following expression to
+ * determine if specified field access should be tracked:
+ * ( **address & *mask != 0 )
+ *
+ * @param field - handle of the field
+ * @param[out] address - pointer to the address of the byte which contains the flag
+ * @param[out] mask - pointer to the bit mask of the flag
*/
VMEXPORT void
field_get_track_access_flag(Field_Handle field, char** address, char* mask);
/**
- * Returns the address and bit mask, for the flag which determine whether field
- * modification event should be sent. JIT may use the following expression to
- * determine if specified field modification should be tracked:
- * ( **address & *mask != 0 )
- * @param field - handle of the field
- * @param[out] address - pointer to the address of the byte which contains the flag
- * @param[out] mask - pointer to the bit mask of the flag
+ * @return the address and bit mask, for the flag which determine whether field
+ * modification event should be sent. JIT may use the following expression to
+ * determine if specified field modification should be tracked:
+ * ( **address & *mask != 0 )
+ *
+ * @param field - handle of the field
+ * @param[out] address - pointer to the address of the byte which contains the flag
+ * @param[out] mask - pointer to the bit mask of the flag
*/
VMEXPORT void
field_get_track_modification_flag(Field_Handle field, char** address,
char* mask);
-
+////
// end field-related functions.
-/////////////////////////////////////////////////////////////////
+////
-
-
-/////////////////////////////////////////////////////////////////
+////
// begin method-related functions.
+////
-
-// Returns TRUE if this a Java method. Every Java JIT must call this
-// function before compiling a method and return JIT_FAILURE if
-// method_is_java returned FALSE.
+/**
+ * @return TRUE if this a Java method. Every Java JIT must call this
+ * function before compiling a method and return JIT_FAILURE if
+ * method_is_java returned FALSE.
+ */
VMEXPORT Boolean method_is_java(Method_Handle mh);
-// Returns the method name.
+/**
+ * @return The method name.
+ */
VMEXPORT const char *method_get_name(Method_Handle mh);
-// Returns the method descriptor. The descriptor is a string representation
-// of the parameter and return value types as defined by the
-// JVM spec.
+/**
+ * @return The method descriptor. The descriptor is a string representation
+ * of the parameter and return value types as defined by the JVM spec.
+ */
VMEXPORT const char *method_get_descriptor(Method_Handle mh);
-// Returns a class in which the method is declared.
+/**
+ * @return A class in which the method is declared.
+ */
VMEXPORT Class_Handle method_get_class(Method_Handle mh);
-// Returns TRUE if the method is private.
+/**
+ * @return TRUE if the method is private.
+ */
VMEXPORT Boolean method_is_private(Method_Handle mh);
-// Returns TRUE if the method is static.
+/**
+ * @return TRUE if the method is static.
+ */
VMEXPORT Boolean method_is_static(Method_Handle mh);
-// Returns TRUE if the method is final.
+/**
+ * @return TRUE if the method is final.
+ */
VMEXPORT Boolean method_is_final(Method_Handle mh);
-// Returns TRUE if the method is native.
+/**
+ * @return TRUE if the method is native.
+ */
VMEXPORT Boolean method_is_native(Method_Handle mh);
-// Returns TRUE if the method is synchronized.
+/**
+ * @return TRUE if the method is synchronized.
+ */
VMEXPORT Boolean method_is_synchronized(Method_Handle mh);
-// Returns TRUE if the method is abstract.
+/**
+ * @return TRUE if the method is abstract.
+ */
VMEXPORT Boolean method_is_abstract(Method_Handle mh);
-// Java methods may have a flag set to indicate that floating point operations
-// must be performed in the strict mode. method_is_strict() returns TRUE is
-// the ACC_STRICT flag is set for a Java method and FALSE otherwise.
+/**
+ * Java methods may have a flag set to indicate that floating point operations
+ * must be performed in the strict mode.
+ *
+ * @return method_is_strict() returns TRUE if
+ * the ACC_STRICT flag is set for a Java method and FALSE otherwise.
+ */
VMEXPORT Boolean method_is_strict(Method_Handle m);
-// Returns TRUE if the method has been overriden in a subclass and FALSE
-// otherwise. Note that if method_is_overridden returns FALSE, loading
-// of a subclass later in the execution of the program may change invalidate
-// this condition. If a JIT uses method_is_overridden to implement
-// unconditional inlining, it must be prepared to patch the code later
-// (see vm_register_jit_overridden_method_callback).
+/**
+ * @return TRUE if the method has been overriden in a subclass
+ * and FALSE otherwise.
+ *
+ * @note If method_is_overridden returns FALSE, loading
+ * of a subclass later in the execution of the program may change
+ * invalidate this condition. If a JIT uses method_is_overridden
+ * to implement unconditional inlining, it must be prepared to patch the code later
+ * (see vm_register_jit_overridden_method_callback).
+ */
VMEXPORT Boolean method_is_overridden(Method_Handle m);
-// Returns TRUE if the method should not be inlined. There may also
-// be other reasons why a method shouldn't be inlined, e.g., native methods
-// can't be inlined and in Java you can't inlined methods that are
-// loaded by a different class loader than the caller.
-// Always FALSE for Java.
+/**
+ * @return TRUE if the method should not be inlined. There may also
+ * be other reasons why a method shouldn't be inlined, e.g., native methods
+ * can't be inlined and in Java you can't inlined methods that are
+ * loaded by a different class loader than the caller.
+ * Always FALSE for Java.
+ */
VMEXPORT Boolean method_is_no_inlining(Method_Handle mh);
-// Always FALSE for Java.
+/**
+ * Always FALSE for Java.
+ */
VMEXPORT Boolean method_is_require_security_object(Method_Handle mh);
-// Return a signature that can be used to iterate over method's arguments
-// and query the type of the method result.
+/**
+ * @return A signature that can be used to iterate over method's arguments
+ * and query the type of the method result.
+ */
VMEXPORT Method_Signature_Handle method_get_signature(Method_Handle mh);
-// Class ch is a subclass of method_get_class(mh). The function returns a method handle
-// for an accessible method overriding mh in ch or in its closest superclass that overrides mh.
-// Class ch must be a class not an interface.
+/**
+ * Class ch is a subclass of method_get_class(mh).
+ * The function returns a method handle for an accessible method overriding
+ * mh in ch or in its closest superclass that overrides
+ * mh.
+ * Class ch must be a class not an interface.
+ */
VMEXPORT Method_Handle method_find_overridden_method(Class_Handle ch, Method_Handle mh);
-
-/////////////////////////////////////////////////////////////////
+////
// begin method iterator related functions.
+///
-// Initializes the CHA_Method_Iterator, to iterate over all methods that
-// match the method signature and descend from root_class (including root_class itself).
-// Returns TRUE if iteration is supported over root_class, FALSE if not.
+/**
+ * Initializes the CHA_Method_Iterator, to iterate over all methods that
+ * match the method signature and descend from root_class
+ * (including root_class itself).
+ *
+ * @return TRUE if iteration is supported over root_class,
+ * FALSE if not.
+ */
VMEXPORT Boolean method_iterator_initialize(ChaMethodIterator*, Method_Handle method, Class_Handle root_class);
-// Returns the current method of the iterator. NULL is returned if
-// therea are no more methods.
+/**
+ * @return The current method of the iterator. NULL is returned if
+ * therea are no more methods.
+ */
VMEXPORT Method_Handle method_iterator_get_current(ChaMethodIterator*);
-// Advances the iterator.
+/**
+ * Advances the iterator.
+ */
VMEXPORT void method_iterator_advance(ChaMethodIterator*);
-
-///////////////////////////////////////////////////////
+////
// begin method signature-related functions.
+////
-// Returns the method descriptor for a given method signature.
-// See method_get_descriptor().
+/**
+ * @return The method descriptor for a given method signature.
+ * See method_get_descriptor().
+ */
VMEXPORT const char *method_sig_get_descriptor(Method_Signature_Handle s);
-// Return a signature that can be used to iterate over method's arguments
-// and query the type of the method result.
-// Java doesn't have standalone signatures, so for Java, always return NULL.
+/**
+ * Return a signature that can be used to iterate over method's arguments
+ * and query the type of the method result.
+ * Java doesn't have standalone signatures, so for Java, always return NULL.
+ */
VMEXPORT Method_Signature_Handle method_standalone_signature(Class_Handle ch,
unsigned idx);
+////
// end method signature-related functions.
-///////////////////////////////////////////////////////
+////
-
-///////////////////////////////////////////////////////
+////
// begin local variables-related functions.
+///
-// Returns the number of local variables defined for the method.
+/**
+ * @return the number of local variables defined for the method.
+ */
VMEXPORT unsigned method_vars_get_number(Method_Handle mh);
-// Return the type info of the local variable number idx.
-// Since local variables are not typed in Java. this function
-// always returns NULL for Java methods.
+/**
+ * Return the type info of the local variable number idx.
+ * Since local variables are not typed in Java. this function
+ * always returns NULL for Java methods.
+ */
VMEXPORT Type_Info_Handle method_vars_get_type_info(Method_Handle mh,
unsigned idx);
-
-// Returns TRUE if the local variable is a managed pointer.
+/**
+ * @return TRUE if the local variable is a managed pointer.
+ */
VMEXPORT Boolean method_vars_is_managed_pointer(Method_Handle mh, unsigned idx);
-// Returns TRUE if the local variable is pinned.
+/**
+ * @return TRUE if the local variable is pinned.
+ */
VMEXPORT Boolean method_vars_is_pinned(Method_Handle mh, unsigned idx);
-// end local variables-related functions.
-///////////////////////////////////////////////////////
+/**
+ * end local variables-related functions.
+ */
+/**
+ * begin argument-related functions.
+ */
-///////////////////////////////////////////////////////
-// begin argument-related functions.
-
-// Returns the number of arguments defined for the method.
-// This number automatically includes the this pointer (if present).
+/**
+ * @return the number of arguments defined for the method.
+ * This number automatically includes the this pointer (if present).
+ */
VMEXPORT unsigned method_args_get_number(Method_Signature_Handle msh);
VMEXPORT Boolean method_args_has_this(Method_Signature_Handle msh);
-// Return the class handle of the argument number idx.
-// That's true even for primitive types like int or float.
+/**
+ * Return the class handle of the argument number idx.
+ * That's TRUE even for primitive types like int or float.
+ */
VMEXPORT Type_Info_Handle method_args_get_type_info(Method_Signature_Handle msh,
unsigned idx);
-
-// Returns TRUE if the argument is a managed pointer.
+/**
+ * @return TRUE if the argument is a managed pointer.
+ */
VMEXPORT Boolean method_args_is_managed_pointer(Method_Signature_Handle msh, unsigned idx);
+////
// end argument-related functions.
-///////////////////////////////////////////////////////
+////
-
-///////////////////////////////////////////////////////
+////
// begin return value-related functions.
-
+////
VMEXPORT Type_Info_Handle method_ret_type_get_type_info(Method_Signature_Handle msh);
-// Returns TRUE if the return value is a managed pointer.
+/**
+ * @return TRUE if the return value is a managed pointer.
+ */
VMEXPORT Boolean method_ret_type_is_managed_pointer(Method_Signature_Handle msh);
+////
// end return value-related functions.
-///////////////////////////////////////////////////////
+////
-
+////
// end method-related functions.
-/////////////////////////////////////////////////////////////////
+////
-
-
-///////////////////////////////////////////////////////
+////
// begin type info-related functions.
+////
-// Array shapes and custom modifiers are not implemented yet.
-
-// If type info is a reference, type_info_get_class will return the class
-// of the reference.
+/**
+ * Array shapes and custom modifiers are not implemented yet.
+ *
+ * If type info is a reference, type_info_get_class
+ * will return the class of the reference.
+ */
VMEXPORT Boolean type_info_is_reference(Type_Info_Handle tih);
-// If type info is unboxed, type_info_get_class will return the class
-// of the unboxed type and class_is_primitive will return its VM_Data_Type.
+/**
+ * If type info is unboxed, type_info_get_class
+ * will return the class of the unboxed type and class_is_primitive
+ * will return its VM_Data_Type.
+ */
VMEXPORT Boolean type_info_is_unboxed(Type_Info_Handle tih);
-// Returns TRUE if the type is a primitive type. type_info_is_primitive does
-// not cause resolution in contrast to the otherwise equivalentcall sequence
-// suggested in the description of type_info_is_unboxed (i.e.
-// type_info_is_unboxed-->type_info_get_class-->class_is_primitive).
+/**
+ * @return TRUE if the type is a primitive type.
+ * type_info_is_primitive does
+ * not cause resolution in contrast to the otherwise equivalentcall sequence
+ * suggested in the description of type_info_is_unboxed
+ * (i.e. type_info_is_unboxed-->type_info_get_class-->class_is_primitive).
+ */
VMEXPORT Boolean type_info_is_primitive(Type_Info_Handle tih);
-// If TRUE, then
-// type_info_get_type_info returns the type info that the pointer
-// points to.
+/**
+ * If TRUE, then type_info_get_type_info
+ * returns the type info that the pointer points to.
+ */
VMEXPORT Boolean type_info_is_unmanaged_pointer(Type_Info_Handle tih);
-// For a return value a type can be void when it is not an unmanaged pointer.
-// In all other contexts, if type_info_is_void is TRUE then
-// type_info_is_unmanaged_pointer is TRUE too.
+/**
+ * For a return value a type can be void when it is not an unmanaged pointer.
+ * In all other contexts, if type_info_is_void is TRUE then
+ * type_info_is_unmanaged_pointer is TRUE too.
+ */
VMEXPORT Boolean type_info_is_void(Type_Info_Handle tih);
-// If TRUE, use type_info_get_method_sig to retrieve the method signature.
+/**
+ * If TRUE, use type_info_get_method_sig to
+ * retrieve the method signature.
+ */
VMEXPORT Boolean type_info_is_method_pointer(Type_Info_Handle tih);
-// Is it a vector, i.e., a one-dimensional, zero-based array.
+/**
+ * Is it a vector, i.e., a one-dimensional, zero-based array.
+ */
VMEXPORT Boolean type_info_is_vector(Type_Info_Handle tih);
-// Is it a general array, i.e., either multidimensional or non zero-based.
-// Returns FALSE for vectors. Always FALSE for Java.
+/**
+ * Is it a general array, i.e., either multidimensional or non zero-based.
+ *
+ * @return FALSE for vectors. Always FALSE for Java.
+ */
VMEXPORT Boolean type_info_is_general_array(Type_Info_Handle tih);
-// Get the class if type_info_is_reference or type_info_is_unboxed
-// returned TRUE. If the type info is a vector or a general array, return the
-// class handle for the array type (not the element type).
+/**
+ * Get the class if type_info_is_reference or
+ * type_info_is_unboxed returned TRUE.
+ * If the type info is a vector or a general array, return the
+ * class handle for the array type (not the element type).
+ */
VMEXPORT Class_Handle type_info_get_class(Type_Info_Handle tih);
-// Get the method signature if type_info_is_method_pointer returned TRUE.
+/**
+ * Get the method signature if type_info_is_method_pointer
+ * returned TRUE.
+ */
VMEXPORT Method_Signature_Handle type_info_get_method_sig(Type_Info_Handle tih);
-// Get recursively type info if type_info_is_unmanaged_pointer,
-// type_info_is_vector or type_info_is_general_array returned TRUE.
+/**
+ * Get recursively type info if type_info_is_unmanaged_pointer,
+ * type_info_is_vector or type_info_is_general_array
+ * returned TRUE.
+ */
VMEXPORT Type_Info_Handle type_info_get_type_info(Type_Info_Handle tih);
-// Return an VM_Data_Type corresponding to a type info.
-// This function is provided for convenience as it can be implemented in terms
-// of other functions provided in this interface.
+/**
+ * Return an VM_Data_Type corresponding to a type info.
+ * This function is provided for convenience as it can be implemented in terms
+ * of other functions provided in this interface.
+ */
VMEXPORT VM_Data_Type type_info_get_type(Type_Info_Handle tih);
+////
// end type info-related functions.
-///////////////////////////////////////////////////////
+////
-
-
-/////////////////////////////////////////////////////////////////
+////
// begin vector layout functions.
+////
-// Vectors are one-dimensional, zero-based arrays. All Java "arrays" are
-// vectors.
-// Functions provided in this section do not work on multidimensional or
-// non-zero based arrays (i.e. arrays with a lower bound that is non-zero
-// for at least one of the dimensions.
+/**
+ * Vectors are one-dimensional, zero-based arrays. All Java
+ * arrays are vectors.
+ * Functions provided in this section do not work on multidimensional or
+ * non-zero based arrays (i.e. arrays with a lower bound that is non-zero
+ * for at least one of the dimensions.
+ */
-
-// Return the offset to the length field of the array. That field has
-// the same offset for vectors of all types.
+/**
+ * Return the offset to the length field of the array. That field has
+ * the same offset for vectors of all types.
+ */
VMEXPORT int vector_length_offset();
-// Deprecated. Please use vector_length_offset instead.
-//VMEXPORT int array_length_offset();
+/**
+ * Deprecated. Please use vector_length_offset instead.
+ */
+VMEXPORT int array_length_offset();
-// Return the offset to the first element of the vector of the given type.
-// This function is provided for the cases when the class handle of the
-// element is not available.
+/**
+ * Return the offset to the first element of the vector of the given type.
+ * This function is provided for the cases when the class handle of the
+ * element is not available.
+ */
VMEXPORT int vector_first_element_offset(VM_Data_Type element_type);
-// Deprecated. Please use vector_first_element_offset instead.
-//VMEXPORT int array_first_element_offset(VM_Data_Type element_type);
+/**
+ * Deprecated. Please use vector_first_element_offset instead.
+ */
+VMEXPORT int array_first_element_offset(VM_Data_Type element_type);
-// Return the offset to the first element of the vector of the given type.
-// Assume that the elements are boxed. Byte offset.
+
+/**
+ * Return the offset to the first element of the vector of the given type.
+ * Assume that the elements are boxed. Byte offset.
+ */
VMEXPORT int vector_first_element_offset_class_handle(Class_Handle element_type);
VMEXPORT int vector_first_element_offset_vtable_handle(VTable_Handle element_type);
-// Deprecated. Please use vector_first_element_offset_class_handle instead.
-//VMEXPORT int array_first_element_offset_class_handle(Class_Handle element_type);
+/**
+ * Deprecated. Please use vector_first_element_offset_class_handle instead.
+ */
+VMEXPORT int array_first_element_offset_class_handle(Class_Handle element_type);
-// Return the offset to the first element of the vector of the given type.
-// If the class is a value type, assume that elements are unboxed.
-// If the class is not a value type, assume that elements are references.
+/**
+ * Return the offset to the first element of the vector of the given type.
+ * If the class is a value type, assume that elements are unboxed.
+ * If the class is not a value type, assume that elements are references.
+ */
VMEXPORT int vector_first_element_offset_unboxed(Class_Handle element_type);
-// Deprecated. Please use vector_first_element_offset_unboxed instead.
-//VMEXPORT int array_first_element_offset_unboxed(Class_Handle element_type);
+/**
+ * Deprecated. Please use vector_first_element_offset_unboxed instead.
+ */
+VMEXPORT int array_first_element_offset_unboxed(Class_Handle element_type);
-// Return the length of a vector. The caller must ensure that GC will not
-// move or deallocate the vector while vector_get_length() is active.
+/**
+ * Return the length of a vector. The caller must ensure that GC will not
+ * move or deallocate the vector while vector_get_length() is active.
+ */
VMEXPORT int32 vector_get_length(Vector_Handle vector);
-// Return the address to an element of a vector of references.
-// The caller must ensure that GC will not move or deallocate the vector
-// while vector_get_element_address_ref() is active.
+/**
+ * Return the address to an element of a vector of references.
+ * The caller must ensure that GC will not move or deallocate the vector
+ * while vector_get_element_address_ref() is active.
+ */
VMEXPORT Managed_Object_Handle *
vector_get_element_address_ref(Vector_Handle vector, int32 idx);
-// Return the size of a vector of a given number of elements.
-// The size is rounded up to take alignment into account.
+/**
+ * Return the size of a vector of a given number of elements.
+ * The size is rounded up to take alignment into account.
+ */
VMEXPORT unsigned vm_vector_size(Class_Handle vector_class, int length);
-
+////
// end vector layout functions.
-/////////////////////////////////////////////////////////////////
+////
-
-
-/////////////////////////////////////////////////////////////////
+////
// begin miscellaneous functions.
+////
-
-// Returns TRUE if references within objects and vector elements are
-// to be treated as offsets rather than raw pointers.
+/**
+ * @return TRUE if references within objects and vector elements are
+ * to be treated as offsets rather than raw pointers.
+ */
VMEXPORT Boolean vm_references_are_compressed();
-// Returns the starting address of the GC heap.
+/**
+ * @return The starting address of the GC heap.
+ */
VMEXPORT void *vm_heap_base_address();
-// Returns the ending address of the GC heap.
+/**
+ * @return The ending address of the GC heap.
+ */
VMEXPORT void *vm_heap_ceiling_address();
-// Returns TRUE if vtable pointers within objects are to be treated
-// as offsets rather than raw pointers.
+/**
+ * @return TRUE if vtable pointers within objects are to be treated
+ * as offsets rather than raw pointers.
+ */
VMEXPORT Boolean vm_vtable_pointers_are_compressed();
-// Returns the offset to the vtable pointer in an object.
+/**
+ * @return The offset to the vtable pointer in an object.
+ */
VMEXPORT int object_get_vtable_offset();
-// Returns the base address of the vtable memory area. This value will
-// never change and can be cached at startup.
+/**
+ * @return The base address of the vtable memory area. This value will
+ * never change and can be cached at startup.
+ */
VMEXPORT POINTER_SIZE_INT vm_get_vtable_base();
-// Returns the width in bytes (e.g. 4 or 8) of the vtable type
-// information in each object's header. This is typically used
-// by the JIT for generating type-checking code, e.g. for inlined
-// type checks or for inlining of virtual methods.
+/**
+ * @return The width in bytes (e.g. 4 or 8) of the vtable type
+ * information in each object's header. This is typically used
+ * by the JIT for generating type-checking code, e.g. for inlined
+ * type checks or for inlining of virtual methods.
+ */
VMEXPORT unsigned vm_get_vtable_ptr_size();
-// Returns a printable signature. The character buffer is owned by the
-// caller. Call free_string_buffer to reclaim the memory.
+/**
+ * @return A printable signature. The character buffer is owned by the
+ * caller. Call free_string_buffer to reclaim the memory.
+ */
VMEXPORT char *method_sig_get_string(Method_Signature_Handle msh);
-// Free a string buffer returned by method_sig_get_string.
+/**
+ * Free a string buffer returned by method_sig_get_string.
+ */
VMEXPORT void free_string_buffer(char *buffer);
@@ -690,42 +979,69 @@
JAVA_PROPERTIES = 1
} PropertyTable;
-//Sets the property for table_number property table. NULL value is supported.
+/**
+ * Sets the property for table_number property table. NULL value is supported.
+ */
VMEXPORT void set_property(const char* key, const char* value, PropertyTable table_number);
-//Returns the value of the property from table_number property table if it
-//has been set by set_property function. Otherwise returns NULL.
+/**
+ * @return The value of the property from table_number property table if it
+ * has been set by set_property function. Otherwise NULL.
+ */
VMEXPORT char* get_property(const char* key, PropertyTable table_number);
-//Safety frees memory of value returned by get_property function.
+/**
+ * Safety frees memory of value returned by get_property function.
+ */
VMEXPORT void destroy_property_value(char* value);
-//Checks if the property is set. Return:
-// -1 if table_number is incorrect.
-// 1 if property is set in table_number property table.
-// 0 otherwise.
+/**
+ * Checks if the property is set.
+ *
+ * @return -1 if table_number is incorrect.
+ * 1 if property is set in table_number property table.
+ * 0 otherwise.
+ */
VMEXPORT int is_property_set(const char* key, PropertyTable table_number);
-//Unsets the property in table_number property table.
+/**
+ * Unsets the property in table_number property table.
+ */
VMEXPORT void unset_property(const char* key, PropertyTable table_number);
-//Returns an array of keys from table_number properties table.
+/**
+ * @return An array of keys from table_number properties table.
+ */
VMEXPORT char** get_properties_keys(PropertyTable table_number);
-//Returns an array of keys which start with specified prefix from table_number properties table.
+/**
+ * @return An array of keys which start with specified prefix from
+ * table_number properties table.
+ */
VMEXPORT char** get_properties_keys_staring_with(const char* prefix, PropertyTable table_number);
-//Safety frees array of keys memory which returned by get_properties_keys
-//or get_properties_keys_staring_with functions.
+/**
+ * Safety frees array of keys memory which returned by get_properties_keys
+ * or get_properties_keys_staring_with functions.
+ */
VMEXPORT void destroy_properties_keys(char** keys);
-//Tries to interpret property value as Boolean and returns it. In case of failure returns default_value.
+/**
+ * Tries to interpret property value as Boolean and returns it.
+ * In case of failure returns default_value.
+ */
VMEXPORT Boolean get_boolean_property(const char* property, Boolean default_value, PropertyTable table_number);
-//Tries to interpret property value as int and returns it. In case of failure returns default_value.
+/**
+ * Tries to interpret property value as int and returns it. In case of failure
+ * returns default_value.
+ */
VMEXPORT int get_int_property(const char *property_name, int default_value, PropertyTable table_number);
+
+
+////
// end miscellaneous functions.
-/////////////////////////////////////////////////////////////////
+////
#ifdef __cplusplus
}
Index: trunk/vm/include/open/vm_util.h
===================================================================
--- trunk/vm/include/open/vm_util.h (revision 487512)
+++ trunk/vm/include/open/vm_util.h (working copy)
@@ -14,12 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
- * @author Intel, Alexei Fedotov
- * @version $Revision: 1.1.2.2.4.3 $
- */
-
#ifndef _VM_UTILS_H_
#define _VM_UTILS_H_
@@ -59,16 +54,17 @@
extern VTable *cached_object_array_vtable_ptr;
+/**
+ * Runtime support functions exported directly, because they
+ * may be called from native code.
+ */
-
-////////////////////////////////////////////////////////////////////////////
-// Runtime support functions exported directly, because they may be called
-// from native code.
-////////////////////////////////////////////////////////////////////////////
-
Boolean class_is_subtype(Class *sub, Class *super);
-// Like class_is_subtype, but sub must not be an interface class.
+/**
+ * Like class_is_subtype, but sub must not be an
+ * interface class.
+ */
Boolean class_is_subtype_fast(VTable *sub, Class *super);
@@ -155,12 +151,12 @@
/**
* @brief Generates an VM's helper to invoke the provided function.
*
- * The helper takes 'void*' parameter which is passed to the function after
- * some preparation made (namely GC and stack info are prepared to allow GC
- * to work properly).
+ * The helper takes the void* parameter, which is passed
+ * to the function after some preparation made (namely GC and stack
+ * info are prepared to allow GC to work properly).
*
- * The function must follow stdcall convention, which takes 'void*' and
- * returns 'void*', so does the helper.
+ * The function must follow stdcall convention, which takes void* and
+ * returns void*, so does the helper.
* On a return from the function, the helper checks whether an exception
* was raised for the current thread, and rethrows it if necessary.
*/