thread.h

java 1.1 gemini 08_16

#define MAX_JAVA_PRIORITY  10        /* These constants must be the same */
#define NORM_JAVA_PRIORITY 5         /* as those defined in Thread.java */
#define MIN_JAVA_PRIORITY  1

/*=========================================================================
 * Global multitasking operations
 *=======================================================================*/

void storeExecutionEnvironment(THREAD thisThread); /* Context save */
void loadExecutionEnvironment(THREAD thisThread);  /* Context restore */
bool_t SwitchThread(void);

/*=========================================================================
 * Thread data structures and operations
 *=======================================================================*/

/*=========================================================================
 * Thread instance data structures:
 *
 * One of the structures below is instantiated
 * for every thread (task) in the system:
 *
 * - THREAD is an internal (VM-level) structure that is used for storing
 *   the necessary information for implementing preemptive task
 *   switching independently of Java-level stuff. Active THREADs
 *   are singly-linked to a linear list that contains all the
 *   active threads in the system.
 *
 * - JAVATHREAD is mapped one to one to the instance structure
 *   defined in Java class 'Thread.java'. It is referred to from
 *   THREAD.
 *
 * Why do we need two separate structures? Well, since class 'Thread.java'
 * may be subclassed, we cannot add the necessary implementation-level
 * fields directly to JAVATHREAD, but we must use a separate struct instead!
 * Also, we wanted to keep the thread system implementation independent
 * of the Java language for portability reasons.
 *
 * Note that a JAVATHREAD must be a full-fledged Java object instance.
 * Thus its beginning must be identical with that of INSTANCE.
 *
 * IMPORTANT: Do not change the order of the data elements below
 * unless you do the corresponding modifications also in the data
 * fields of class java.lang.Thread!!
 *
 *=======================================================================*/

/* THREAD */
struct threadQueue {
    THREAD nextAliveThread;  /* Queue of threads that are alive; */
    THREAD nextThread;       /* Queue of runnable or waiting threads */
    JAVATHREAD javaThread;   /* Contains Java-level thread information */
    long   timeslice;        /* Calculated from Java-level thread priority */
    STACK stack;             /* The execution stack of the thread */

    /* The following four variables are used for storing the */
    /* virtual machine registers of the thread while the thread */
    /* is runnable (= active but not currently given processor time). */
    /* In order to facilitate garbage collection, we store pointers */
    /* to execution stacks as offsets instead of real pointers. */
    BYTE* ipStore;           /* Program counter temporary storage (pointer) */
    FRAME fpStore;           /* Frame pointer temporary storage (pointer) */
    cell* spStore;           /* Execution stack pointer temp storage (ptr) */
    cell* nativeLp;          /* Used in KNI calls to access local variables */

    MONITOR monitor;         /* Monitor whose queue this thread is on */
    short monitor_depth;

    THREAD nextAlarmThread;  /* The next thread on this queue */
    long   wakeupTime[2];    /* We can't demand 8-byte alignment of heap
                                objects  */
    void (*wakeupCall)(THREAD); /* Callback when thread's alarm goes off */
    struct {
        int depth;
        long hashCode;
    } extendedLock;          /* Used by an object with a FASTLOCK */

#if (ASYNCHRONOUS_NATIVE_FUNCTIONS || USE_KNI)
    char* pendingException;  /* Name of class for which the thread */
                             /* has an exception pending */
    char* exceptionMessage;  /* Message string for the exception */
#endif

    enum {
        THREAD_JUST_BORN = 1,     /* Not "start"ed yet */
        THREAD_ACTIVE = 2,        /* Currently running, or on Run queue */
        THREAD_SUSPENDED = 4,     /* Waiting for monitor or alarm */
        THREAD_DEAD = 8,          /* Thread has quit */
        THREAD_MONITOR_WAIT = 16,
        THREAD_CONVAR_WAIT = 32,
        THREAD_DBG_SUSPENDED = 64
    } state;

#ifdef CLDC11
    bool_t isPendingInterrupt;    /* Don't perform next sleep or wait */
#endif /* CLDC11 */

#if ENABLE_JAVA_DEBUGGER
    bool_t isStepping;       /* Single stepping this thread */
    bool_t isAtBreakpoint;
    bool_t needEvent;
    CEModPtr debugEvent;

