/**
 * @file
 * These are the functions that a GC may call.

/**
 * @return the number of bytes allocated by VM in VTable
 *         for use by GC.
 */
VMEXPORT size_t vm_number_of_gc_bytes_in_vtable();

/**
 * @return the number of bytes allocated by VM in thread-local
 *         storage for use by GC.
 */
VMEXPORT size_t vm_number_of_gc_bytes_in_thread_local();

/**
 * @return the pointer to thread-local area of current thread.
 */
VMEXPORT void *vm_get_gc_thread_local();


/**
 * Acquire the lock that guards all GC-related operations in the VM.
 * If the lock can't be acquired the thread waits until the lock is available.
 * This operation marks the current thread as being safe for root set
 * enumeration.
 */
VMEXPORT void vm_gc_lock_enum();


/**
 * Release the system-wide lock acquired by vm_gc_lock_enum().
 * The thread is marked as unsafe for root set enumeration.
 */
VMEXPORT void vm_gc_unlock_enum();


/**
 * GC calls this function to command VM to start root set enumeration.
 *
 * Root set enumeration for all managed threads.
 */
VMEXPORT void vm_enumerate_root_set_all_threads();


/**
 * GC calls this function to restart managed threads after root set 
 * enumeration is complete.
 *
 * This function resumes all threads suspended by 
 * vm_enumerate_root_set_all_threads()
 */
VMEXPORT void vm_resume_threads_after();


/**
 * thread state as concerns root set enumeration.
 */
enum safepoint_state {
    nill = 0,

    /** 
     * thread is stopped for root set enumeration,
     * as is the whole world (all managed threads).
     * For sapphire just means sapphire is running.
     */
    enumerate_the_universe,

    /** 
     * thread is stopped for root set enumeration
     */
    java_suspend_one_thread,

    /**
     * thread is stopped by java debugger.
     */
    java_debugger
};

/**
 * @return thread safepoint state.
 */
VMEXPORT enum safepoint_state get_global_safepoint_status();

/**
 * @return TRUE if no apparent trash was found in the object.
 * 
 * Used for debugging.
 */
VMEXPORT Boolean verify_object_header(void *ptr);


/*
 * *****
 * *
 * *  Routines to support finalization of objects.
 * * 
 * *****
 */

/**
 * GC should call this function when an object becomes
 * "f-reachable, finalizable"
 * The VM later finalizes those objects in a way that
 * is not part of this interface.
 *
 * VM must not call finalizer immediately to prevent
 * deadlocks in user code, because this functions
 * may be called during the stop-the-world phase.
 */
VMEXPORT void vm_finalize_object(Managed_Object_Handle p_obj);

/**
 * GC should call this function when an phantom reference object
 * is to be enqueued, i.e. when the reference is not reachable anymore.
 */
VMEXPORT void vm_enqueue_reference(Managed_Object_Handle p_obj);

enum WeakReferenceType {
    NOT_REFERENCE = 0,
    WEAK_REFERENCE,
    SOFT_REFERENCE,
    PHANTOM_REFERENCE
};

/**
 * Returns non-zero value if the class represented by Class_Handle
 * is a descendant of java.lang.ref.Reference. The particular type
 * of reference (weak, soft or phantom) is encoded by the return 
 * value of WeakReferenceType.
 */
VMEXPORT WeakReferenceType class_is_reference(Class_Handle clss);

/**
 * Returns the offset of the referent field 
 * in the java.lang.ref.Reference object.
 *
 * clss is assumed to represent the reference object,
 * i.e. class_is_reference() returned non-zero value.
 *
 * @note the returned value is most probably a constant,
 *       and is not dependent on the clss.
 *
 * @note this interface allows only one non-strong (i.e. weak
 *       soft or phantom) reference per object.
 *       It seems to be sufficient for JVM Spec.
 */
VMEXPORT int class_get_referent_offset(Class_Handle clss);


#define CL_PROP_ALIGNMENT_MASK      0x00FFF     ///< @see class_properties
#define CL_PROP_NON_REF_ARRAY_MASK  0x01000     ///< @see class_properties
#define CL_PROP_ARRAY_MASK          0x02000     ///< @see class_properties
#define CL_PROP_PINNED_MASK         0x04000     ///< @see class_properties
#define CL_PROP_FINALIZABLE_MASK    0x08000     ///< @see class_properties


/**
 * @section class_properties Class properties flags
 * 3322|2222|2222|1111|1111|1100|0000|0000
 * 1098|7654|3210|9876|5432|1098|7654|3210
 *                          ^^^^^^^^^^^^^^------ CL_PROP_ALIGNMENT_MASK
 *                        ^--------------------- CL_PROP_NON_REF_ARRAY_MASK
 *                       ^---------------------- CL_PROP_ARRAY_MASK
 *                      ^----------------------- CL_PROP_PINNED_MASK
 *                     ^------------------------ CL_PROP_FINALIZABLE_MASK 
 */


/**
 * extract the recursion counter from object lockword.
 */
#define P_RECURSION_BYTE(x)       ( (uint8 *)(((x)->get_obj_info_addr())) + 1 )  

#ifdef GC_PUBLIC_PRIVATE

/**
 * mask of recursion counter
 */
#define RECURSION_MASK 0x7f

/**
 * mask of recursion counter shifted to its position in lockword.
 */
#define RECURSION_MASK_SHIFTED 0x7f00
#define PUBLIC_PRIVATE_MASK 0x80