gc.h File Reference


Detailed Description

GC interface exposed to VM.

These are the functions that a GC built as a DLL must export. Some functions may be optional and are marked as such.

This is a global include file which provides to the VM an interface to the GC. This interface is the only supported interface that the VM should call to talk to the GC. All routines in this C interface will begin with gc_.

The GC expects that there is a vm_gc.h file holding the only interface that the GC will use to talk to the VM.

In order to eliminate dependency on certain types such as (VTable *) we have eliminated them from this interface and replace them with (void *). While this might appear to be unfortunate it allows us to eliminate any knowledge of the class and VTable structures that are not of interest to the GC.


Routines to support the functionality required by the Java language specification

#define GC_OBJECT_ALIGNMENT   4
 Granularity of object alignment.
void gc_force_gc ()
 API for the VM to force a GC, typically in response to a call to java.lang.Runtime.gc.
int64 gc_total_memory ()
 API for the VM to determine the current GC heap size, typically in response to a call to java.lang.Runtime.totalMemory.
int64 gc_max_memory ()
 API for the VM to determine the maximum GC heap size, typically in response to a call to java.lang.Runtime.maxMemory.
int64 gc_free_memory ()
 API for the VM to get an approximate view of the free space, typically in response to a call to java.lang.Runtime.freeMemory.
Boolean gc_is_object_pinned (Managed_Object_Handle obj)
 
Returns:
TRUE if the object is pinned.

void gc_class_prepared (Class_Handle ch, VTable_Handle vth)
 The VM calls this function after a new class has been prepared.
int64 gc_get_collection_count ()
int64 gc_get_collection_time ()

Routines to support threads

typedef void * Thread_Handle
 Opaque handle for threads.
void gc_thread_init (void *gc_information)
 This routine is called during thread startup to set an initial nursery for the thread.
void gc_thread_kill (void *gc_information)
 This is called just before the thread is reclaimed.
VMEXPORT void vm_iterate_threads ()
 GC may call this function asynchronously any time it wants to get thread list.
void gc_iterate_thread (Thread_Handle thread)
 VM calls this method repeatedly to iterate over the list of java threads, initiated earlier by calling vm_iterate_threads().
VMEXPORT void vm_suspend_thread (Thread_Handle thread)
 GC calls this method to request VM to suspend an individual thread.
void gc_thread_suspended (Thread_Handle thread)
 VM calls this GC callback when it's accomplished the requested operation of suspending a thread in gc-safe point.
VMEXPORT void vm_enumerate_thread_root_set (Thread_Handle thread)
 GC calls this function to command VM to enumerate a thread, which was earlier suspenden using vm_suspend_thread().
VMEXPORT void vm_enumerate_global_root_set ()
 GC calls this function to command VM to enumerate global slots.

Defines

#define GCExport   __declspec(dllexport)
 GCExport is used to declare functions exported by GC.
#define BITS_PER_BYTE   8
#define NEXT_TO_HIGH_BIT_SET_MASK   (1<<((sizeof(unsigned) * BITS_PER_BYTE)-2))
#define NEXT_TO_HIGH_BIT_CLEAR_MASK   ~NEXT_TO_HIGH_BIT_SET_MASK

Functions

unsigned int gc_time_since_last_gc ()
 API for the VM to get the time since the last GC happened.
void * gc_heap_base_address ()
 
Returns:
The base address of the heap.

void * gc_heap_ceiling_address ()
 
Returns:
The top address of the heap.

Routines to support the initialization and termination of GC
int gc_init ()
 Is called by VM to start GC initialization sequence.
void gc_test_safepoint ()
 May be called at various points the VM decides are GC-safe.
Boolean gc_supports_frontier_allocation (unsigned *offset_of_current, unsigned *offset_of_limit)
 If the GC supports a "bump-the-pointer" style allocation, where the GC's thread-local information contains a "current" pointer and a "limit" pointer, then it should return TRUE, and it should set *offset_of_current to be the offset into the GC thread block of the "current" pointer, and similar for *offset_of_limit and the "limit" pointer.
void gc_vm_initialized ()
 This API is used by the VM to notify the GC that the VM has completed bootstrapping and initialization, and is henceforth ready to field requests for enumerating live references.
void gc_wrapup ()
 This is called once the VM has no use for the heap or the garbage collector data structures.