    ByteCode nextOpcode;
    struct singleStep_mod stepInfo;
    int debugSuspendCount; /* Number of times debugger suspended thread */
#endif /* ENABLE_JAVA_DEBUGGER */

}; /* End of THREAD data structure definition */

#define SIZEOF_THREAD        StructSizeInCells(threadQueue)

/* JAVATHREAD
 *
 * DANGER: This structure is mapped one-to-one with Java thread instances
 *         The fields should be the same as in 'java.lang.Thread'
*/
struct javaThreadStruct {    /* (A true Java object instance) */

    COMMON_OBJECT_INFO(INSTANCE_CLASS)
    long       priority;     /* Current priority of the thread */
    THREAD     VMthread;     /* Backpointer to internal THREAD. */
    INSTANCE   target;       /* Pointer to the object whose 'run' */
#ifdef CLDC11
    SHORTARRAY name;         /* Name of the thread (new in CLDC 1.1) */
                             /* The name is stored as a Java char array */
#endif /* CLDC11 */
};

#define SIZEOF_JAVATHREAD    StructSizeInCells(javaThreadStruct)

/*=========================================================================
* Public operations on thread instances
 *=======================================================================*/

/*     Constructors and destructors */
void   InitializeThreading(INSTANCE_CLASS, ARRAY);
THREAD getVMthread(JAVATHREAD_HANDLE);

/*     Thread activation and deactivation operations */
void   initThreadBehavior(THREAD, METHOD, OBJECT);
void   startThread(THREAD);
void   stopThread(void);
#ifdef CLDC11
void   interruptThread(THREAD);
void   handlePendingInterrupt(void);
#endif /* CLDC11 */
void   DismantleThread(THREAD);
void   suspendThread(void);
void   suspendSpecificThread(THREAD);
void   resumeThread(THREAD);
void   resumeSpecificThread(THREAD);
int    activeThreadCount(void);
int    isActivated(THREAD);
THREAD removeFirstRunnableThread(void);

/*     Asynchronous threading operations (optional) */
#if ASYNCHRONOUS_NATIVE_FUNCTIONS
void   asyncFunctionProlog(void);
void   asyncFunctionEpilog(THREAD);
void   RundownAsynchronousFunctions(void);
void   RestartAsynchronousFunctions(void);
#else
#define RundownAsynchronousFunctions() /**/
#define RestartAsynchronousFunctions() /**/
#endif

#if ASYNCHRONOUS_NATIVE_FUNCTIONS
void enterSystemCriticalSection(void);
void exitSystemCriticalSection(void);
#define START_CRITICAL_SECTION { enterSystemCriticalSection();
#define END_CRITICAL_SECTION   exitSystemCriticalSection(); }
#else
#define START_CRITICAL_SECTION {
#define END_CRITICAL_SECTION   }
#endif

#ifndef NATIVE_FUNCTION_COMPLETED
#define NATIVE_FUNCTION_COMPLETED()  /* do nothing by default */
#endif

/* Thread debugging operations */
#if INCLUDEDEBUGCODE
void printFullThreadStatus(void);
#else
#define printFullThreadStatus()
#endif

/*=========================================================================
 * Timer data structures and operations
 *=======================================================================*/

/* Threads waiting for a timer interrupt */
extern THREAD TimerQueue;

/*=========================================================================
 * Timer operations
 *=======================================================================*/

void   registerAlarm(THREAD thread, long64 delta, void (*)(THREAD));
void   checkTimerQueue(ulong64 *nextTimerDelta);
bool_t inTimerQueue(THREAD thread);

/*=========================================================================
 * Monitor data structures and operations
 *=======================================================================*/

extern MONITOR MonitorCache;

