object_handles.h File Reference

---

Detailed Description

This module manages object handles and other forms of GC root protection.

It is not exposed outside VM - other modules should use pure JNI instead.

There are three managed pointer protection facilities: 1) Object handles on M2nFrames 2) Native object handles 3) GC frames GC frames are C++ objects that protect object references and managed pointers directly. A function can set up a GC frame to protect its references and then pass those references to functions it calls. Handles protect indirectly. A function creates handles for the references and passes the handles rather than the references.

Classes
class	GcFrame
struct	GcFrame.GcFrameNode
struct	_jobject
class	NativeObjectHandles
struct	ObjectHandlesOld
struct	ObjectHandlesNew
Defines
#define	GC_FRAME_DEFAULT_SIZE   10
	GC frames store memory locations which contain managed pointers, so they are updated during garbage collection.
Typedefs
typedef jobject	ObjectHandle
Functions
bool	managed_object_is_java_lang_class (ManagedObject *)
	Checks if an object is exactly java.lang.Class.class.
bool	object_is_java_lang_class (ObjectHandle)
	Checks if an object is exactly java.lang.Class.class.
bool	managed_object_is_valid (ManagedObject *)
	Checks if an object's virtual table points to the correct class.
bool	object_is_valid (ObjectHandle)
	Checks if an object's virtual table points to the correct class.
ObjectHandle	oh_allocate_global_handle ()
	Creates global handle, which needs to be explicitly freed.
ObjectHandle	oh_allocate_global_handle_from_jni ()
void	oh_deallocate_global_handle (ObjectHandle)
	Frees global handle.
void	oh_enumerate_global_handles ()
	Called during root enumeration process to enumerate global handles.
VMEXPORT ObjectHandle	oh_allocate_local_handle ()
ObjectHandle	oh_allocate_local_handle_from_jni ()
ObjectHandle	oh_convert_to_local_handle (ManagedObject *pointer)
ObjectHandle	oh_copy_to_local_handle (ObjectHandle oh)
void	oh_discard_local_handle (ObjectHandle)
VMEXPORT void	oh_enumerate_handles (ObjectHandles *)
void	oh_free_handles (ObjectHandles *)
void	oh_null_init_handles (ObjectHandles *handles)
LilCodeStub *	oh_gen_allocate_handles (LilCodeStub *, unsigned number_handles, char *base_var, char *helper_var)
POINTER_SIZE_INT	oh_get_handle_offset (unsigned handle_indx)
LilCodeStub *	oh_gen_init_handle (LilCodeStub *, char *base_var, unsigned handle_indx, char *val, bool null_check)
VMEXPORT void	free_local_object_handles2 (ObjectHandles *)
void	free_local_object_handles3 (ObjectHandles *)

---

Define Documentation

#define GC_FRAME_DEFAULT_SIZE   10

GC frames store memory locations which contain managed pointers, so they are updated during garbage collection.

Note, GC suspension must be disabled when created or deleting a frame and when adding objects or managed pointers.

---

Typedef Documentation

typedef jobject ObjectHandle

---

Function Documentation

bool managed_object_is_java_lang_class

(

ManagedObject *

)

Checks if an object is exactly java.lang.Class.class.

This function must be called when GC suspension is disabled.

bool object_is_java_lang_class

(

ObjectHandle

)

Checks if an object is exactly java.lang.Class.class.

This function must be called when GC suspension is enabled.

bool managed_object_is_valid

(

ManagedObject *

)

Checks if an object's virtual table points to the correct class.

This function must be called when GC suspension is disabled.

bool object_is_valid

(

ObjectHandle

)

Checks if an object's virtual table points to the correct class.

This function must be called when GC suspension is enabled.

ObjectHandle oh_allocate_global_handle

(

)

Creates global handle, which needs to be explicitly freed.

ObjectHandle oh_allocate_global_handle_from_jni

(

)

void oh_deallocate_global_handle

(

ObjectHandle

)

Frees global handle.

void oh_enumerate_global_handles

(

)

Called during root enumeration process to enumerate global handles.

VMEXPORT ObjectHandle oh_allocate_local_handle

(

)

ObjectHandle oh_allocate_local_handle_from_jni

(

)

ObjectHandle oh_convert_to_local_handle

(

ManagedObject *

pointer

)

ObjectHandle oh_copy_to_local_handle

(

ObjectHandle

oh

)

void oh_discard_local_handle

(

ObjectHandle

)

VMEXPORT void oh_enumerate_handles

(

ObjectHandles *

)

void oh_free_handles

(

ObjectHandles *

)

void oh_null_init_handles

(

ObjectHandles *

handles

)

LilCodeStub* oh_gen_allocate_handles	(	LilCodeStub *	,
		unsigned	number_handles,
		char *	base_var,
		char *	helper_var
	)

POINTER_SIZE_INT oh_get_handle_offset

(

unsigned

handle_indx

)

LilCodeStub* oh_gen_init_handle	(	LilCodeStub *	,
		char *	base_var,
		unsigned	handle_indx,
		char *	val,
		bool	null_check
	)

VMEXPORT void free_local_object_handles2

(

ObjectHandles *

)

void free_local_object_handles3

(

ObjectHandles *

)

---