void gc_add_root_set_entry (Managed_Object_Handle *ref, Boolean is_pinned)
 Is called by the VM to enumerate the root reference.
void gc_add_compressed_root_set_entry (uint32 *ref, Boolean is_pinned)
 Resembles gc_add_root_set_entry() but is passed the address of a slot containing a compressed reference.
void gc_add_weak_root_set_entry (Managed_Object_Handle *slot, Boolean is_pinned, Boolean is_short_weak)
 Is called by the VM to enumerate weak root reference.
void gc_add_root_set_entry_managed_pointer (void **slot, Boolean is_pinned)
 Enumerate a managed pointer.
void gc_add_root_set_entry_interior_pointer (void **slot, int offset, Boolean is_pinned)
 Call from the VM to the gc to enumerate an interior pointer.
Managed_Object_Handle gc_alloc_fast (unsigned size, Allocation_Handle type, void *thread_pointer)
 This routine is the primary routine used to allocate objects.
Managed_Object_Handle gc_alloc (unsigned size, Allocation_Handle type, void *thread_pointer)
 This routine is used to allocate an object.
Managed_Object_Handle gc_pinned_malloc_noclass (unsigned size)
 For bootstrapping situations, when we still don't have a class for the object.
Managed_Object_Handle gc_alloc_pinned (unsigned size, Allocation_Handle type, void *thread_pointer)
 Allocate pinned forever object.
Routines to support write barriers
Boolean gc_requires_barriers ()
 
Returns:
TRUE if the GC requires write barriers before every store to a field of a reference type.

Routines to support various write barriers
Boolean gc_supports_compressed_references ()
 
Returns:
TRUE if references within objects and vector elements are to be treated as offsets rather than raw pointers.

void gc_write_barrier (Managed_Object_Handle p_base_of_obj_with_slot)
 These interfaces are marked for replacement for the IPF by the following gc_heap_write_mumble interface.
void gc_heap_wrote_object (Managed_Object_Handle p_base_of_object_just_written)
 There are two flavors for historical reasons.
void gc_heap_write_global_slot (Managed_Object_Handle *p_slot, Managed_Object_Handle value)
 By calling this function VM notifies GC that a heap reference was written to global slot.
void gc_heap_write_global_slot_compressed (uint32 *p_slot, Managed_Object_Handle value)
 VM should call this function on heap reference writes to global slots.
void gc_heap_write_ref (Managed_Object_Handle p_base_of_object_with_slot, unsigned offset, Managed_Object_Handle value)
 VM should call this function on heap reference writes to heap objects.
void gc_heap_slot_write_ref (Managed_Object_Handle p_base_of_object_with_slot, Managed_Object_Handle *p_slot, Managed_Object_Handle value)
 VM should call this function on heap reference writes to heap objects.
void gc_heap_slot_write_ref_compressed (Managed_Object_Handle p_base_of_object_with_slot, uint32 *p_slot, Managed_Object_Handle value)
 VM should call this function on heap reference writes to heap objects.
void gc_pin_object (Managed_Object_Handle *p_object)
 Pin object.
void gc_unpin_object (Managed_Object_Handle *p_object)
 Unpin object.
int32 gc_get_hashcode (Managed_Object_Handle object)
 Get identity hashcode.
Managed_Object_Handle gc_get_next_live_object (void *iterator)
 Iterate all live objects in heap.
void gc_iterate_heap ()
 Iterates all objects in the heap.
void gc_finalize_on_exit ()
 Moves all finalizable objects to vm finalization queue.
void gc_set_mutator_block_flag ()
 Sets the mutator need block flag in case of heavy finalizable object load.
Boolean gc_clear_mutator_block_flag ()
 Clears the mutator need block flag when heavy finalizable object load lightens.
Boolean gc_supports_class_unloading ()
 
Returns:
TRUE if references within objects and vector elements are to be treated as offsets rather than raw pointers.

Routines to support soft, weak, and phantom reference objects
void JNICALL Java_java_lang_ref_Reference_enqueue_reference (JNIEnv *the_env, jobject p_obj)
 reference - the reference object to register.
jobject JNICALL Java_java_lang_ref_Reference_get (JNIEnv *the_env, jobject p_obj)
 reference - the reference object to register.