/*=========================================================================
 * COMMENTS:
 * KVM has a general, machine-independent monitor implementation
 * that is used when executing synchronized method calls and
 * MONITORENTER/MONITOREXIT bytecodes.
 *
 * Monitors are always attached to individual object instances
 * (or class instances when executing synchronized static method
 * calls). Each monitor structure holds a wait queue in which
 * those threads who are waiting for the monitor to be released
 * are stored. A democratic FCFS (first-come-first-serve) scheduling
 * model is used for controlling wait queues. Threads are
 * automatically suspended while they wait in a monitor.
 *
 *=========================================================================
 * NEW COMMENTS FOR 1.0.3:
 *
 * KVM 1.0.3 has a new monitor system that allocates real
 * monitor objects only when they are really needed.
 * If a monitor is uncontended (only one thread needs
 * to acquire the monitor), no monitor object is allocated
 * at all. Rather, the mch (monitorOrHashCode) field of the
 * object is used for storing information about the monitor
 * that is associated with that object.  The mch field can
 * be in four different states depending on the status of
 * the system.  The different mch states are explained below.
 *=======================================================================*/

/* These are the possible meanings of the low two bits of an object's .mhc
 * field.  If the upper 30 bits point to a thread or monitor, the low two
 * bits are implicitly zero.
 */
enum MHC_Tag_TypeCode {
    /* The upper 30 bits are the hash code. 0 means no hash code */
    MHC_UNLOCKED  = 0,

    /* The upper 30 bits are the thread that locks this object.
     * This object implicitly has no hash code, and the locking
     * depth is 1.  There is no other contention for this object */
    MHC_SIMPLE_LOCK  = 1,

    /* The upper 30 bits are the thread that locks this object.
     * thread->extendedLock.hashCode & thread->extendedLock->depth
     * contain this object's hashCode and and locking depth.
     * There is no other contention for this object. */
    MHC_EXTENDED_LOCK = 2,

    /* The upper 30 bits point to a MONITOR object */
    MHC_MONITOR  = 3
};

/* These macros are used to extract the .mhc field of the object in a
 * meaningful way.
 */
#define OBJECT_MHC_TAG(obj) ((enum MHC_Tag_TypeCode)((obj)->mhc.hashCode & 0x3))
#define OBJECT_MHC_MONITOR(obj)  \
             ((MONITOR)(((char *)(obj)->mhc.address) - MHC_MONITOR))
#define OBJECT_MHC_SIMPLE_THREAD(obj) \
             ((THREAD)(((char *)(obj)->mhc.address) - MHC_SIMPLE_LOCK))
#define OBJECT_MHC_EXTENDED_THREAD(obj) \
             ((THREAD)(((char *)(obj)->mhc.address) - MHC_EXTENDED_LOCK))

/* Utility macros for checking and setting lock values */
#define IS_EXTENDED_LOCK_FREE(thread) (thread->extendedLock.depth == 0)
#define FREE_EXTENDED_LOCK(thread)    (thread->extendedLock.depth = 0)

/* MONITOR */
struct monitorStruct {
    THREAD owner;          /* Current owner of the monitor */
    THREAD monitor_waitq;
    THREAD condvar_waitq;
    long   hashCode;       /* Hash code of original object */
    long   depth;          /* Nesting depth: how many times the */
                           /* monitor has been entered recursively */
#if INCLUDEDEBUGCODE
    OBJECT object;
#endif
};

#define SIZEOF_MONITOR     StructSizeInCells(monitorStruct)

/* These are the possible return values from monitorEnter, monitorExit,
 * monitorWait, and monitorNotify.
 */
enum MonitorStatusType {
    MonitorStatusOwn,       /* The process owns the monitor */
    MonitorStatusRelease,   /* The process has released the monitor */
    MonitorStatusWaiting,   /* The process is waiting for monitor/condvar */
    MonitorStatusError      /* An error has occurred */
};

/*=========================================================================
 * Monitor operations
 *=======================================================================*/

enum MonitorStatusType  monitorEnter(OBJECT object);
enum MonitorStatusType  monitorExit(OBJECT object, char **exceptionName);
enum MonitorStatusType  monitorWait(OBJECT object, long64 time);
enum MonitorStatusType  monitorNotify(OBJECT object, bool_t wakeAll);

/* Remove any monitor associated with this object */
void clearObjectMonitor(OBJECT object);

/* If this object has a monitor or monitor-like structure associated with it,
 * then return the address of its "hash code" field.  This function may GC
 * if it returns a non-NULL value.
 */
long* monitorHashCodeAddress(OBJECT object);

#if INCLUDEDEBUGCODE
void printAllMonitors(void);
#endif

#endif /* __THREAD_H__ */