Runtime Support Functions

Allocation

• void *allocate(int nbytes);
  
  Allocate nbytes from the heap. The space is reclaimed automatically by the garbage collector when there are no references left to it.
  
  
• Object construct(Class c);
  
  Allocate an instance of c and initialize it with the default (zero-argument) initializer if there is one. If there is no default initializer an exception is thrown.
  
  
• Object new(Class c);
  
  Allocate an instance of c but do not initialize it. It is up to the caller to call one of the initializer functions.
  
  
• Object anewarray(Class c, int nelem);
  
  Allocate an array with nelem elements which can hold instances of c.
  
  
• Object vmnewarray(Class c, int arraydim, int ndim, /*d1,d2,*/...)
  
  Allocates a multi-dimensional array of elements of type Class c.

Helpers

• struct mt_generic * findinterface(Object o, int signaturehash)();
  
  Return a pointer to the method table structure for the function that implements an interface method in an object given the hash code of the interface. The hash code can be found by looking at the generated header file for the class. If no matching interface is found an exception is thrown.
  
  
• int instanceof(Object o, Class c, int ndim)
  
  Returns true (non-zero) if Object o is an instance of an n-dimensional array of Class c. The Object o cannot be null, and Class c cannot be an array class. For Example:

        instanceof(o, &cl_java_lang_String.C, 1)
  

  returns true if o is a one dimensional array of strings and

        instanceof(o, &cl_java_lang_Throwable.C, 0)
  

  returns true if o is an object that extends the java.lang.Throwable class.
  
  
• void terminate(int status);
  
  Exit with the specified exit status.
  
  
• char *cstring(struct in_java_lang_String *str);
  
  Translates a java.lang.String into a C string (in ASCII-zero format). The returned string will be garbage collected when it is no longer referenced.
  Similar to Sun's char *makeCString(Hjava_lang_String *)
  
  
• struct in_java_lang_String *javastring(char *cstr);
  
  Translate a C string (in ASCII-zero format) into a java.lang.String object.
  Similar to Sun's Hjava_lang_String *makejavaString(char *str, int len)

File Operations

• Void fd_open(struct in_java_io_FileDescriptor *fd, Object unameo, int oflags);
• Int fd_read_char(struct in_java_io_FileDescriptor *fd);
• Int fd_read_bytes(struct in_java_io_FileDescriptor *fd, Object Harg2, Int off, Int len);
• Void fd_close(struct in_java_io_FileDescriptor *fd);
• Void fd_write_char(struct in_java_io_FileDescriptor *fd, Int arg2);
• Void fd_write_bytes(struct in_java_io_FileDescriptor *fd, Object Harg2, Int off, Int len);
• int name_stat(struct in_java_lang_String *uname, struct stat *buf);
• Boolean name_access(struct in_java_lang_String *uname, int amode);
• int java_fd(int unixfd);
• int unix_fd(int javafd);
• int java_fd_valid(int javafd);
• void set_address(struct in_java_net_InetAddress *jaddr, Int port, struct sockaddr_in *uaddr);

Throw Operations

• void athrow(Object o)
  
  Throw an object o. The object should be an instance of Class java.lang.Throwable.
  
  
• void throwMesg(Class etype, char *mesg, ...);
  
  Create and throw an exception of type etype and optionally (if mesg is non-null) fill in a message. The message is formatted in the style of printf.

Monitor Operations

• void monitorenter(Object obj, struct mythread *thr, int val, volatile int *resp);
• void enterclass(Class c, struct mythread *thr, int val, volatile int *resp);
  
  Enter the monitor associated with obj or c. The thr argument is the current thread as returned by mythread(). The value val is stored in the location pointed to by resp atomically with the grabbing of the monitor lock -- If the value is stored in the given location then the monitor has been entered successfully.
  
  
• void monitorexit(Object obj, struct mythread *thr, int val, volatile int *resp);
• void exitclass(Class c, struct mythread *thr, int val, volatile int *resp);
  
  Exit the monitor associated with obj or c. Atomically set the location pointed to by resp with val. The argument thr should be the current thread as returned by mythread().
  
  
• void monitorwait(Object obj, Long millis);
  
  Wait to be signaled in the monitor associated with obj. The monitor lock for obj should already be held or an exception is thrown. If millis is non-zero it is used as a maximum amount of time to wait.
  
  