void JNICALL Java_java_lang_ref_Reference_register_phantom_ref (JNIEnv *the_env, jobject p_obj, jobject referent)
 reference - the reference object to register.
void JNICALL Java_java_lang_ref_Reference_register_soft_ref (JNIEnv *the_env, jobject p_obj, jobject referent)
 reference - the reference object to register.
void JNICALL Java_java_lang_ref_Reference_register_weak_ref (JNIEnv *the_env, jobject p_obj, jobject referent)
 reference - the reference object to register.


Define Documentation

#define GCExport   __declspec(dllexport)

GCExport is used to declare functions exported by GC.

#define BITS_PER_BYTE   8

#define NEXT_TO_HIGH_BIT_SET_MASK   (1<<((sizeof(unsigned) * BITS_PER_BYTE)-2))

#define NEXT_TO_HIGH_BIT_CLEAR_MASK   ~NEXT_TO_HIGH_BIT_SET_MASK

#define GC_OBJECT_ALIGNMENT   4

Granularity of object alignment.

Objects are aligned on 4 or 8 bytes. If they are aligned on 8 bytes then Arrays will be required to start on the indicated alignement. This means that for 8 byte alignment on the IA32 the header will look like this:

uint32 gc_header_lock_hash VTable *vt uint32 array_length uint32 padding the array elements.


Typedef Documentation

typedef void* Thread_Handle

Opaque handle for threads.


Function Documentation

int gc_init (  ) 

Is called by VM to start GC initialization sequence.

This function is expected to initialize the GC internal data structures. The VM should call this *before* any other calls to this interface The GC assumes that the VM is ready to support a GC if it calls this function.

void gc_test_safepoint (  ) 

May be called at various points the VM decides are GC-safe.

The GC may ignore this, or it may force a root set enumeration, or it may execute a full GC.

Note:
Optional debug interface.

Boolean gc_supports_frontier_allocation ( unsigned *  offset_of_current,
unsigned *  offset_of_limit 
)

If the GC supports a "bump-the-pointer" style allocation, where the GC's thread-local information contains a "current" pointer and a "limit" pointer, then it should return TRUE, and it should set *offset_of_current to be the offset into the GC thread block of the "current" pointer, and similar for *offset_of_limit and the "limit" pointer.

If not, then it should return FALSE.

void gc_vm_initialized (  ) 

This API is used by the VM to notify the GC that the VM has completed bootstrapping and initialization, and is henceforth ready to field requests for enumerating live references.

Prior to this function being called the GC might see some strange sights such as NULL or incomplete vtables. The GC will need to consider these as normal and work with the VM to ensure that bootstrapping works. This means that the GC will make few demands on the VM prior to this routine being called.

However, once called the GC will feel free to do stop-the-world collections and will assume that the entire gc_import.h interface is available and fully functioning.

If this routine is called twice the result is undefined.

void gc_wrapup (  ) 

This is called once the VM has no use for the heap or the garbage collector data structures.

The assumption is that the VM is exiting but needs to give the GC time to run destructors and free up memory it has gotten from the OS. After this routine has been called the VM can not relie on any data structures created by the GC.

Errors: If gc_enumerate_finalizable_objects has been called and gc_wrapup gc discovers an object that has not had it finalizer run then it will attempt to report an error.

void gc_add_root_set_entry ( Managed_Object_Handle ref,
Boolean  is_pinned 
)

Is called by the VM to enumerate the root reference.

void gc_add_compressed_root_set_entry ( uint32 *  ref,
Boolean  is_pinned 
)

Resembles gc_add_root_set_entry() but is passed the address of a slot containing a compressed reference.

void gc_add_weak_root_set_entry ( Managed_Object_Handle slot,
Boolean  is_pinned,
Boolean  is_short_weak 
)

Is called by the VM to enumerate weak root reference.

Parameters:
slot - a pointer to the slot, containing the weak root
is_pinned - TRUE denotes that object pointed-to from this slot should not be moved during garbage collection
is_short_weak - TRUE means that the weak root must be cleared before object becomes eligible for finalization

void gc_add_root_set_entry_managed_pointer ( void **  slot,
Boolean  is_pinned 
)

Enumerate a managed pointer.

The pointer can be declared as pinned. The pointer can point to the managed heap or any other area where data can be stored: stack or static fields. It is the responsibility of the GC to ignore pointers that are not in the managed heap.

