interpreter_ti_set_breakpoint(..))
* is also passed as a parameter.
*/
void (*interpreter_ti_clear_breakpoint)(jmethodID method, jlocation location, jbyte saved);
/**
* Set callback to notify JVMTI about frame pop event.
- * @return JVMTI_ERROR_NONE - successfully added notification.
- * JVMTI_ERROR_OPAQUE_FRAME - frame is native.
- * JVMTI_ERROR_NO_MORE_FRAMES - depth too large.
+ *
+ * @return JVMTI_ERROR_NONE - successfully added notificationcallback_data pointer will
+ * be passed back to the JIT during the callback. The callback function is
+ * JIT_extended_class_callback.
+ */
VMEXPORT void vm_register_jit_extended_class_callback(JIT_Handle jit, Class_Handle clss,
void *callback_data);
-// Called by a JIT in order to be notified whenever the given method is overridden by a newly
-// loaded class. The callback_data pointer will be passed back to the JIT during the callback.
-// The callback function is JIT_overridden_method_callback.
+/**
+ * Called by a JIT in order to be notified whenever the given method is
+ * overridden by a newly loaded class. The callback_data pointer
+ * will be passed back to the JIT during the callback. The callback function is
+ * JIT_overridden_method_callback.
+ */
VMEXPORT void vm_register_jit_overridden_method_callback(JIT_Handle jit, Method_Handle method,
void *callback_data);
-// Called by a JIT in order to be notified whenever the vtable entries for the given method
-// are changed. This could happen, e.g., when a method is first compiled, or when it is
-// recompiled. The callback_data pointer will be passed back to the JIT during the callback.
-// The callback method is JIT_recompiled_method_callback.
+/**
+ * Called by a JIT in order to be notified whenever the vtable entries for the
+ * given method are changed. This could happen, e.g., when a method is first
+ * compiled, or when it is recompiled. The callback_data pointer
+ * will be passed back to the JIT during the callback. The callback method is
+ * JIT_recompiled_method_callback.
+ */
VMEXPORT void vm_register_jit_recompiled_method_callback(JIT_Handle jit, Method_Handle method,
void *callback_data);
-// Called by a JIT to have the VM replace a section of executable code in a thread-safe fashion.
-// This function does not synchronize the I- or D-caches. It may be a lot cheaper to batch up
-// the patch requests, so we may need to extend this interface.
+/**
+ * Called by a JIT to have the VM replace a section of executable code in a
+ * thread-safe fashion. This function does not synchronize the I- or D-caches.
+ * It may be a lot cheaper to batch up the patch requests, so we may need to
+ * extend this interface.
+ */
VMEXPORT void vm_patch_code_block(Byte *code_block, Byte *new_code, size_t size);
-// Called by a JIT to have the VM recompile a method using the specified JIT. After
-// recompilation, the corresponding vtable entries will be updated, and the necessary
-// callbacks to JIT_recompiled_method_callback will be made. It is a requirement that
-// the method has not already been compiled by the given JIT; this means that multiple
-// instances of a JIT may need to be active at the same time. (See vm_clone_jit.)
+/**
+ * Called by a JIT to have the VM recompile a method using the specified JIT. After
+ * recompilation, the corresponding vtable entries will be updated, and the necessary
+ * callbacks to JIT_recompiled_method_callback will be made. It is a
+ * requirement that the method has not already been compiled by the given JIT;
+ * this means that multiple instances of a JIT may need to be active at the same time.
+ *
+ * @sa vm_clone_jit
+ */
+
VMEXPORT void vm_recompile_method(JIT_Handle jit, Method_Handle method);
-// Called by a JIT to have VM synchronously (in the same thread) compile a method
-// It is a requirement that JIT calls this routine only during compilation of other method,
-// not during run-time.
+/**
+ * Called by a JIT to have VM synchronously (in the same thread) compile a method
+ * It is a requirement that JIT calls this routine only during compilation of
+ * other method, not during run-time.
+ */
+
VMEXPORT JIT_Result vm_compile_method(JIT_Handle jit, Method_Handle method);
-// Creates and returns a new instance of the given JIT. The new JIT's implementation of
-// JIT_init_with_data is invoked with the jit_data argument.
+/**
+ * Creates and returns a new instance of the given JIT. The new JIT's
+ * implementation of JIT_init_with_data is invoked with the
+ * jit_data argument.
+ */
+
VMEXPORT JIT_Handle vm_clone_jit(JIT_Handle jit, void *jit_data);
-// end direct call-related functions.
-///////////////////////////////////////////////////////
+//@}
+/** @name Exception-related compile-time functions
+ */
+//@{
+/**
+ * @return The number of exception handlers defined for this method in the
+ * bytecodes.
+ */
-
-///////////////////////////////////////////////////////
-// begin exception-related compile-time functions.
-
-
-// Return the number of exception handlers defined for this method in the
-// bytecodes.
VMEXPORT unsigned method_get_num_handlers(Method_Handle method);
-//deprecated: see method_get_handler_info
-//VMEXPORT void method_get_handler_info_full(Method_Handle method,
- //unsigned handler_id,
- //unsigned *begin_offset,
- //unsigned *end_offset,
- //unsigned *handler_offset,
- //unsigned *handler_len,
- //unsigned *filter_offset,
- //unsigned *handler_class_index);
+/**
+ * Deprecated.
+ *
+ * @sa method_get_handler_info
+ */
+VMEXPORT void method_get_handler_info_full(Method_Handle method,
+ unsigned handler_id,
+ unsigned *begin_offset,
+ unsigned *end_offset,
+ unsigned *handler_offset,
+ unsigned *handler_len,
+ unsigned *filter_offset,
+ unsigned *handler_class_index);
-// This is a simpler version of method_get_handler_info_full() that works
-// only for JVM.
+/**
+ * This is a simpler version of method_get_handler_info_full() that works
+ * only for JVM.
+ */
VMEXPORT void method_get_handler_info(Method_Handle method,
unsigned handler_id,
unsigned *begin_offset,
@@ -121,30 +145,50 @@
unsigned *handler_offset,
unsigned *handler_class_index);
-// deprecated: For Java methods, it always returns FALSE since JVM
-// handlers do not have a finally clause.
-//VMEXPORT Boolean method_handler_has_finally(Method_Handle method,
-// unsigned handler_id);
+/**
+ * Deprecated.
+ *
+ * @return For Java methods, it always returns FALSE since JVM
+ * handlers do not have a finally clause.
+ */
+VMEXPORT Boolean method_handler_has_finally(Method_Handle method,
+ unsigned handler_id);
-// deprecated: For Java methods, it always returns FALSE since JVM
-// handlers do not have a filters.
-//VMEXPORT Boolean method_handler_has_filter(Method_Handle method,
-// unsigned handler_id);
+/**
+ * Deprecated.
+ *
+ * @return For Java methods, it always returns FALSE since JVM
+ * handlers do not have a filters.
+ */
-// deprecated: For Java methods, it always returns FALSE since JVM
-// handlers do not have a fault clause.
-//VMEXPORT Boolean method_handler_has_fault(Method_Handle method,
-// unsigned handler_id);
+VMEXPORT Boolean method_handler_has_filter(Method_Handle method,
+ unsigned handler_id);
-// Set the number of exception handlers in the code generated by the JIT j
-// for a given method. The JIT must then call method_set_target_handler_info()
-// for each of the num_handlers exception handlers.
+/**
+ * Deprecated.
+ *
+ * @return For Java methods, it always returns FALSE since JVM
+ * handlers do not have a fault clause.
+ */
+
+VMEXPORT Boolean method_handler_has_fault(Method_Handle method,
+ unsigned handler_id);
+
+/**
+ * Set the number of exception handlers in the code generated by the JIT
+ * j for a given method. The JIT must then
+ * call method_set_target_handler_info()
+ * for each of the num_handlers exception handlers.
+ */
+
VMEXPORT void method_set_num_target_handlers(Method_Handle method,
JIT_Handle j,
unsigned num_handlers);
-// Set the information about an exception handler in the code generated by
-// the JIT.
+/**
+ * Set the information about an exception handler in the code generated by
+ * the JIT.
+ */
VMEXPORT void method_set_target_handler_info(Method_Handle method,
JIT_Handle j,
unsigned eh_number,
@@ -154,101 +198,139 @@
Class_Handle catch_cl,
Boolean exc_obj_is_dead);
-// end exception-related compile-time functions.
-///////////////////////////////////////////////////////
+//@}
+/** @name Method-related functions
+ */
+//@{
-
+/**
+ * @ingroup bytecodes
+ */
///////////////////////////////////////////////////////
-// begin method-related functions.
-
-///////////////////////////////////////////////////////
// begin method-related functions: bytecodes
+///////////////////////////////////
-// Get a pointer to the buffer containing the bytecodes for this method.
-// Bytecodes are either JVML instructions or CIL instructions.
-VMEXPORT const Byte *method_get_byte_code_addr(Method_Handle method);
+/**
+ * Get a pointer to the buffer containing the bytecodes for this method.
+ * Bytecodes are either JVML instructions or CIL instructions.
+ */
+ VMEXPORT const Byte *method_get_byte_code_addr(Method_Handle method);
-// Size if the buffer returned by method_get_byte_code_addr().
+/**
+ * Size if the buffer returned by method_get_byte_code_addr().
+ */
+
VMEXPORT size_t method_get_byte_code_size(Method_Handle method);
-// Maximum depth of the evaluation stack in this method.
+/**
+ * Maximum depth of the evaluation stack in this method.
+ */
+
VMEXPORT unsigned method_get_max_stack(Method_Handle method);
-
+//////////////////////////
// end method-related functions: bytecodes
///////////////////////////////////////////////////////
///////////////////////////////////////////////////////
// begin method-related functions: compiled code
+////////////////////////////
+/**
+ * @return The address where the code pointer for a given method is.
+ *
+ * A simple JIT that doesn't support recompilation (see e.g.
+ * vm_register_jit_recompiled_method_callback) can only
+ * generate code with indirect branches through the address provided
+ * by method_get_indirect_address().
+ */
-// Return the address where the code pointer for a given method is.
-// A simple JIT that doesn't support recompilation
-// (see e.g. vm_register_jit_recompiled_method_callback) can only generate
-// code with indirect branches through the address provided by
-// method_get_indirect_address().
VMEXPORT void *method_get_indirect_address(Method_Handle method);
-// Return the offset in bytes from the start of the vtable to the entry for
-// a given method.
+/**
+ * @return The offset in bytes from the start of the vtable to the entry for
+ * a given method.
+ */
VMEXPORT unsigned method_get_offset(Method_Handle method);
-
+///////////////////////////
// end method-related functions: compiled code
///////////////////////////////////////////////////////
///////////////////////////////////////////////////////
// begin method memory allocation-related functions.
+/////////////////////////////////
-// Allocate the "read-write" data block for this method. This memory block
-// cannot be retrieved later. The intention is to use the data block for data
-// that may be needed during the program execution (e.g. tables for
-// switch statements).
-//
-// Separation of data allocated by method_allocate_data_block() and
-// method_allocate_info_block() may help improve locality of references to data
-// accessed during execution of compiled code and data accessed during
-// stack uwinding.
-//
-// (See method_allocate_info_block).
+/**
+ * Allocate the "read-write" data block for this method. This memory block
+ * cannot be retrieved later. The intention is to use the data block for data
+ * that may be needed during the program execution (e.g. tables for
+ * switch statements).
+ *
+ * Separation of data allocated by method_allocate_data_block() and
+ * method_allocate_info_block() may help improve locality of
+ * references to data accessed during execution of compiled code and data
+ * accessed during stack uwinding.
+ *
+ * @sa method_allocate_info_block
+ */
+
VMEXPORT Byte *method_allocate_data_block(Method_Handle method,
JIT_Handle j,
size_t size,
size_t alignment);
-// Allocated a "read-only" data block.
-//
-// (? 20030314) This function is deprecated. In all new code, use
-// method_allocate_data_block() only. At some point, we will revisit
-// this interface to have more control over the layout of various
-// memory blocks allocated by the VM.
+/**
+ * Allocated a "read-only" data block.
+ *
+ * (? 20030314) This function is deprecated. In all new code, use
+ * method_allocate_data_block() only. At some point, we
+ * will revisit this interface to have more control over the layout
+ * of various memory blocks allocated by the VM.
+ */
+
VMEXPORT Byte *method_allocate_jit_data_block(Method_Handle method,
JIT_Handle j,
size_t size,
size_t alignment);
-// The following values should be used as the "heat" argument for calls like
-// method_allocate_code_block() or malloc_fixed_code_for_jit().
+/**
+ * The following values should be used as the "heat" argument for
+ * calls like method_allocate_code_block() or
+ * malloc_fixed_code_for_jit().
+ */
+
#define CODE_BLOCK_HEAT_COLD 0
#define CODE_BLOCK_HEAT_DEFAULT 1
#define CODE_BLOCK_HEAT_MAX 20
-// See method_allocate_code_block.
+/**
+ * @sa method_allocate_code_block
+ */
+
typedef enum Code_Allocation_ActionEnum {
CAA_Simulate,
CAA_Allocate
}Code_Allocation_Action;
-// This function allows allocation of multiple chunks of code with different
-// heat values. The JIT is responsible for specifying ids that are unique
-// within the same method.
-// The first instruction of the chunk with id=0 is the entry point of the method.
-// DEPRECATED: If the CAA_Allocate argument is specified, memory is allocated and a pointer
-// to it is returned. If the CAA_Simulate argument is specified, no memory is
-// allocated - the same as pass parameter size = 0 - function returns only current
-// address for allocation in pool but no memory is allocated.
+/**
+ * This function allows allocation of multiple chunks of code with different
+ * heat values. The JIT is responsible for specifying ids that are unique
+ * within the same method.
+ * The first instruction of the chunk with id=0 is the entry point
+ * of the method.
+ *
+ * Deprecated.
+ *
+ * @return If the CAA_Allocate argument is specified, memory is
+ * allocated and a pointer to it is returned. If the
+ * CAA_Simulate argument is specified, no memory is
+ * allocated - the same as pass parameter size = 0 - function returns
+ * only current address for allocation in pool but no memory is allocated.
+ */
+
VMEXPORT Byte *
method_allocate_code_block(Method_Handle m,
JIT_Handle j,
@@ -263,209 +345,288 @@
method_set_relocatable(Method_Handle m, JIT_Handle j, NativeCodePtr code_address, Boolean is_relocatable);
-// Allocate an info block for this method. An info block can be later
-// retrieved by the JIT. The JIT may for instance store GC maps for
-// root set enumeration and stack unwinding in the onfo block.
-// (See method_allocate_data_block)
+/**
+ * Allocate an info block for this method. An info block can be later
+ * retrieved by the JIT. The JIT may for instance store GC maps for
+ * root set enumeration and stack unwinding in the onfo block.
+ *
+ * @sa method_allocate_data_block
+ */
VMEXPORT Byte *method_allocate_info_block(Method_Handle method,
JIT_Handle j,
size_t size);
-// Retrieve the memory block allocated earlier by method_allocate_code_block().
-// A pair uniquely identifies a code block.
+ */
+
VMEXPORT Byte *method_get_code_block_addr_jit(Method_Handle method,
JIT_Handle j);
-// Get the size of the memory block allocated earlier by
-// method_allocate_code_block().
+/**
+ * Get the size of the memory block allocated earlier by
+ * method_allocate_code_block().
+ */
+
VMEXPORT unsigned method_get_code_block_size_jit(Method_Handle method,
JIT_Handle j);
-// Retrieve the memory block allocated earlier by
-// method_allocate_code_block().
-// A triple uniquely identifies a
+ * code block.
+ */
+
VMEXPORT Byte *method_get_code_block_addr_jit_new(Method_Handle method,
JIT_Handle j,
int id);
-// Get the size of the memory block allocated earlier by
-// method_allocate_code_block().
-// A triple uniquely identifies a
+ * code block.
+ */
+
VMEXPORT unsigned method_get_code_block_size_jit_new(Method_Handle method,
JIT_Handle j,
int id);
-// Retrieve the memory block allocated earlier by method_allocate_info_block().
-// A pair uniquely identifies a JIT info block.
+ */
+
VMEXPORT Byte *method_get_info_block_jit(Method_Handle method,
JIT_Handle j);
-// Get the size of the memory block allocated earlier by
-// method_allocate_info_block().
+/**
+ * Get the size of the memory block allocated earlier by
+ * method_allocate_info_block().
+ */
+
VMEXPORT unsigned method_get_info_block_size_jit(Method_Handle method,
JIT_Handle j);
///////////////////////////////////////////////////////
// begin functions for iterating over methods compiled by a given JIT.
+/////////////////////////////////////
#define METHOD_JIT_ITER_END 0
-// Here are the obvious three functions to iterate over all methods
-// compiled by a given JIT.
+/**
+ * Here are the obvious three functions to iterate over all methods
+ * compiled by a given JIT.
+ */
+
VMEXPORT Method_Iterator method_get_first_method_jit(JIT_Handle j);
VMEXPORT Method_Iterator method_get_next_method_jit(Method_Iterator mi);
VMEXPORT Method_Handle method_get_method_jit(Method_Iterator mi);
-
+/////////////////////////////////////////
// end functions for iterating over methods compiled by a given JIT.
///////////////////////////////////////////////////////
-
+//////////////////////////////
// end method-related functions.
///////////////////////////////////////////////////////
+/**
+ * @name Resolution-related functions
+ */
+//@{
+/**
+ * Resolve a class.
+ *
+ * The idx parameter is interpreted as a constant pool index for JVM.
+ */
-///////////////////////////////////////////////////////
-// begin resolution-related functions.
-
-
-// Resolve a class.
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
VMEXPORT Class_Handle
vm_resolve_class(Compile_Handle h, Class_Handle ch, unsigned idx);
-// Resolve a class and provide error checking if the class cannot have an
-// instance, i.e. it is abstract (or is an interface class).
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
+/**
+ * Resolve a class and provide error checking if the class cannot have an
+ * instance, i.e. it is abstract (or is an interface class).
+ * The idx parameter is interpreted as a constant pool index for JVM.
+ */
+
VMEXPORT Class_Handle
vm_resolve_class_new(Compile_Handle h, Class_Handle c, unsigned index);
-// Resolve a reference to a non-static field.
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
-// Used for getfield and putfield in JVM.
+/**
+ * Resolve a reference to a non-static field.
+ * The idx parameter is interpreted as a constant pool index for JVM.
+ * Used for getfield and putfield in JVM.
+ */
+
VMEXPORT Field_Handle
resolve_nonstatic_field(Compile_Handle h, Class_Handle ch, unsigned idx, unsigned putfield);
-// Resolve constant pool reference to a static field
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
-// Used for getstatic and putstatic in JVM.
+/**
+ * Resolve constant pool reference to a static field.
+ * The idx parameter is interpreted as a constant pool index for JVM.
+ * Used for getstatic and putstatic in JVM.
+ */
+
VMEXPORT Field_Handle
resolve_static_field(Compile_Handle h, Class_Handle ch, unsigned idx, unsigned putfield);
-// Resolve a method.
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
+/**
+ * Resolve a method.
+ * The idx parameter is interpreted as a constant pool index for JVM.
+ */
VMEXPORT Method_Handle
resolve_method(Compile_Handle h, Class_Handle ch, unsigned idx);
-// Resolve a method. Same as resolve_method() but the VM checks that the
-// method can be used for a virtual dispatch.
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
+/**
+ * Resolve a method. Same as resolve_method() but the VM checks
+ * that the method can be used for a virtual dispatch.
+ * The idx parameter is interpreted as a constant pool index for JVM.
+ */
+
VMEXPORT Method_Handle
resolve_virtual_method(Compile_Handle h, Class_Handle c, unsigned index);
-// Resolve a method. Same as resolve_method() but the VM checks that the
-// method is static (i.e. it is not an instance method).
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
+/**
+ * Resolve a method. Same as resolve_method() but the VM checks
+ * that the method is static (i.e. it is not an instance method).
+ * The idx parameter is interpreted as a constant pool index for
+ * JVM.
+ */
+
VMEXPORT Method_Handle
resolve_static_method(Compile_Handle h, Class_Handle c, unsigned index);
-// Resolve a method. Same as resolve_method() but the VM checks that the
-// method is declared in an interface type.
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
+/**
+ * Resolve a method. Same as resolve_method() but the VM checks
+ * that the method is declared in an interface type.
+ * The idx parameter is interpreted as a constant pool index for JVM.
+ */
+
VMEXPORT Method_Handle
resolve_interface_method(Compile_Handle h, Class_Handle c, unsigned index);
+//@}
+/** @name Miscellaneous functions
+ */
+//@{
-// end resolution-related functions.
-///////////////////////////////////////////////////////
+/**
+ * @return A UTF8 representation of a string declared in a class.
+ *
+ * The idx parameter is interpreted as a constant pool
+ * index for JVM.
+ * class_get_const_string is generally only for JIT internal use,
+ * e.g. printing a string pool constant in a bytecode disassembler.
+ * The resulting const char* should of course not be inserted into
+ * the jitted code.
+ */
+VMEXPORT const char *class_get_const_string(Class_Handle ch, unsigned idx);
-/////////////////////////////////////////////////////////////////
-// begin miscellaneous functions.
+/**
+ * @return The address where the interned version of the string
+ * is stored.
+ *
+ * Calling class_get_const_string_intern_addr has
+ * a side-effect of interning the string, so that the JIT can
+ * load a reference to the interned string without checking if
+ * it is null.
+ */
-// Returns a UTF8 representation of a string declared in a class.
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
-// class_get_const_string is generally only for JIT internal use,
-// e.g. printing a string pool constant in a bytecode disassembler.
-// The resulting const char* should of course not be inserted into
-// the jitted code.
-VMEXPORT const char *class_get_const_string(Class_Handle ch, unsigned idx);
+VMEXPORT void *class_get_const_string_intern_addr(Class_Handle ch, unsigned idx);
+/**
+ * @return The type of a compile-time constant.
+ *
+ * The idx parameter is interpreted as a constant pool index for JVM.
+ */
-// Returns the address where the interned version of the string
-// is stored. Calling class_get_const_string_intern_addr has
-// a side-effect of interning the string, so that the JIT can
-// load a reference to the interned string without checking if
-// it is null.
-VMEXPORT void *class_get_const_string_intern_addr(Class_Handle ch, unsigned idx);
+ VMEXPORT VM_Data_Type class_get_const_type(Class_Handle ch, unsigned idx);
-// Returns the type of a compile-time constant.
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
-VMEXPORT VM_Data_Type class_get_const_type(Class_Handle ch, unsigned idx);
+/**
+ * @return The signature for field or (interface) method in constant pool entry.
+ * The cp_index parameter is interpreted as a constant pool index
+ * for JVM.
+ */
-// Returns the signature for field or (interface) method in constant pool entry
-// The 'cp_index' parameter is interpreted as a constant pool index for JVM.
VMEXPORT const char* class_get_cp_entry_signature(Class_Handle src_class,
unsigned short cp_index);
-// Returns the data type for field in constant pool entry
-// The 'cp_index' parameter is interpreted as a constant pool index for JVM.
+/**
+ * @return The data type for field in constant pool entry.
+ *
+ * The cp_index parameter is interpreted as a constant pool index
+ * for JVM.
+ */
+
VMEXPORT VM_Data_Type class_get_cp_field_type(Class_Handle src_class,
unsigned short cp_index);
-// Returns a pointer to the location where the constant is stored.
-// The 'idx' parameter is interpreted as a constant pool index for JVM.
-// This function shouldn't be called for constant strings.
-// Instead, either:
-// 1. the jitted code should get the string object at runtime by calling
-// VM_RT_LDC_STRING, or
-// 2. use class_get_const_string_intern_addr().
+/**
+ * @return A pointer to the location where the constant is stored.
+ *
+ * The idx parameter is interpreted as a constant pool index for JVM.
+ * This function shouldn't be called for constant strings. Instead, either:VM_RT_LDC_STRING, or
+ * method_ prefix really make sense here?
+ * Perhaps we should rename this function?
+ */
+
VMEXPORT JIT_Handle method_get_JIT_id(Compile_Handle h);
+//@}
+/** @name Experimental functions
+ */
+//@{
-// end miscellaneous functions.
-/////////////////////////////////////////////////////////////////
-
-
-
-/////////////////////////////////////////////////////////////////
-// begin experimental functions.
-//
-// These functions are currently not part of the official interface,
-// although they may be promoted in some form in the future.
-
-
-
-// Returns TRUE if the VM's functionality for monitorenter and monitorexit
-// may be inlined by the JIT, and FALSE if not. If TRUE is returned, then
-// the output arguments will be filled in with the synchronization parameters.
-// The parameters are the following:
-// thread_id_register: the register number that holds the thread ID which
-// is used to identify the locking thread
-// sync_header_offset: the offset in bytes of the synchronization header
-// from the start of the object
-// sync_header_width: the width in bytes of the synchronization header
-// lock_owner_offset: the offset in bytes of the lock owner field from
-// the start of the object
-// lock_owner_width: the width in bytes of the lock owner field in the
-// synchronization header
-// jit_clears_ccv: TRUE if the JIT-generated code needs to clear the
-// ar.ccv register, FALSE if the VM ensures it is
-// already cleared
-//
-// Note that this is useful only for monitorenter/monitorexit, but not
-// monitorenter_static/monitorexit_static, since the JIT doesn't know how to
-// map the class_handle to an object.
+/**
+ * These functions are currently not part of the official interface,
+ * although they may be promoted in some form in the future.
+ *
+ * @return TRUE if the VM's functionality for monitorenter
+ * and monitorexit may be inlined by the JIT; otherwise, FALSE.
+ *
+ * If TRUE is returned, then the output arguments will be
+ * filled in with the synchronization parameters.
+ *
+ * @param thread_id_register - the register number that holds the thread ID which
+ * is used to identify the locking thread
+ * @param sync_header_offset - the offset in bytes of the synchronization header
+ * from the start of the object
+ * @param sync_header_width - the width in bytes of the synchronization header
+ * @param lock_owner_offset - the offset in bytes of the lock owner field from
+ * the start of the object
+ * @param lock_owner_width - the width in bytes of the lock owner field in the
+ * synchronization header
+ * @param jit_clears_ccv - TRUE if the JIT-generated code needs
+ * to clear the ar.ccv register,
+ * FALSE if the VM ensures it is
+ * already cleared
+ *
+ * @note This is useful only for monitorenter/monitorexit, but not
+ * monitorenter_static/monitorexit_static, since the JIT doesn't
+ * know how to map the class_handle to an object.
+ */
VMEXPORT Boolean jit_may_inline_object_synchronization(unsigned *thread_id_register,
unsigned *sync_header_offset,
unsigned *sync_header_width,
@@ -483,10 +644,6 @@
VMEXPORT CallingConvention vm_managed_calling_convention();
-// end experimental functions.
-/////////////////////////////////////////////////////////////////
-
-
#ifdef __cplusplus
}
#endif
Index: trunk/vm/include/jvmti_types.h
===================================================================
--- trunk/vm/include/jvmti_types.h (revision 487512)
+++ trunk/vm/include/jvmti_types.h (working copy)
@@ -1,10 +1,10 @@
/*
* 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
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -14,10 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
-* @author Gregory Shimansky
-* @version $Revision: 1.1.2.1.4.4 $
-*/
+
#ifndef _JVMTI_TYPES_H_
#define _JVMTI_TYPES_H_
@@ -115,28 +112,28 @@
*/
enum
{
- /*
- * Class bytecodes have been verified
+ /**
+ * Class bytecodes have been verified.
*/
JVMTI_CLASS_STATUS_VERIFIED = 1,
- /*
- * Class preparation is complete
+ /**
+ * Class preparation is complete.
*/
JVMTI_CLASS_STATUS_PREPARED = 2,
- /*
+ /**
* Class initialization is complete. Static initializer has been run.
*/
JVMTI_CLASS_STATUS_INITIALIZED = 4,
- /*
- * Error during initialization makes class unusable
+ /**
+ * Error during initialization makes class unusable.
*/
JVMTI_CLASS_STATUS_ERROR = 8,
- /*
+ /**
* Class is an array. If set, all other bits are zero.
*/
JVMTI_CLASS_STATUS_ARRAY = 16,
- /*
- * Class is a primitive class (for example, java.lang.Integer.TYPE).
+ /**
+ * Class is a primitive class (for example, java.lang.Integer.TYPE).
* If set, all other bits are zero.
*/
JVMTI_CLASS_STATUS_PRIMITIVE = 32
@@ -244,7 +241,7 @@
/**
* Event numbers (from spec). Custom events could be added
- * after JVMTI_MAX_EVENT_TYPE_VAL.
+ * after JVMTI_MAX_EVENT_TYPE_VAL.
*/
typedef enum
{
@@ -362,8 +359,8 @@
jint slot;
} jvmtiLocalVariableEntry;
- /* ******************************************************
- * Event management is exposed to other OPEN components.
+ /**
+ * Event management is exposed to other OPEN components.
*/
typedef void (JNICALL * jvmtiEventVMInit)
@@ -598,7 +595,7 @@
} jvmtiExtensionEventInfo;
/**
- * OPEN components should be aware of event management
+ * OPEN components should be aware of event management
* capabilities.
*/
typedef struct
Index: trunk/vm/include/open/jthread.h
===================================================================
--- trunk/vm/include/open/jthread.h (revision 487512)
+++ trunk/vm/include/open/jthread.h (working copy)
@@ -1,10 +1,10 @@
/*
* 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
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -14,26 +14,26 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
- * @author Andrey Chernyshev
- * @version $Revision$
- */
+
#ifndef _OPEN_THREAD_GENERIC_H
#define _OPEN_THREAD_GENERIC_H
/**
- * @file jthread_.h
- * @brief Java threading interface
+ * @file
+ * Java threading interface
+ *
* @details
* Java threading interface - contains functions to work with Java threads.
* The generic part od Java thrading interface is mostly targeted to address
- * the needs of java.lang.Object and java.lang.Thread classes implementations.
- * All functions in this interface start with jthread_* prefix.
- * The implemnentation of this layer provides the mapping of Java thrads onto native/OS threads.
+ * the needs of java.lang.Object and java.lang.Thread
+ * classes implementations.
+ * All functions in this interface start with <>jthread_* prefix.
+ * The implemnentation of this layer provides the mapping of Java thrads onto
+ * native/OS threads.
*
- * For more detailes see thread manager component documentation located at vm/thread/doc/ThreadManager.htm
- *
+ * For more detailes, see thread manager component documentation located at
+ * vm/thread/doc/ThreadManager.htm
*/
#include "open/types.h"
@@ -46,7 +46,8 @@
#endif /* __cplusplus */
-/** @name Basic manipulation
+/**
+ * @name Basic manipulation
*/
//@{
@@ -132,15 +133,17 @@
*
* @param[in] thread those attribute is set
* @param[in] name thread name
- * @sa java.lang.Thread.setName()
+ *
+ * @sa java.lang.Thread.setName()
*/
IDATA jthread_set_name(jthread thread, jstring name);
/**
* Returns the name for the thread.
*
- * @param[in] thread those attribute is read
- * @sa java.lang.Thread.getName()
+ * @param[in] - thread those attribute is read
+ *
+ * @sa java.lang.Thread.getName()
*/
jstring jthread_get_name(jthread thread);
Index: trunk/vm/vmcore/include/compile.h
===================================================================
--- trunk/vm/vmcore/include/compile.h (revision 487512)
+++ trunk/vm/vmcore/include/compile.h (working copy)
@@ -1,10 +1,10 @@
/*
* 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
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -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.1.4.3 $
- */
-
#ifndef _COMPILE_H_
#define _COMPILE_H_
@@ -34,22 +29,30 @@
void vm_delete_all_jits();
void vm_initialize_all_jits();
-// Protect arguments from GC
-// The arguments are those passed to the last M2nFrame
-// The given method's signature describes what arguments were passed
-void compile_protect_arguments(Method_Handle method, GcFrame* gc);
+/**
+ * Protect arguments from GC.
+ *
+ * The arguments are those passed to the last M2nFrame.
+ * The given method's signature describes what arguments were passed.
+ */
+
+void compile_protect_arguments(Method_Handle method, GcFrame* gc).
-// Code has been generated by writing it to memory.
-// Ensure that it is visible to all instruction fetchers.
-// The first function flushes a particular block of code,
-// the other should be called after all blocks are flushed.
+/**
+ * Code has been generated by writing it to memory.
+ *
+ * Ensure that it is visible to all instruction fetchers.
+ * The first function flushes a particular block of code,
+ * another should be called after all blocks are flushed.
+ */
void compile_flush_generated_code_block(Byte*, size_t);
-void compile_flush_generated_code();
-
+void compile_flush_generated_code().
+
/**
* Execution manager uses this method to call back to VM to compile
* a method using a specific JIT.
*/
+
JIT_Result compile_do_compilation_jit(Method* method, JIT* jit);
NativeCodePtr compile_gen_compile_me(Method_Handle method);
@@ -66,20 +69,29 @@
Global_Env* compile_handle_to_environment(Compile_Handle);
-// Create a LIL stub for JNI interfacing
+/**
+ * Create a LIL stub for JNI interfacing.
+ */
+
NativeCodePtr compile_create_lil_jni_stub(Method_Handle method, void* func, NativeStubOverride nso);
-// Create a LIL stub for JNI interfacing
+/**
+ * Create a LIL stub for JNI interfacing.
+ */
+
NativeCodePtr interpreter_compile_create_lil_jni_stub(Method_Handle method, void* func, NativeStubOverride nso);
-// Create a LIL stub for PINVOKE interfacing
-NativeCodePtr compile_create_lil_pinvoke_stub(Method_Handle method, void* func, NativeStubOverride nso);
+/**
+ * Create a LIL stub for PINVOKE interfacing.
+ */
-//
-// Support for stub override code sequences
-//
+NativeCodePtr compile_create_lil_pinvoke_stub(Method_Handle method, void* func, NativeStubOverride nso);
+/**
+ * Support for stub override code sequences.
+ */
+
typedef void (Override_Generator)(Emitter_Handle, Method *);
typedef unsigned (Override_Size)(Method *);
@@ -91,7 +103,10 @@
Override_Size *override_size;
} Stub_Override_Entry;
-// Points to an an array of override entries with sizeof_stub_override_entries entries.
+/**
+ * Points to an an array of override entries with
+ * sizeof_stub_override_entries entries.
+ */
extern Stub_Override_Entry *stub_override_entries;
extern int sizeof_stub_override_entries;
@@ -100,17 +115,23 @@
bool needs_override(Method*);
-//
-// Method instrumentation support.
-//
-
-// Type of the instrumentation procedures called before invoking methods.
+/**
+ * Method instrumentation support.
+ *
+ * Type of the instrumentation procedures called before invoking methods.
+ */
typedef void (*MethodInstrumentationProc)(CodeChunkInfo *callee);
-// Interpose on calls to the specified method by calling the instr_proc.
+/**
+ * Interpose on calls to the specified method by calling the instr_proc.
+ */
NativeCodePtr compile_do_instrumentation(CodeChunkInfo *callee, MethodInstrumentationProc instr_proc);
-// A MethodInstrumentationProc that records the number of calls from the caller code chunk to the callee.
+/**
+ * A MethodInstrumentationProc that records the number of
+ * calls from the caller code chunk to the callee.
+ */
+
void count_method_calls(CodeChunkInfo *callee);
struct DynamicCode
@@ -121,10 +142,14 @@
DynamicCode *next;
};
-// Adding dynamic generated code info to global list
-// Is used in JVMTI and native frames interface
+/**
+ * Adding dynamic generated code info to global list.
+ * Is used in JVMTI and native frames interface
+ */
DynamicCode* compile_get_dynamic_code_list(void);
-// Adding dynamic generated code info to global list
+/**
+ * Adding dynamic generated code info to global list.
+ */
void compile_add_dynamic_generated_code_chunk(const char* name, const void* address, jint length);
void compile_clear_dynamic_code_list(DynamicCode* list);
Index: trunk/vm/vmcore/include/environment.h
===================================================================
--- trunk/vm/vmcore/include/environment.h (revision 487512)
+++ trunk/vm/vmcore/include/environment.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,10 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
- * @author Intel, Alexei Fedotov
- * @version $Revision: 1.1.2.5.4.3 $
- */
#ifndef _ENVIRONMENT_H
#define _ENVIRONMENT_H
@@ -62,9 +58,9 @@
JavaVMInitArgs vm_arguments;
- //
- // globals
- //
+ /**
+ * Globals
+ */
bool is_hyperthreading_enabled; // VM automatically detects HT status at startup.
bool use_lil_stubs; // 20030307: Use LIL stubs instead of hand crafted ones. Default off (IPF) on (IA32).
bool compress_references; // 20030311 Compress references in references and vector elements.
@@ -81,31 +77,48 @@
Lock_Manager *p_method_call_lock;
Lock_Manager *p_handle_lock;
- // If set to true by the "-compact_fields" command line option,
- // the VM will not pad out fields of less than 32 bits to four bytes.
- // However, fields will still be aligned to a natural boundary,
- // and the num_field_padding_bytes field will reflect those alignment padding bytes.
- bool compact_fields;
+ /**
+ * If set to true by the -compact_fields command-line option,
+ * the VM will not pad out fields of less than 32 bits to four bytes.
+ * However, fields will still be aligned to a natural boundary,
+ * and the num_field_padding_bytes field will reflect those
+ * alignment padding bytes.
+ */
+ bool compact_fields;
- // If set to true by the "-sort_fields" command line option,
- // the VM will sort fields by size before assigning their offset during
- // class preparation.
+ /**
+ * If set to true by the -sort_fields command line option,
+ * the VM will sort fields by size before assigning their offset during
+ * class preparation.
+ */
bool sort_fields;
- // Base address of Java heap
+ /*
+ * Base address of Java heap.
+ */
+
Byte* heap_base;
- // Ceiling of Java heap.
- // NOTE: we assume Java heap uses one continuous memory block.
+
+ /**
+ * Ceiling of Java heap.
+ */
+
+ /**
+ * @note We assume Java heap uses one continuous memory block.
+ */
+
Byte* heap_end;
- // This will be set to either NULL or heap_base depending
- // on whether compressed references are used.
+ /**
+ * This will be set to either NULL or heap_base depending
+ * on whether compressed references are used.
+ */
+
Byte* managed_null;
- //
- // preloaded strings
- //
-
+ /**
+ * Preloaded strings
+ */
String* JavaLangObject_String;
String* JavaLangClass_String;
String* Init_String;
@@ -138,9 +151,9 @@
String* LoadClassDescriptor_String;
String* InitCauseDescriptor_String;
- //
- // preloaded classes
- //
+ /**
+ * Preloaded classes
+ */
Class* Boolean_Class;
Class* Char_Class;
Class* Float_Class;
@@ -184,7 +197,10 @@
ObjectHandle java_lang_Object;
ObjectHandle java_lang_OutOfMemoryError;
ObjectHandle java_lang_ThreadDeath;
- // object of java.lang.Error class used for JVMTI JIT PopFrame support
+ /**
+ * Object of java.lang.Error class used for
+ * JVMTI JIT PopFrame support.
+ */
ObjectHandle popFrameException;
Class* java_io_Serializable_Class;
@@ -200,23 +216,36 @@
Class* java_lang_reflect_Method_Class;
Class* finalizer_thread;
- // pointers to 2 static fields in FinalizerThread class.
+
+ /**
+ * Pointers to two static fields in FinalizerThread class.
+ */
+
jboolean* finalizer_shutdown;
jboolean* finalizer_on_exit;
Class* java_lang_EMThreadSupport_Class;
- // VTable for the java_lang_String class
- VTable* JavaLangString_VTable;
+ /**
+ * VTable for the java_lang_String class
+ */
+ VTable* JavaLangString_VTable;
- // Offset to the vm_class field in java.lang.Class;
+ /**
+ * Offset to the vm_class field in java.lang.Class.
+ */
unsigned vm_class_offset;
- // The VM state. See VM_STATE enum above.
+ /**
+ * The VM state. See VM_STATE enum above.
+ */
volatile int vm_state;
- // FIXME
- // The whole environemt will be refactored to VM instance
- // The following contains a cached copy of EM interface table
+ /**
+ * FIXME
+ *
+ * The whole environemt will be refactored to VM instance.
+ * The following contains a cached copy of EM interface table.
+ */
OpenComponentManagerHandle cm;
OpenInstanceHandle em_instance;
OpenEmVmHandle em_interface;
@@ -232,9 +261,10 @@
void operator delete(void * mem, apr_pool_t * pool) {};
- //
- // determine bootstrapping of root classes
- //
+ /**
+ * Determine bootstrapping of root classes
+ */
+
bool InBootstrap() const { return bootstrapping; }
void StartVMBootstrap() {
assert(!bootstrapping);
@@ -257,25 +287,30 @@
return vm_state == VM_SHUTDOWNING;
}
- //load a class via bootstrap classloader
+ /**
+ * Load a class via bootstrap classloader.
+ */
+
Class* LoadCoreClass(const String* name);
Class* LoadCoreClass(const char* name);
/**
- * Set "Ready For Exceptions" state.
- * This function must be called as, soon as VM becomes able to create
- * exception objects. I.e. all required classes (such as "java/lang/Trowable")
- * are loaded .
- */
+ * Set Ready For Exceptions state.
+ * This function must be called as, soon as VM becomes able to create
+ * exception objects. I.e. all required classes (such as java/lang/Trowable)
+ * are loaded.
+ */
+
void ReadyForExceptions()
{
ready_for_exceptions = true;
}
/**
- * Get "Ready For Exceptions" state.
- * @return true, if VM is able to create exception objects.
- */
+ * Get Ready For Exceptions state.
+ *
+ * @return TRUE, if VM is able to create exception objects.
+ */
bool IsReadyForExceptions() const
{
return ready_for_exceptions;
Index: trunk/vm/vmcore/include/exceptions.h
===================================================================
--- trunk/vm/vmcore/include/exceptions.h (revision 487512)
+++ trunk/vm/vmcore/include/exceptions.h (working copy)
@@ -1,10 +1,10 @@
/*
* 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
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -14,10 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/**
- * @author Intel, Pavel Afremov
- * @version $Revision: 1.1.2.1.4.3 $
- */
+
#ifndef _EXCEPTIONS_H_
#define _EXCEPTIONS_H_
@@ -27,27 +24,22 @@
#include "open/types.h"
/**
-@file
-\ref exceptions
-*/
+ * @file
+ * ref exceptions
+ */
/**
-@page exceptions Exceptions subsystem
-
-\section exn_introduction Introduction
-The functions to work with exceptions are described in exceptions.h.
-
-\section exn_issues Issues
-
-\li Interaction with JIT and runtime helpers? -salikh
-\li Interaction with JIT is implemented via rth_wrap_exn_throw stubs. -pavel.n.afremov
-\li Existing interface is currently included.
-
-*/
-
+ \ page page1 exceptions Exceptions subsystem
+ \section section1 exn_introduction Introduction
+ The functions to work with exceptions are described in exceptions.h.
+ \section section1 exn_issues Issues
+ \li Interaction with JIT and runtime helpers? -salikh
+ \li Interaction with JIT is implemented via rth_wrap_exn_throw stubs. -pavel.n.afremov
+ \li Existing interface is currently included.
+ */
/**
- * Returns the thread-local exception object
- * or NULL if no exception occured.
+ * @return The thread-local exception object, or NULL if no
+ * exception occured.
*/
VMEXPORT jthrowable exn_get();
@@ -56,21 +48,23 @@
/**
- * Returns true if the thread-local exception object is set.
+ * @return TRUE if the thread-local exception object is set.
*/
VMEXPORT bool exn_raised();
/**
* Clears the thread-local exception object.
*
- * @note rename of clear_current_thread_exception(). It may be eliminated if
- * exn_catch() will be used and will clean thread exception.
+ * @note Rename of clear_current_thread_exception().
+ * It may be eliminated if exn_catch() will be
+ * used and will clean thread exception.
*/
VMEXPORT void exn_clear();
/**
* Creates exception object.
*/
+
//FIXME LAZY EXCEPTION (2006.05.06)
// Maybe change to exn_object_create (whole 7)
jthrowable exn_create(Exception* exception);
@@ -101,21 +95,22 @@
VMEXPORT jthrowable exn_create(const char* exc_name, const char* message, jthrowable cause);
/**
- * Returns true if frame is unwindable and false if isn't.
+ * @return TRUE if frame is unwindable and false if isn't.
*/
VMEXPORT bool is_unwindable();
/**
* Sets unwindable property of frame. If frame is unwindable property
* should be true and should be false if frame isn't unwindable.
- * Returns previous value of unwindable property.
+ *
+ * @return Previous value of unwindable property.
*/
bool set_unwindable(bool unwindable);
/**
- * Throws an exception object
+ * Throws an exception object.
*
- * @note internal convenience function, may not be exposed to VMI interface.
+ * @note Internal convenience function, may not be exposed to VMI interface.
*/
void exn_throw_object(jthrowable exc_object);
@@ -123,7 +118,7 @@
* Throws an exceptionas lazy.
* Does not return in case of destructive exception propagation.
*
- * @note internal convenience function, may not be exposed to VMI interface.
+ * @note Internal convenience function, may not be exposed to VMI interface.
*/
void exn_throw_by_class(Class* exc_class);
void exn_throw_by_class(Class* exc_class, jthrowable exc_cause);
@@ -158,15 +153,15 @@
/**
* Sets exceptions as a thread local exception.
*
- * @note explicit non-destructive semantics should be deduced from context.
+ * @note Explicit non-destructive semantics should be deduced from context.
*/
VMEXPORT void exn_raise_object(jthrowable exc_object);
/**
* Sets exception lazy as a thread local exception.
*
- * @note internal convenience function, may not be exposed to VMI interface.
- * @note explicit non-destructive semantics should be deduced from context.
+ * @note Internal convenience function, may not be exposed to VMI interface.
+ * @note Explicit non-destructive semantics should be deduced from context.
*/
void exn_raise_by_class(Class* exc_class);
void exn_raise_by_class(Class* exc_class, jthrowable exc_cause);
@@ -177,28 +172,28 @@
/**
* Sets exception lazy as a thread local exception.
*
- * @note explicit non-destructive semantics should be deduced from context.
+ * @note Explicit non-destructive semantics should be deduced from context.
*/
VMEXPORT void exn_raise_by_name(const char* exception_name);
/**
* Sets exception lazy as a thread local exception.
*
- * @note explicit non-destructive semantics should be deduced from context.
+ * @note Explicit non-destructive semantics should be deduced from context.
*/
VMEXPORT void exn_raise_by_name(const char* exception_name, jthrowable exc_cause);
/**
* Sets exception lazy as a thread local exception.
*
- * @note explicit non-destructive semantics should be deduced from context.
+ * @note Explicit non-destructive semantics should be deduced from context.
*/
VMEXPORT void exn_raise_by_name(const char* exception_name, const char* message);
/**
* Sets exception lazy as a thread local exception.
*
- * @note explicit non-destructive semantics should be deduced from context.
+ * @note Explicit non-destructive semantics should be deduced from context.
*/
VMEXPORT void exn_raise_by_name(const char* exception_name, const char* message,
jthrowable exc_cause);
@@ -208,27 +203,27 @@
* After this returns true. If unwinding is happnened control coming back into
* this function, and after this it returns false.
*
- * @note experimental
+ * @note Experimental.
*/
bool exn_function_try();
/**
- * pops dummy non-unwindable stack frame
+ * Pops dummy non-unwindable stack frame.
*
- * returns the current thread exception object
- * or NULL if no exception occured.
+ * @retur The current thread exception object, or NULL
+ * if no exception occured.
*
- * @note experimental
+ * @note Experimental.
*/
jthrowable exn_function_catch();
/**
- * Wrapper for exn_function_try.
+ * Wrapper for exn_function_try.
*/
#define exn_try (if (exn_function_try()))
/**
- * Wrapper for exn_function_catch.
+ * Wrapper for exn_function_catch.
*/
#define exn_catch (th) (if ( th = exn_function_catch()))
@@ -256,16 +251,21 @@
struct ManagedObject;
-//**** Stack Trace support
+/**
+ * Stack Trace support
+ */
-// Print the stack trace stored in the exception object to the given file.
+/**
+ * Print the stack trace stored in the exception object to the given file.
+ */
void exn_print_stack_trace(FILE* f, jthrowable exc);
void print_uncaught_exception_message(FILE *f, char* context_message, jthrowable exc);
-//**** Native code exception support
-
+/**
+ * Native code exception support
+ */
void exn_rethrow();
void exn_rethrow_if_pending();
Index: trunk/vm/vmcore/include/jit_export.h
===================================================================
--- trunk/vm/vmcore/include/jit_export.h (revision 487512)
+++ trunk/vm/vmcore/include/jit_export.h (working copy)
@@ -1,10 +1,10 @@
/*
* 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
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -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.1.4.4 $
- */
+/**
+ * These are the functions that a JIT built as a DLL must export.
+ * Some functions may be optional and are marked as such.
+ */
-//
-// These are the functions that a JIT built as a DLL must export.
-// Some functions may be optional and are marked as such.
-//
-
#ifndef _JIT_EXPORT_H
#define _JIT_EXPORT_H
@@ -52,10 +47,11 @@
// Required functions.
////////////////////////////////////////////////////////
-//
-// Flags passed from the VM to the JIT.
-//
-// Max 32 bits, so that it fits in one word.
+/**
+ * Flags passed from the VM to the JIT.
+ *
+ * Max 32 bits, so that it fits in one word.
+ */
typedef
struct JIT_Flags {
@@ -76,71 +72,85 @@
* call a certain VM helpers at certain places in the code. For JIT,
* in particular, this means that it will have to generate additional
* code which will perform these calls.
-* +* * Each of the requirement is associated with a corresponding ability of * the EE to satisfy this requirement. So, elements of the struct should also * be used to denote EE capabilities related to method execution. -*
+*
* If an element corresponds to a certain VM helper, concrete contract
* of calling this helper (arguments, etc.) can be found at the place of
* definition of this helper (or its ID) within present OPEN specification.
*/
typedef struct OpenMethodExecutionParams {
- /** call corresponding VM helper upon entry to the managed method */
+
+ /**
+ * Call corresponding VM helper upon entry to the managed method.
+ */
Boolean exe_notify_method_entry : 1;
- /** call corresponding VM helper upon exit from the managed method */
+ /**
+ * Call corresponding VM helper upon exit from the managed method.
+ */
Boolean exe_notify_method_exit : 1;
- /** call corresponding VM helper upon reading a value of a field which has get_address_of_this method. Used for JVMTI debug support.
*/
Boolean exe_provide_access_to_this : 1;
/**
* Provide restoring of arguments in the stack after the call
- * of the unwind_frame method so that method could be called again
+ * of the unwind_frame method so that method could be called again
* with the same arguments. Used for JVMTI debug support.
*/
Boolean exe_restore_context_after_unwind : 1;
@@ -197,14 +209,16 @@
JIT_Flags flags
);
-/**
+ /**
* Performs compilation of given method.
*
* @param method_handle - handle of the method to be compiled
- * @param compilation_params - compilation parameters. If NULL, default compilation parameters
- * should be used by the JIT (passed in the initialize function). If either of parameters is
- * not supported by the JIT, the function should return compilation failure.
- * @return compilation status
+ * @param compilation_params - compilation parameters. If NULL,
+ * default compilation parameters should be used by
+ * the JIT (passed in the initialize function).
+ * If either of parameters is not supported by the JIT,
+ * the function should return compilation failure.
+ * @return Compilation status.
*/
JITEXPORT JIT_Result JIT_compile_method_with_params(
JIT_Handle jit,
@@ -214,10 +228,10 @@
);
-/**
+ /**
* Retrieves method execution-related capabilities supported by the EE.
*
- * @return the set of supported capabilities
+ * @return The set of supported capabilities.
*/
JITEXPORT OpenMethodExecutionParams JIT_get_exe_capabilities (JIT_Handle jit);
Index: trunk/vm/vmcore/include/jit_export_jpda.h
===================================================================
--- trunk/vm/vmcore/include/jit_export_jpda.h (revision 487512)
+++ trunk/vm/vmcore/include/jit_export_jpda.h (working copy)
@@ -1,10 +1,10 @@
/*
* 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
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -14,10 +14,6 @@
* 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.4 $
- */
#ifndef _JIT_EXPORT_JPDA_H
#define _JIT_EXPORT_JPDA_H
@@ -28,9 +24,9 @@
extern "C" {
#endif // __cplusplus
-/**
+ /**
* Elements of this enum denote various error conditions which can
- * arise when working with the OpenExeJPDA interface.
+ * arise when working with the OpenExeJPDA interface.
*/
typedef enum OpenExeJpdaError {
EXE_ERROR_NONE,
@@ -42,19 +38,21 @@
} OpenExeJpdaError;
-/**
+ /**
* Gets corresponding native code location for given bytecode location.
- * @param method method whose bytecode contains the location
- * @param bc_pc location within the bytecode
- * @param native_pc (out) upon successfull return points to corresponding native
- * code location
+ *
+ * @param method - method whose bytecode contains the location
+ * @param bc_pc - location within the bytecode
+ * @param[out] native_pc - upon successfull return points to corresponding native
+ * code location
* @return
- * EXE_ERROR_NONE on success
- * EXE_ERROR_INVALID_METHODID if the given method handle is invalid
+ * EXE_ERROR_NONE on success.
+ * EXE_ERROR_INVALID_METHODID if the given method handle is invalid.
* EXE_ERROR_INVALID_LOCATION if either the execution engine is unable to map
- * the bytecode location or if the location is invalid (does not correspond to
- * a valid offset of a bytecode instruction)
- * EXE_ERROR_UNSUPPORTED if the execution engine does not support this functionality
+ * the bytecode location or if the location is invalid
+ * (does not correspond to a valid offset of a bytecode
+ * instruction).
+ * EXE_ERROR_UNSUPPORTED if the execution engine does not support this functionality.
*/
JITEXPORT OpenExeJpdaError get_native_location_for_bc(
JIT_Handle jit,
@@ -63,18 +61,23 @@
NativeCodePtr *native_pc
);
-/**
- * Gets corresponding bytecode location for given native location (absolute code address).
- * @param method method whose (compiled native) code contains the location
- * @param native_pc location within the native code
- * @param bc_pc (out) upon successfull return points to corresponding bytecode location
+ /**
+ * Gets corresponding bytecode location for given native location (absolute
+ * code address).
+ *
+ * @param method - method whose (compiled native) code contains the location
+ * @param native_pc - location within the native code
+ * @param[out] bc_pc - upon successfull return points to corresponding bytecode
+ * location
* @return
- * EXE_ERROR_NONE on success
- * EXE_ERROR_INVALID_METHODID if the given method handle is invalid
+ * EXE_ERROR_NONE on success.
+ * EXE_ERROR_INVALID_METHODID if the given method handle is invalid.
* EXE_ERROR_INVALID_LOCATION if either the execution engine is unable to map
- * the native location or if the location is invalid (does not correspond to
- * a valid offset of a processor instruction within the compiled code)
- * EXE_ERROR_UNSUPPORTED if the execution engine does not support this functionality
+ * the native location or if the location is
+ * invalid (does not correspond to a valid offset
+ * of a processor instruction within the compiled code).
+ * EXE_ERROR_UNSUPPORTED if the execution engine does not support this
+ * functionality.
*/
JITEXPORT OpenExeJpdaError get_bc_location_for_native(
JIT_Handle jit,
@@ -84,23 +87,28 @@
);
-/**
+ /**
* Gets the value of the bytecode local variable in given method stack frame.
- * @param method method in whose frame the variable is to be read
- * @param context stack frame of the method describing its current execution state
- * (at the point of thread suspension)
- * @param var_num the variable's slot number
- * @param var_type the variable's type
- * @param value_ptr address of the buffer to write variable value into. Caller is responsible for
- * providing enough (OPEN_VM::get_vm_type_size(var_type) bytes) memory in the buffer.
+ *
+ * @param method - method in whose frame the variable is to be read
+ * @param context - stack frame of the method describing its current execution state
+ * (at the point of thread suspension)
+ * @param var_num - the variable's slot number
+ * @param var_type - the variable's type
+ * @param value_ptr - address of the buffer to write variable value into.
+ * Caller is responsible for providing enough
+ * (OPEN_VM::get_vm_type_size(var_type) bytes)
+ * memory in the buffer
+ *
* @return
- * EXE_ERROR_NONE on success
- * EXE_ERROR_INVALID_METHODID if the given method handle is invalid
- * EXE_ERROR_INVALID_LOCATION if the execution engine does not support local variable access
- * at current execution point in the method, specified by the context
- * EXE_ERROR_TYPE_MISMATCH if the variable with given slot is of different type,
- * EXE_ERROR_INVALID_SLOT if the stack frame does not have variable with given slot number,
- * EXE_ERROR_UNSUPPORTED if the execution engine does not support this functionality
+ * EXE_ERROR_NONE on success.
+ * EXE_ERROR_INVALID_METHODID if the given method handle is invalid.
+ * EXE_ERROR_INVALID_LOCATION if the execution engine does not support local
+ * variable access at current execution point
+ * in the method, specified by the context.
+ * EXE_ERROR_TYPE_MISMATCH if the variable with given slot is of different type.
+ * EXE_ERROR_INVALID_SLOT if the stack frame does not have variable with given slot number.
+ * EXE_ERROR_UNSUPPORTED if the execution engine does not support this functionality.
*/
JITEXPORT OpenExeJpdaError get_local_var(
JIT_Handle jit,
@@ -112,22 +120,25 @@
);
-/**
+ /**
* Sets the value of the bytecode local variable in given method stack frame.
- * @param method method in whose frame the variable is to be changed
- * @param context stack frame of the method describing its current execution state
- * (at the point of thread suspension)
+ *
+ * @param method method in whose frame the variable is to be changed
+ * @param context stack frame of the method describing its current execution state
+ * (at the point of thread suspension)
* @param var_num the variable's slot number
- * @param var_type the variable's type
- * @param value_ptr address of the new value for the variable
+ * @param var_type the variable's type
+ * @param value_ptr address of the new value for the variable
+ *
* @return
- * EXE_ERROR_NONE on success
- * EXE_ERROR_INVALID_METHODID if the given method handle is invalid
+ * EXE_ERROR_NONE on success.
+ * EXE_ERROR_INVALID_METHODID if the given method handle is invalid.
* EXE_ERROR_INVALID_LOCATION if the execution engine does not support local variable access
- * at current execution point in the method, specified by the context
- * EXE_ERROR_TYPE_MISMATCH if the variable with given slot is of different type,
- * EXE_ERROR_INVALID_SLOT if the stack frame does not have variable with given slot number,
- * EXE_ERROR_UNSUPPORTED if the execution engine does not support this functionality
+ * at current execution point in the method,
+ * specified by the context.
+ * EXE_ERROR_TYPE_MISMATCH if the variable with given slot is of different type.
+ * EXE_ERROR_INVALID_SLOT if the stack frame does not have variable with given slot number.
+ * EXE_ERROR_UNSUPPORTED if the execution engine does not support this functionality.
*/
JITEXPORT OpenExeJpdaError set_local_var(
JIT_Handle jit,
Index: trunk/vm/vmcore/include/jit_export_rt.h
===================================================================
--- trunk/vm/vmcore/include/jit_export_rt.h (revision 487512)
+++ trunk/vm/vmcore/include/jit_export_rt.h (working copy)
@@ -1,10 +1,10 @@
/*
* 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
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -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.1.4.3 $
- */
+/**
+ * These are the functions that a JIT built as a DLL must export for
+ * the purpose of runtime interaction.
+ */
-//
-// These are the functions that a JIT built as a DLL must export for
-// the purpose of runtime interaction.
-//
-
#ifndef _JIT_EXPORT_RT_H
#define _JIT_EXPORT_RT_H
@@ -36,15 +31,16 @@
extern "C" {
#endif // __cplusplus
-
-
-///////////////////////////////////////////////////////
+/////////
// begin Frame Contexts for JITs
+////////
#ifdef _IPF_
-// Note that the code in transfer context is very depend upon the ordering of fields in this structure.
-// Be very careful in changing this structure.
+/**
+ * @note The code in transfer context is very depend upon the ordering of fields
+ * in this structure. Be very careful in changing this structure.
+ */
typedef
struct JitFrameContext {
uint64 *p_ar_pfs;
@@ -109,7 +105,7 @@
uint32 *p_ecx;
uint32 *p_edx;
- // To restore processor flags during transfer
+
uint32 eflags;
Boolean is_ip_past;
@@ -128,34 +124,47 @@
// begin direct call support
-// The following are optional functions used by the direct call-related JIT interface.
-// These functions are implemented by a JIT and invoked by the VM. They allow a JIT
-// to be notified whenever, e.g., a VM data structure changes that would require
-// code patching or recompilation.
-
-// The callback that corresponds to vm_register_jit_extended_class_callback.
-// The newly loaded class is new_class. The JIT should return TRUE if any code was modified
-// (consequently the VM will ensure correctness such as synchronizing I- and D-caches),
-// and FALSE otherwise.
+/**
+ * The following are optional functions used by the direct call-related
+ * JIT interface.
+ * These functions are implemented by a JIT and invoked by the VM. They allow
+ * a JIT to be notified whenever, e.g., a VM data structure changes that would
+ * require code patching or recompilation.
+ *
+ * The callback that corresponds to vm_register_jit_extended_class_callback.
+ * The newly loaded class is new_class.
+ *
+ * @return TRUE if any code was modified
+ * (consequently the VM will ensure correctness such as synchronizing
+ * I- and D-caches); otherwise, FALSE.
+ */
JITEXPORT Boolean
JIT_extended_class_callback(JIT_Handle jit,
Class_Handle extended_class,
Class_Handle new_class,
void *callback_data);
-// The callback that corresponds to vm_register_jit_overridden_method_callback.
-// The overriding method is new_method. The JIT should return TRUE if any code was modified
-// (consequently the VM will ensure correctness such as synchronizing I- and D-caches),
-// and FALSE otherwise.
+/**
+ * The callback that corresponds to new_method.
+ *
+ * @return TRUE if any code was modified (consequently the VM will
+ * ensure correctness such as synchronizing I- and D-caches); otherwise,
+ * FALSE.
+ */
+
JITEXPORT Boolean
JIT_overridden_method_callback(JIT_Handle jit,
Method_Handle overridden_method,
Method_Handle new_method,
void *callback_data);
-// The callback that corresponds to vm_register_jit_recompiled_method_callback.
-// The JIT should return TRUE if any code was modified (consequently the VM will ensure
-// correctness such as synchronizing I- and D-caches), and FALSE otherwise.
+/**
+ * The callback that corresponds to vm_register_jit_recompiled_method_callback.
+ *
+ * @return TRUE if any code was modified (consequently the VM will ensure
+ * correctness such as synchronizing I- and D-caches); otherwise, FALSE.
+ */
JITEXPORT Boolean
JIT_recompiled_method_callback(JIT_Handle jit,
Method_Handle recompiled_method,
@@ -228,9 +237,14 @@
// begin compressed references
-// Returns TRUE if the JIT will compress references within objects and vector elements by representing
-// them as offsets rather than raw pointers. The JIT should call the VM function vm_references_are_compressed()
-// during initialization in order to decide whether it should compress references.
+/**
+ * @return TRUE if the JIT will compress references within
+ * objects and vector elements by representing them as offsets
+ * rather than raw pointers. The JIT should call the VM function
+ * vm_references_are_compressed() during initialization
+ * in order to decide whether it should compress references.
+ */
+
JITEXPORT Boolean
JIT_supports_compressed_references(JIT_Handle jit);
Index: trunk/vm/vmcore/include/jit_runtime_support_common.h
===================================================================
--- trunk/vm/vmcore/include/jit_runtime_support_common.h (revision 487512)
+++ trunk/vm/vmcore/include/jit_runtime_support_common.h (working copy)
@@ -1,10 +1,10 @@
/*
* 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
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -14,15 +14,7 @@
* 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.1.4.4 $
- */
-
-
-
-
#ifndef _JIT_RUNTIME_SUPPORT_COMMON_H_
#define _JIT_RUNTIME_SUPPORT_COMMON_H_
@@ -33,11 +25,15 @@
VMEXPORT // temporary solution for interpreter unplug
int __stdcall vm_instanceof(ManagedObject *obj, Class *c) stdcall__;
-// Implements VM_RT_AASTORE
+/**
+ * Implements VM_RT_AASTORE.
+ */
void * __stdcall
vm_rt_aastore(ManagedObject *elem, int idx, Vector_Handle array) stdcall__;
-// Implements VM_RT_AASTORE_TEST
+/**
+ * Implements VM_RT_AASTORE_TEST.
+ */
int __stdcall
vm_aastore_test(ManagedObject *elem, Vector_Handle array) stdcall__;
@@ -56,16 +52,21 @@
Vector_Handle vm_rt_new_vector_using_vtable_and_thread_pointer(
int length, Allocation_Handle vector_handle, void *tp);
-// creates a LIL code stub for checkcast or instanceof
-// can be used by both IA32 and IPF code
-LilCodeStub *gen_lil_typecheck_stub(bool is_checkcast);
-
-// creates a SPECIALIZED LIL code stub for checkcast or instanceof
-// it assumes that the class is suitable for fast instanceof checks.
-// The result is a different fast stub for every class.
-// will_inline should be set to TRUE if this stub will be inlined
-// in a JIT, and false if it will be passed to a code generator
-// (this is due to the slightly different treatment of exceptions)
+/**
+ * Creates a LIL code stub for checkcast or instance of
+ * can be used by both IA32 and IPF code
+ */
+ LilCodeStub *gen_lil_typecheck_stub(bool is_checkcast).
+
+/**
+ * Creates a SPECIALIZED LIL code stub for checkcast or instance of
+ * it assumes that the class is suitable for fast instanceof checks.
+ *
+ * @return Different fast stub for every class. will_inline
+ * is set to TRUE, if this stub will be inlined in a JIT,
+ * and FALSE, if it will be passed to a code generator
+ * (this is due to the slightly different treatment of exceptions).
+ */
LilCodeStub *gen_lil_typecheck_stub_specialized(bool is_checkcast,
bool will_inline,
Class *superclass);
Index: trunk/vm/vmcore/include/vm_strings.h
===================================================================
--- trunk/vm/vmcore/include/vm_strings.h (revision 487512)
+++ trunk/vm/vmcore/include/vm_strings.h (working copy)
@@ -1,10 +1,10 @@
/*
* 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
- * the License. You may obtain a copy of the License at
+ * the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
@@ -14,14 +14,10 @@
* 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 $
- */
-
-// This describes the VM internal interface for manipulating strings
-
+/**
+ * This describes the VM internal interface for manipulating strings.
+ */
#ifndef _VM_STRINGS_H_
#define _VM_STRINGS_H_
@@ -65,57 +61,100 @@
jstring String_to_interned_jstring(String* str);
-//***** New Interface
+/**
+ * @name New Interface
+ */
+//@{
-// GC must be disabled, but at a GC safe point
+
+/**
+ * GC must be disabled, but at a GC safe point.
+ */
+
ManagedObject* string_create_from_utf8(const char* buf, unsigned length);
ManagedObject* string_create_from_unicode(const uint16* buf, unsigned length);
ManagedObject* string_create_blank(unsigned length); // Create a string of given length (in characters) with arbitrary characters
-// GC must be disabled
-// returns length in characters
+/**
+ * GC must be disabled.
+ *
+ * @return Length in characters.
+ */
unsigned string_get_length(ManagedObject*);
-// GC must be disabled
-// returns the length of the UTF8 encoding of the string
+/**
+ * GC must be disabled.
+ *
+ * @return The length of the UTF8 encoding of the string
+ */
unsigned string_get_utf8_length(ManagedObject* str);
-// GC must be disabled
-// result is zero terminated
-// Caller should free the result
+/**
+ * GC must be disabled.
+ * Result is zero terminated.
+ * Caller should free the result.
+ */
+
const uint16* string_get_unicode_chars(ManagedObject* string);
-// GC must be disabled
-// result is zero terminated
-// Caller should free the result
+/**
+ * GC must be disabled
+ * Result is zero terminated.
+ * Caller should free the result.
+ */
+
const char* string_get_utf8_chars(ManagedObject* string);
-// GC must be disabled
-// Copy the characters offset..offset+count-1 into res
+/**
+ * GC must be disabled.
+ * Copy the characters offset..offset+count-1 into res.
+ */
void string_get_unicode_region(ManagedObject* str, unsigned offset, unsigned count, uint16* res);
-// GC must be disabled
-// Encode characters offset..offset+count-1 into UTF8 and place in res
+/**
+ * GC must be disabled.
+ * Encode characters offset..offset+count-1 into UTF8 and place in res.
+ */
+
void string_get_utf8_region(ManagedObject* str, unsigned offset, unsigned count, char* res);
-//*** Handle versions
+/**
+ * @name Handle versions
+ */
+//@{
+
+
ObjectHandle string_create_from_utf8_h(const char* buf, unsigned length);
ObjectHandle string_create_from_unicode_h(const uint16* buf, unsigned length);
-// returns length in characters
+/**
+ * @return Length in characters.
+ */
+
unsigned string_get_length_h(ObjectHandle str);
-// returns the length of the UTF8 encoding of the string
+/**
+ * @return The length of the UTF8 encoding of the string.
+ */
+
unsigned string_get_utf8_length_h(ObjectHandle str);
-// Caller should free the result
+/**
+ * Caller should free the result.
+ */
+
const char* string_get_utf8_chars_h(ObjectHandle string);
-// Copy the characters offset..offset+count-1 into buf
+/**
+ * Copy the characters offset..offset+count-1 into buf.
+ */
+
void string_get_unicode_region_h(ObjectHandle str, unsigned offset, unsigned count, uint16* buf);
-// Encode characters offset..offset+count-1 into UTF8 and place in buf
+/**
+ * Encode characters offset..offset+count-1 into UTF8 and place in buf.
+ */
void string_get_utf8_region_h(ObjectHandle str, unsigned offset, unsigned count, char* buf);
#endif //!_VM_STRINGS_H_