• void monitornotify(Object obj);
• void monitornotifyall(Object obj);
  
  Signal (notify) one or all threads waiting in the monitor for obj. The monitor lock for obj should already be held by the current thread or an exception is thrown.

Threads

• struct mythread *mythread();
  
  Return a pointer to the current thread's per-thread data.

Thread Primitives

The sthreads package exports three data types:

• threads
• mutual exclusion locks
• condition variables

Sthread Thread Operations

• void sthread_create(struct in_java_lang_Thread *o);
  
  Create and start a thread for thread object o.
  
  
• struct tcb * sthread_current();
  
  Return the thread control block associated with the currently running thread.
  
  
• void sthread_yield();
  
  Potentially yield the CPU to another thread of the same priority.
  
  
• void sthread_sleep(Long millis);
  
  Put the current thread to sleep for the specified number of milliseconds.
  
  
• void sthread_suspend(struct in_java_lang_Thread *o);
  
  Suspend the given thread as soon as possible. (The suspend and return from sthread_suspend could be delayed until the thread being suspended releases critical internal locks.)
  
  
• void sthread_resume(struct in_java_lang_Thread *o);
  
  Resume the given thread if it was suspended.
  
  
• void sthread_setpriority(struct in_java_lang_Thread *o, int prio);
  
  Set the priority associated with the given thread to the given priority number.
  
  
• void sthread_stop(struct in_java_lang_Thread *o, Object e);
  
  Cause the given thread to asynchronously throw the exception specified by e. (The throw and return from sthread_stop could be delayed until the thread being stopped releases critical internal locks.)
  
  
• void sthread_exit();
  
  Wait for all non-daemon threads to complete.

The following routines are used to prevent a thread from being killed for a short amount of time. They are meant to be used to protect threads from being killed or suspended while holding critical internal locks, such as the monitor creation lock and the allocation lock. These routines should only be used sparingly, for short amounts of time, and with careful consideration. Inside of the critical sections defined using these routines, the current thread cannot be killed or suspended by the API.

• void sthread_dontkill_start(struct mythread *thr);
  
• void sthread_dontkill_end(struct mythread *thr);
  
  Denote the start and end of a critical section in which the current thread should not be suspended or killed because it may be holding an internal lock.
  
  
• int sthread_dontkill_p(struct mythread *thr);
  
  Return 0 if the current thread can currently be killed or suspended, and non-zero otherwise.

Sthread Mutex Operations

• void sthread_mutex_init(struct sthread_mutex *m);
  
  Initialize the mutex pointed to by m.
  
  
• void sthread_mutex_lock(struct sthread_mutex *m);
  
  Acquire the mutex pointed to by m.
  
  
• void sthread_mutex_unlock(struct sthread_mutex *m);
  
  Release the mutex pointed to by m.
  
  
• void sthread_mutex_destroy(struct sthread_mutex *m);
  
  Destroy any related space used by the mutex pointed to by m. The results of operations on a destroyed mutex are undefined.
  
  
• void sthread_cond_init(struct sthread_cond *c);
  
  Initialize the condition variable pointed to by c.
  
  
• void sthread_cond_wait(struct sthread_cond *c, struct sthread_mutex *m, Long timeout);
  
  Atomically release the mutex m and wait at most timeout milliseconds for someone to signal the condition c. A thread re-acquires the mutex m prior to successfully returning from sthread_cond_wait. Timeout expiration results in sthread_cond_wait throwing an exception.
  
  
• void sthread_cond_signal(struct sthread_cond *c);
  
  Signal one thread waiting on the condition c that it should stop waiting. Threads calling sthread_cond_signal should acquire the mutex used in calls to sthread_cond_wait prior to signaling a condition.
  
  
• void sthread_cond_broadcast(struct sthread_cond *c);
  
  Signal all threads waiting on the condition c that it should stop waiting. Threads calling sthread_cond_broadcast should acquire the mutex used in calls to sthread_cond_wait prior to broadcasting a condition.
  
  
• void sthread_cond_destroy(struct sthread_cond *c);
  
  Destroy any related storage used by the condition pointed to by c. The results of operations on a destroyed condition are undefined.

Sthread Miscellaneous Operations

• void sthread_init();
  
  Initialize the sthread package.
  
  
• void sthread_got_exception(void);
  
  A callback from the exception handling code used to notify the thread that it received an exception. This callback is used to clean up after receipt of an asynchronous exception.