Note:
Is this function needed for Java? -salikh

void gc_add_root_set_entry_interior_pointer ( void **  slot,
int  offset,
Boolean  is_pinned 
)

Call from the VM to the gc to enumerate an interior pointer.

**ref is a slot holding a pointer into the interior of an object. The base of the object is located at *ref - offset. The strategy employed is to place the slot, the object base and the offset into a slot_base_offset table. We then call gc_add_root_set_entry with the slot in the table holding the base of the object. Upon completion of the garbage collection the routine fixup_interior_pointers is called and the slot_base_offset table is traversed and the new interior pointer is calculated by adding the base of the object and the offset. This new interior pointer value is then placed into the slot.

This routine can be called multiple times with the same interiour pointer without any problems. The offset is checked to make sure it is positive but the logic is not dependent on this fact.

Note:
Optional function, never called by Java virtual machine.

Managed_Object_Handle gc_alloc_fast ( unsigned  size,
Allocation_Handle  type,
void *  thread_pointer 
)

This routine is the primary routine used to allocate objects.

It assumes nothing about the state of the VM internal data structures or the runtime stack. If gc_malloc_or_null is able to allocate the object without invoking a GC or calling the VM then it does so. It places p_vtable into the object, ensures that the object is zeroed and then returns a ManagedObject pointer to the object. If it is not able to allocate the object without invoking a GC then it returns NULL.

Parameters:
size - the size of the object to allocate. If the high bit set then various constraints as described above are placed on the allocation of this object.
type - a pointer to the vtable of the class being allocated. This routine will place this value in the appropriate slot of the new object.
thread_pointer - a pointer to the GC's thread-local space
This is like gc_malloc_or_null, except that it passes a pointer to the thread's GC-specific space as a third argument. This prevents the GC from having to immediately call vm_get_thread_curr_alloc_block() as its first task.

Note:
Rename of gc_malloc_with_thread_pointer().

Managed_Object_Handle gc_alloc ( unsigned  size,
Allocation_Handle  type,
void *  thread_pointer 
)

This routine is used to allocate an object.

See the above discussion on the overloading of size. {link allocation}

Parameters:
size - the size of the object to allocate. If the high bit set then various constraints as described above are placed on the allocation of this object.
type - a pointer to the vtable of the class being allocated. This routine will place this value in the appropriate slot of the new object.
thread_pointer - a pointer to the GC's thread-local space
Note:
Rename of gc_malloc_or_null_with_thread_pointer().

Managed_Object_Handle gc_pinned_malloc_noclass ( unsigned  size  ) 

For bootstrapping situations, when we still don't have a class for the object.

This routine is only available prior to a call to the call gc_vm_initialized. If it is called after the call to gc_vm_initialized then the results are undefined. The GC places NULL in the vtable slot of the newly allocated object.

The object allocated will be pinned, not finalizable and not an array.

Parameters:
size - the size of the object to allocate. The high bit will never be set on this argument.
Returns:
The newly allocated object.
Note:
Will be renamed to gc_alloc_pinned_noclass() to comply with accepted naming conventions.

Managed_Object_Handle gc_alloc_pinned ( unsigned  size,
Allocation_Handle  type,
void *  thread_pointer 
)

Allocate pinned forever object.

Note:
Not implemented.

Boolean gc_requires_barriers (  ) 

Returns:
TRUE if the GC requires write barriers before every store to a field of a reference type.

void gc_thread_init ( void *  gc_information  ) 

This routine is called during thread startup to set an initial nursery for the thread.

Note:
gc_thread_init and gc_thread_kill assume that the current thread is the one we are interested in. If we passed in the thread then these things could be cross inited and cross killed.

void gc_thread_kill ( void *  gc_information  ) 

This is called just before the thread is reclaimed.

VMEXPORT void vm_iterate_threads (  ) 

GC may call this function asynchronously any time it wants to get thread list.

This function signals VM to obtain thread lock and start thread iteration.

Note:
Not implemented.

void gc_iterate_thread ( Thread_Handle  thread  ) 

VM calls this method repeatedly to iterate over the list of java threads, initiated earlier by calling vm_iterate_threads().

Thread creation and termination is locked during this iteration.

