SunSPOT API V3.0


com.sun.squawk
Class VM

java.lang.Object
  extended by com.sun.squawk.VM

public class VM
extends Object

This is a Squawk VM specific class that is used to communicate between executing Java software and the low level core VM that is expressed in machine code. There are two parts to this. There are a set of native methods that are used to invoke very low level operations like manipulating memory at a very low level or performing I/O. In the other direction there are a number of methods that the low level core may call. These are used to implement high level operations that are better done in Java than in machine code.

A special version of this class exists for the romizer. The romizer version only implements the methods used to manipulate memory.

Version:
1.0
Author:
Nik Shaylor, Doug Simon

Field Summary
static int MAX_SYS_PRIORITY
          The maximum priority that a system thread can have.
static int STREAM_STDERR
          The identifier denoting the standard error output stream.
static int STREAM_STDOUT
          The identifier denoting the standard output stream.
 
Method Summary
static void allowUserGC(boolean value)
          Enable or disable Runtime.gc()
static long branchCount()
          Enables a dynamically loaded class to call this.
static void collectGarbage(boolean forceFullGC)
          Switch to the service stack and call 'GC.collectGarbage()'
static int execGraphicsIO(int op, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes an I/O operation on the graphics channel and return the result.
static int execIO(int op, int channel, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes a I/O operation that may block.
static long execIOLong(int op, int channel, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes an I/O operation that returns a long value.
static Address execMessageIO(int op, Object key, Object data, int status)
          Executes a message I/O operation.
static int execSyncIO(int op, int i1)
          Executes a non-blocking I/O operation whose result is guaranteed to be available immediately.
static int execSyncIO(int context, int op, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes a non-blocking I/O operation whose result is guaranteed to be available immediately.
static int execSyncIO(int op, int i1, int i2, int i3, int i4, int i5, int i6, Object send, Object receive)
          Executes a non-blocking I/O operation whose result is guaranteed to be available immediately.
static Address getBootstrapEnd()
          Gets the address at which the object memory containing the bootstrap suite ends.
static int getBootstrapHash()
          Gets the hash of the object memory containing the bootstrap suite in it's canonical (i.e. relative to address 0) form.
static Address getBootstrapStart()
          Gets the address at which the object memory containing the bootstrap suite starts.
static Object getClass(Object object)
          Support routine to get the object representing the class of a given object.
static Isolate getCurrentIsolate()
          Gets the isolate of the currently executing thread.
static char getFileSeparatorChar()
          The system-dependent default name-separator character.
static int getFullGCCount()
           
static long getGUIEvent()
          Gets the next available event on the GUI input channel, blocking until there is one.
static long getLastGCTime()
           
static String getManifestProperty(String name)
          Gets the value of an Suite#PROPERTIES_MANIFEST_RESOURCE_NAME property embedded in the suite.
static Enumeration getManifestPropertyNames()
          Gets the names of all manifest properties embedded in the leaf suite and all of its parents.
static long getMaxGCTime()
           
static int getPartialGCCount()
           
static char getPathSeparatorChar()
          The system-dependent path-separator character.
static PeripheralRegistry getPeripheralRegistry()
           
static Address getRomStart()
          Gets the address of the start of the object memory in ROM.
static Thread[] getRunnableThreads()
          Answer an array of threads that are runnable now, in the order they appear in the runnable queue.
static long getTimeBeforeAnotherThreadIsRunnable()
          Answer the time in millis until another thread is runnable.
static long getTimeMicros()
          Gets the current time.
static long getTimeMillis()
          Gets the current time.
static void haltVM(int code)
          Halt the VM without running exit hooks.
static void invokeMain(String className, String[] args)
          Call the main method of the specified class
static boolean isArray(Object o)
          Support routine to test whether a given object is an array.
static boolean isCurrentIsolateInitialized()
          Determines if the current isolate is set and initialized.
static boolean isHosted()
          Determines if code running at the moment is running inside of a Squawk VM or a JSE VM.
static boolean isVerbose()
          Gets the flag indicating if the VM is running in verbose mode.
static boolean isVeryVerbose()
          Gets the flag indicating if the VM is running in very verbose mode.
static void print(boolean b)
          Prints a boolean to the VM output stream.
static void print(char x)
          Prints a character to the VM output stream.
static void print(double x)
          Prints a double to the VM output stream.
static void print(float x)
          Prints a float to the VM output stream.
static void print(int x)
          Prints an integer to the VM output stream.
static void print(long x)
          Prints a long to the VM output stream.
static void print(String x)
          Prints a string to the VM output stream.
static void printAddress(Object val)
          Prints an address to the VM stream.
static void printBC()
          Print branch count as safely as possible.
static Throwable printExceptionAndTrace(Throwable exc, String msg)
          Safely print exception and stack trace to System.err.
static void println()
          Prints a new line to the VM output stream.
static void println(boolean x)
          Prints a boolean followed by a new line to the VM output stream.
static void println(char x)
          Prints a character followed by a new line to the VM output stream.
static void println(double x)
          Prints a double followed by a new line to the VM output stream.
static void println(float x)
          Prints a float followed by a new line to the VM output stream.
static void println(int x)
          Prints an integer followed by a new line to the VM output stream.
static void println(long x)
          Prints a long followed by a new line to the VM output stream.
static void println(String x)
          Prints a string followed by a new line to the VM output stream.
static void printObject(Object obj)
          Prints the string representation of an object to the VM stream.
static void printOffset(Offset val)
          Prints an offset to the VM stream.
static void printUWord(UWord val)
          Prints an unsigned word to the VM stream.
static void setAsDaemonThread(Thread t)
          Mark the specified thread to be a daemon thread (won't prevent VM from exiting).
static void setProperty(String name, String value)
          On a hosted system , this calls System.setProperty(), otherwise calls Isolate.currentIsolate().setProperty()
static int setStream(int stream)
          Sets the stream for the VM.print... methods to one of the STREAM_... constants.
static void setSystemThreadPriority(Thread t, int level)
          Sets the given thread to the given priority, bounded by MAX_SYS_PRIORITY (eg. allowing higher than normal priority levels) Note that threads created by a thread with "system" priority do not inherit the system priority level, but default to NORM_PRIORITY.
static Object shallowCopy(Object original)
          Perform a shallow copy of the original object, without calling a constructor
static void startTracing()
          Start the VM tracing if tracing support is enabled.
static void stopVM(int code)
          Halt the VM in the normal way.
static boolean userGCAllowed()
          Tests if Runtime.gc() is allowed.
static boolean usingTypeMap()
          Determines if the VM was built with memory access type checking enabled.
static long waitForDeepSleep(long minimumDeepSleepTime)
          Wait until it's possible that we can go to deep sleep.
static void waitForInterrupt(int irq)
          Waits for an interrupt.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_SYS_PRIORITY

public static final int MAX_SYS_PRIORITY
The maximum priority that a system thread can have.

See Also:
Constant Field Values

STREAM_STDERR

public static final int STREAM_STDERR
The identifier denoting the standard error output stream.

See Also:
Constant Field Values

STREAM_STDOUT

public static final int STREAM_STDOUT
The identifier denoting the standard output stream.

See Also:
Constant Field Values
Method Detail

allowUserGC

public static void allowUserGC(boolean value)
Enable or disable Runtime.gc()

Parameters:
value - true to enable

branchCount

public static long branchCount()
Enables a dynamically loaded class to call this.

Returns:
the number of instructions the VM has executed or -1 if instruction profiling is disabled

collectGarbage

public static void collectGarbage(boolean forceFullGC)
Switch to the service stack and call 'GC.collectGarbage()'

Parameters:
forceFullGC - forces a collection of the whole heap
Throws:
NotInlinedPragma - as the frame of this method will be the inner most frame on the current thread's stack. The inner most frame on any stack does not have it's local variables scanned by the garbage collector. As such, this method must not use any local variables.

execGraphicsIO

public static int execGraphicsIO(int op,
                                 int i1,
                                 int i2,
                                 int i3,
                                 int i4,
                                 int i5,
                                 int i6,
                                 Object send,
                                 Object receive)
Executes an I/O operation on the graphics channel and return the result.

Parameters:
op - the opcode
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - a outgoing reference parameter
receive - an incoming reference parameter (i.e. an array of some type)
Returns:
the event code to wait on or zero

execIO

public static int execIO(int op,
                         int channel,
                         int i1,
                         int i2,
                         int i3,
                         int i4,
                         int i5,
                         int i6,
                         Object send,
                         Object receive)
                  throws IOException
Executes a I/O operation that may block. This requires at least 2 calls to the IO sub-system: the first to execute the operation and the second to get the status of the operation (success = 0, failure < 0 or blocked > 0). If the status is success, then a third call to the IO sub-system is made to retrieve the result of the operation. If the status indicates that an exception occcurred in the IO sub-system, then an IOException is thrown. If the status indicates that the IO sub-system is blocked, then the status value is used as an event number to block the current thread and put it on a queue of threads waiting for an event.

Parameters:
op - the opcode
channel - the channel number
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - an outgoing array parameter
receive - an incoming array parameter
Returns:
the integer result value
Throws:
IOException

execIOLong

public static long execIOLong(int op,
                              int channel,
                              int i1,
                              int i2,
                              int i3,
                              int i4,
                              int i5,
                              int i6,
                              Object send,
                              Object receive)
                       throws IOException
Executes an I/O operation that returns a long value.

Parameters:
op - the opcode
channel - the channel identifier
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - a outgoing reference parameter
receive - an incoming reference parameter (i.e. an array of some type)
Returns:
the long result
Throws:
IOException

execMessageIO

public static Address execMessageIO(int op,
                                    Object key,
                                    Object data,
                                    int status)
                             throws IOException
Executes a message I/O operation.

Parameters:
op - the opcode
key - the message key
data - the message data or null
Returns:
the Address result or null
Throws:
IOException

execSyncIO

public static int execSyncIO(int op,
                             int i1)
Executes a non-blocking I/O operation whose result is guaranteed to be available immediately.

Parameters:
op - the opcode
i1 - an integer parameter
Returns:
the integer result value

execSyncIO

public static int execSyncIO(int context,
                             int op,
                             int i1,
                             int i2,
                             int i3,
                             int i4,
                             int i5,
                             int i6,
                             Object send,
                             Object receive)
Executes a non-blocking I/O operation whose result is guaranteed to be available immediately. This mechanism requires 2 calls to the IO sub-system. The first sets up the globals used to pass the parameters and initiates the operation. The second retrieves the result from the global that the operation stored its result in.

Parameters:
context - the I/O context
op - the opcode
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - an outgoing array parameter
receive - an incoming array parameter
Returns:
the integer result value

execSyncIO

public static int execSyncIO(int op,
                             int i1,
                             int i2,
                             int i3,
                             int i4,
                             int i5,
                             int i6,
                             Object send,
                             Object receive)
Executes a non-blocking I/O operation whose result is guaranteed to be available immediately. This mechanism requires 2 calls to the IO sub-system. The first sets up the globals used to pass the parameters and initiates the operation. The second retrieves the result from the global that the operation stored its result in.

Parameters:
op - the opcode
i1 - an integer parameter
i2 - an integer parameter
i3 - an integer parameter
i4 - an integer parameter
i5 - an integer parameter
i6 - an integer parameter
send - an outgoing array parameter
receive - an incoming array parameter
Returns:
the integer result value

getBootstrapEnd

public static Address getBootstrapEnd()
Gets the address at which the object memory containing the bootstrap suite ends.

Returns:
the bootstrap object memory end address

getBootstrapHash

public static int getBootstrapHash()
Gets the hash of the object memory containing the bootstrap suite in it's canonical (i.e. relative to address 0) form.

Returns:
the hash of the bootstrap object memory

getBootstrapStart

public static Address getBootstrapStart()
Gets the address at which the object memory containing the bootstrap suite starts.

Returns:
the bootstrap object memory start address

getClass

public static Object getClass(Object object)
Support routine to get the object representing the class of a given object. This takes into account whether or not the VM is running in hosted mode or not. The returned object can only be used for identity comparisons.


getCurrentIsolate

public static Isolate getCurrentIsolate()
Gets the isolate of the currently executing thread.

Returns:
the isolate

getFileSeparatorChar

public static char getFileSeparatorChar()
The system-dependent default name-separator character. This field is initialized to contain the first character of the value of the system property file.separator. On UNIX systems the value of this field is '/'; on Microsoft Windows systems it is '\'.

See Also:
System.getProperty(java.lang.String)

getFullGCCount

public static int getFullGCCount()
Returns:
the total number of full garbage collections since reboot

getGUIEvent

public static long getGUIEvent()
Gets the next available event on the GUI input channel, blocking until there is one.

Returns:
the GUI event value

getLastGCTime

public static long getLastGCTime()
Returns:
the time taken (in millis) by the last garbage collection

getManifestProperty

public static String getManifestProperty(String name)
Gets the value of an Suite#PROPERTIES_MANIFEST_RESOURCE_NAME property embedded in the suite.

Parameters:
name - the name of the property whose value is to be retrieved
Returns:
the property value

getManifestPropertyNames

public static Enumeration getManifestPropertyNames()
Gets the names of all manifest properties embedded in the leaf suite and all of its parents.

Returns:
enumeration over the names

getMaxGCTime

public static long getMaxGCTime()
Returns:
the time taken (in millis) by the slowest garbage collection

getPartialGCCount

public static int getPartialGCCount()
Returns:
the total number of partial garbage collections since reboot

getPathSeparatorChar

public static char getPathSeparatorChar()
The system-dependent path-separator character. This character is used to separate filenames in a sequence of files given as a path list. On UNIX systems, this character is ':'; on Windows systems it is ';'.

Returns:
the system-dependent path-separator character

getPeripheralRegistry

public static PeripheralRegistry getPeripheralRegistry()

getRomStart

public static Address getRomStart()
Gets the address of the start of the object memory in ROM.

Returns:
the address of the start of the object memory in ROM

getRunnableThreads

public static Thread[] getRunnableThreads()
Answer an array of threads that are runnable now, in the order they appear in the runnable queue.

Returns:
the runnable threads

getTimeBeforeAnotherThreadIsRunnable

public static long getTimeBeforeAnotherThreadIsRunnable()
Answer the time in millis until another thread is runnable. Will return zero if another thread is already runnable, otherwise the delta until the first thread on the timer queue becomes runnable, otherwise Long.MAX_VALUE if there are no threads on the timer queue. This method takes no account of events.

Returns:
time in millis

getTimeMicros

public static long getTimeMicros()
Gets the current time.

Returns:
the time in microseconds

getTimeMillis

public static long getTimeMillis()
Gets the current time.

Returns:
the time in milliseconds

haltVM

public static void haltVM(int code)
Halt the VM without running exit hooks.

Parameters:
code - the exit status code.

invokeMain

public static void invokeMain(String className,
                              String[] args)
                       throws ClassNotFoundException
Call the main method of the specified class

Parameters:
className - the name of the class whose main method is to be run
args - the arguments to be passed to the main method
Throws:
ClassNotFoundException - if the class is not found

isArray

public static boolean isArray(Object o)
Support routine to test whether a given object is an array. This takes into account whether or not the VM is running in hosted mode or not.


isCurrentIsolateInitialized

public static boolean isCurrentIsolateInitialized()
Determines if the current isolate is set and initialized.

Returns:
true if the current isolate is set and initialized

isHosted

public static boolean isHosted()
Determines if code running at the moment is running inside of a Squawk VM or a JSE VM.

Returns:
true if running in a hosted environment, ie in a JSE VM

isVerbose

public static boolean isVerbose()
Gets the flag indicating if the VM is running in verbose mode.

Returns:
true if the VM is running in verbose mode

isVeryVerbose

public static boolean isVeryVerbose()
Gets the flag indicating if the VM is running in very verbose mode.

Returns:
true if the VM is running in very verbose mode

print

public static void print(char x)
Prints a character to the VM output stream.

Parameters:
x - the value

print

public static void print(double x)
Prints a double to the VM output stream.

Parameters:
x - the value

print

public static void print(float x)
Prints a float to the VM output stream.

Parameters:
x - the value

print

public static void print(int x)
Prints an integer to the VM output stream.

Parameters:
x - the value

print

public static void print(long x)
Prints a long to the VM output stream.

Parameters:
x - the value

print

public static void print(String x)
Prints a string to the VM output stream.

Parameters:
x - the string

print

public static void print(boolean b)
Prints a boolean to the VM output stream.

Parameters:
b - the value

printAddress

public static void printAddress(Object val)
Prints an address to the VM stream. This will be formatted as an unsigned 32 bit or 64 bit value depending on the underlying platform.

Parameters:
val - the address to print

printBC

public static void printBC()
Print branch count as safely as possible. Called by error reporting code, so doesn't assert, or intentionally throw exceptions!


printExceptionAndTrace

public static Throwable printExceptionAndTrace(Throwable exc,
                                               String msg)
Safely print exception and stack trace to System.err. Handles exceptions in Throwable.toString and printStackTrace, including OutOfMemoryExceptions. In all cases, this should print the message, the thread name, and the orginal exception (cclass name or toString).

Parameters:
exc - excption to report
msg - message to print before exception.
Returns:
Secondary exception, or null if none.

printObject

public static void printObject(Object obj)
Prints the string representation of an object to the VM stream.

Parameters:
obj - the object whose toString() result is to be printed

printOffset

public static void printOffset(Offset val)
Prints an offset to the VM stream. This will be formatted as a signed 32 bit or 64 bit value depending on the underlying platform.

Parameters:
val - the offset to print

printUWord

public static void printUWord(UWord val)
Prints an unsigned word to the VM stream. This will be formatted as an unsigned 32 bit or 64 bit value depending on the underlying platform.

Parameters:
val - the word to print

println

public static void println()
Prints a new line to the VM output stream.


println

public static void println(char x)
Prints a character followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(double x)
Prints a double followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(float x)
Prints a float followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(int x)
Prints an integer followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(long x)
Prints a long followed by a new line to the VM output stream.

Parameters:
x - the value

println

public static void println(String x)
Prints a string followed by a new line to the VM output stream.

Parameters:
x - the string

println

public static void println(boolean x)
Prints a boolean followed by a new line to the VM output stream.

Parameters:
x - the value

setAsDaemonThread

public static void setAsDaemonThread(Thread t)
Mark the specified thread to be a daemon thread (won't prevent VM from exiting). If this thread is alive, an IllegalThreadStateException is thrown.

Parameters:
t - The thread

setProperty

public static void setProperty(String name,
                               String value)
On a hosted system , this calls System.setProperty(), otherwise calls Isolate.currentIsolate().setProperty()


setStream

public static int setStream(int stream)
Sets the stream for the VM.print... methods to one of the STREAM_... constants.

Parameters:
stream - the stream to use for the print... methods
Returns:
the current stream used for VM printing

setSystemThreadPriority

public static void setSystemThreadPriority(Thread t,
                                           int level)
Sets the given thread to the given priority, bounded by MAX_SYS_PRIORITY (eg. allowing higher than normal priority levels) Note that threads created by a thread with "system" priority do not inherit the system priority level, but default to NORM_PRIORITY. Should only be called by system code. This interface likely to change to more RTSJ-like scheme.

Parameters:
t - The thread
level - the system priority level (currently supports 11, and 12)

shallowCopy

public static Object shallowCopy(Object original)
Perform a shallow copy of the original object, without calling a constructor

Parameters:
original - the iobject to copy
Returns:
a copy of the original object.

startTracing

public static void startTracing()
Start the VM tracing if tracing support is enabled.


stopVM

public static void stopVM(int code)
Halt the VM in the normal way. Any registered shutdown hooks will be run.

Parameters:
code - the exit status code.
See Also:
Isolate.addLifecycleListener(com.sun.squawk.Isolate.LifecycleListener, int)

userGCAllowed

public static boolean userGCAllowed()
Tests if Runtime.gc() is allowed.

Returns:
true if calls to Runtime.gc() are allowed

usingTypeMap

public static boolean usingTypeMap()
Determines if the VM was built with memory access type checking enabled.

Returns:
true if the VM was built with memory access type checking enabled

waitForDeepSleep

public static long waitForDeepSleep(long minimumDeepSleepTime)
Wait until it's possible that we can go to deep sleep. It's possible if the thread scheduler has nothing to do for at least a certain length of time

Parameters:
minimumDeepSleepTime - the minimum time (in millis) that it's worth deep sleeping
Returns:
the target wake up time (in System clock millis) that we should return from deep sleep

waitForInterrupt

public static void waitForInterrupt(int irq)
                             throws IOException
Waits for an interrupt.

Parameters:
irq - mask for interrupt
Throws:
IOException

SunSPOT API V3.0


Copyright © 2006, 2007 Sun Microsystems, Inc. All Rights Reserved.