gc may do one of the following: 1. store thread handle for later use 2. enumerate thread right now, while holding thread lock (using vm_suspend_thread(thread) and vm_enumerate_thread_root_set(thread)).

Note:
Not implemented.

VMEXPORT void vm_suspend_thread ( Thread_Handle  thread  ) 

GC calls this method to request VM to suspend an individual thread.

After the thread is suspended, 0 is returned on success

Thread may have been terminated already, in this case non-zero value is returned, and no additional actions are taken.

GC calls this VM function when it wants a thread to be suspended for stack enumeration or read/write barrier change.

blocks until synchronously call gc_thread_suspended(thread) or asynchronously delegate enumeration to thread (self-enumeration)

Note:
We need a way to signal that process of thread suspension is complete.

Not implemented.

void gc_thread_suspended ( Thread_Handle  thread  ) 

VM calls this GC callback when it's accomplished the requested operation of suspending a thread in gc-safe point.

May be called synchronously from the same context as vm_suspend_thread() in case of cross-enumeration, or may be called asynchronously from the specified thread context in case of self-enumeration.

After this function completes, the thread is resumed automatically.

GC is expected to call a limited subset of GC-VM interface functions from this callback:

Note:
Not implemented.

VMEXPORT void vm_enumerate_thread_root_set ( Thread_Handle  thread  ) 

GC calls this function to command VM to enumerate a thread, which was earlier suspenden using vm_suspend_thread().

In response to this call, VM repeatedly calls gc_add_root_set_entry() to enumerate thread stacks and local handles

Note:
Not implemented.

VMEXPORT void vm_enumerate_global_root_set (  ) 

GC calls this function to command VM to enumerate global slots.

During enumeration of global root set, either all threads need to be suspended, or write barrier installed.

Apparently some operations should be blocked in VM, like class loading, which itself creates new global reference slots. It is not clear to me if we should require stopping the world to use this function or introduce new system-wide lock on operations that change the number of global reference slots.

This function calls gc_add_root_set_entry() for all global reference slots.

Note:
Not implemented.

void gc_force_gc (  ) 

API for the VM to force a GC, typically in response to a call to java.lang.Runtime.gc.

int64 gc_total_memory (  ) 

API for the VM to determine the current GC heap size, typically in response to a call to java.lang.Runtime.totalMemory.

int64 gc_max_memory (  ) 

API for the VM to determine the maximum GC heap size, typically in response to a call to java.lang.Runtime.maxMemory.

int64 gc_free_memory (  ) 

API for the VM to get an approximate view of the free space, typically in response to a call to java.lang.Runtime.freeMemory.

Boolean gc_is_object_pinned ( Managed_Object_Handle  obj  ) 

Returns:
TRUE if the object is pinned.

Routine to support the functionality required by JNI to see if an object is pinned.

void gc_class_prepared ( Class_Handle  ch,
VTable_Handle  vth 
)

The VM calls this function after a new class has been prepared.

The GC can use a call interface to gather relevant information about that class and store it in area of the VTable that is reserved for GC. The information cached in the VTable should be used by the GC in performance sensitive functions like object scanning.

int64 gc_get_collection_count (  ) 

The number of collections that have been executed by this collector. A value of -1 means that collection counts are undefined for this collector.

Returns:
The number of collections executed.

int64 gc_get_collection_time (  ) 

The approximate, cumulative time (in microseconds) spent executing collections for this collector.

Returns:
The time spent collecting garbage.

Boolean gc_supports_compressed_references (  ) 

Returns:
TRUE if references within objects and vector elements are to be treated as offsets rather than raw pointers.

void gc_write_barrier ( Managed_Object_Handle  p_base_of_obj_with_slot  ) 

These interfaces are marked for replacement for the IPF by the following gc_heap_write_mumble interface.

Deprecated:
Will be removed soon.

void gc_heap_wrote_object ( Managed_Object_Handle  p_base_of_object_just_written  ) 

There are two flavors for historical reasons.

The compiler for IA32 will produce code for the version using an offset.

Deprecated:
Will be removed soon.

void gc_heap_write_global_slot ( Managed_Object_Handle p_slot,
Managed_Object_Handle  value 
)

By calling this function VM notifies GC that a heap reference was written to global slot.

There are some global slots that are shared by different threads. Write barriers implementation needs to know about writes to these slots. One example of such slots is in the string pools used by the class loader.

void gc_heap_write_global_slot_compressed ( uint32 *  p_slot,
Managed_Object_Handle  value 
)

VM should call this function on heap reference writes to global slots.

The "compressed" versions of the functions support updates to slots containing compressed references that are heap offsets; these functions handle details of converting raw reference pointers to compressed references before updating slots.

void gc_heap_write_ref ( Managed_Object_Handle  p_base_of_object_with_slot,
unsigned  offset,
Managed_Object_Handle  value 
)

VM should call this function on heap reference writes to heap objects.

void gc_heap_slot_write_ref ( Managed_Object_Handle  p_base_of_object_with_slot,
Managed_Object_Handle p_slot,
Managed_Object_Handle  value 
)

VM should call this function on heap reference writes to heap objects.

void gc_heap_slot_write_ref_compressed ( Managed_Object_Handle  p_base_of_object_with_slot,
uint32 *  p_slot,
Managed_Object_Handle  value 
)

VM should call this function on heap reference writes to heap objects.

void gc_pin_object ( Managed_Object_Handle p_object  ) 

Pin object.

void gc_unpin_object ( Managed_Object_Handle p_object  ) 

Unpin object.

int32 gc_get_hashcode ( Managed_Object_Handle  object  ) 

Get identity hashcode.

Managed_Object_Handle gc_get_next_live_object ( void *  iterator  ) 

Iterate all live objects in heap.

Should be use only in classloader for class unloading purposes.

void gc_iterate_heap (  ) 

Iterates all objects in the heap.

This function calls vm_iterate_object() for each iterated object. Used for JVMTI Heap Iteration. Should be called only in stop-the-world setting

See also:
vm_gc.h.vm_iterate_object()

void gc_finalize_on_exit (  ) 

Moves all finalizable objects to vm finalization queue.

void gc_set_mutator_block_flag (  ) 

Sets the mutator need block flag in case of heavy finalizable object load.

Boolean gc_clear_mutator_block_flag (  ) 

Clears the mutator need block flag when heavy finalizable object load lightens.

Boolean gc_supports_class_unloading (  ) 

Returns:
TRUE if references within objects and vector elements are to be treated as offsets rather than raw pointers.

void JNICALL Java_java_lang_ref_Reference_enqueue_reference ( JNIEnv the_env,
jobject  p_obj 
)

reference - the reference object to register.

referent - the referent of the reference object that is to be retrieved with the get method.

The weak reference code written in Java and the support code provide by the VM must agree on what the layout of a Java.lang.ref.Reference object looks like and agree that any subclassing will only append fields to the agreed upon layout. This seems reasonable.

In addition the support code will have exclusive knowledge and control of a single field (called the_referent) which holds the reference to the target object. The java code will assume that this field is a read only integer and should not be traced by the gc. The Java.lang.ref.ReferenceQueue layout needs to also be known by the supporting code so that it can move reference objects onto the queues at the appropriate times. The Java code uses normal mechanisms to load the Reference classes and to create a reference.

The constructor code however needs to call the appropriate register function listed below based upon whether we have a soft, weak, or phantom reference. The VM support code will fill in the referent field. The routine gc_get_referent will return the value in this field.

Note:
The phantom reference method get will not use the gc_get_referent but instead just return NULL as required by the spec.

XXX Why are they in gc_export.h? -salikh

jobject JNICALL Java_java_lang_ref_Reference_get ( JNIEnv the_env,
jobject  p_obj 
)

reference - the reference object to register.

referent - the referent of the reference object that is to be retrieved with the get method.

The weak reference code written in Java and the support code provide by the VM must agree on what the layout of a Java.lang.ref.Reference object looks like and agree that any subclassing will only append fields to the agreed upon layout. This seems reasonable.

In addition the support code will have exclusive knowledge and control of a single field (called the_referent) which holds the reference to the target object. The java code will assume that this field is a read only integer and should not be traced by the gc. The Java.lang.ref.ReferenceQueue layout needs to also be known by the supporting code so that it can move reference objects onto the queues at the appropriate times. The Java code uses normal mechanisms to load the Reference classes and to create a reference.

The constructor code however needs to call the appropriate register function listed below based upon whether we have a soft, weak, or phantom reference. The VM support code will fill in the referent field. The routine gc_get_referent will return the value in this field.

Note:
The phantom reference method get will not use the gc_get_referent but instead just return NULL as required by the spec.

XXX Why are they in gc_export.h? -salikh

void JNICALL Java_java_lang_ref_Reference_register_phantom_ref ( JNIEnv the_env,
jobject  p_obj,
jobject  referent 
)

reference - the reference object to register.

referent - the referent of the reference object that is to be retrieved with the get method.

The weak reference code written in Java and the support code provide by the VM must agree on what the layout of a Java.lang.ref.Reference object looks like and agree that any subclassing will only append fields to the agreed upon layout. This seems reasonable.

In addition the support code will have exclusive knowledge and control of a single field (called the_referent) which holds the reference to the target object. The java code will assume that this field is a read only integer and should not be traced by the gc. The Java.lang.ref.ReferenceQueue layout needs to also be known by the supporting code so that it can move reference objects onto the queues at the appropriate times. The Java code uses normal mechanisms to load the Reference classes and to create a reference.

The constructor code however needs to call the appropriate register function listed below based upon whether we have a soft, weak, or phantom reference. The VM support code will fill in the referent field. The routine gc_get_referent will return the value in this field.

Note:
The phantom reference method get will not use the gc_get_referent but instead just return NULL as required by the spec.

XXX Why are they in gc_export.h? -salikh

void JNICALL Java_java_lang_ref_Reference_register_soft_ref ( JNIEnv the_env,
jobject  p_obj,
jobject  referent 
)

reference - the reference object to register.

referent - the referent of the reference object that is to be retrieved with the get method.

The weak reference code written in Java and the support code provide by the VM must agree on what the layout of a Java.lang.ref.Reference object looks like and agree that any subclassing will only append fields to the agreed upon layout. This seems reasonable.

In addition the support code will have exclusive knowledge and control of a single field (called the_referent) which holds the reference to the target object. The java code will assume that this field is a read only integer and should not be traced by the gc. The Java.lang.ref.ReferenceQueue layout needs to also be known by the supporting code so that it can move reference objects onto the queues at the appropriate times. The Java code uses normal mechanisms to load the Reference classes and to create a reference.

The constructor code however needs to call the appropriate register function listed below based upon whether we have a soft, weak, or phantom reference. The VM support code will fill in the referent field. The routine gc_get_referent will return the value in this field.

Note:
The phantom reference method get will not use the gc_get_referent but instead just return NULL as required by the spec.

XXX Why are they in gc_export.h? -salikh

void JNICALL Java_java_lang_ref_Reference_register_weak_ref ( JNIEnv the_env,
jobject  p_obj,
jobject  referent 
)

reference - the reference object to register.

referent - the referent of the reference object that is to be retrieved with the get method.

The weak reference code written in Java and the support code provide by the VM must agree on what the layout of a Java.lang.ref.Reference object looks like and agree that any subclassing will only append fields to the agreed upon layout. This seems reasonable.

In addition the support code will have exclusive knowledge and control of a single field (called the_referent) which holds the reference to the target object. The java code will assume that this field is a read only integer and should not be traced by the gc. The Java.lang.ref.ReferenceQueue layout needs to also be known by the supporting code so that it can move reference objects onto the queues at the appropriate times. The Java code uses normal mechanisms to load the Reference classes and to create a reference.

The constructor code however needs to call the appropriate register function listed below based upon whether we have a soft, weak, or phantom reference. The VM support code will fill in the referent field. The routine gc_get_referent will return the value in this field.

Note:
The phantom reference method get will not use the gc_get_referent but instead just return NULL as required by the spec.

XXX Why are they in gc_export.h? -salikh

unsigned int gc_time_since_last_gc (  ) 

API for the VM to get the time since the last GC happened.

Returns an unsigned long value in milliseconds.

Note:
Is this call really needed in GC interface? -salikh 2005-05-12

void* gc_heap_base_address (  ) 

Returns:
The base address of the heap.

API for VM to determine the starting and ending adddresses of the heap.

void* gc_heap_ceiling_address (  ) 

Returns:
The top address of the heap.


Genereated on Tue Mar 11 19:25:22 2008 by Doxygen.

(c) Copyright 2005, 2008 The Apache Software Foundation or its licensors, as applicable.