Subversion Repositories openrisc

\input texinfo @c -*-texinfo-*-

@c %**start of header

@setfilename cp-vmintegration.info

@settitle GNU Classpath VM Integration Guide

@c %**end of header

@setchapternewpage off

@ifinfo

This file contains important information you will need to know if you

are going to write an interface between GNU Classpath and a Virtual

Machine.

Copyright (C) 1998-2002, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.

@ifnotplaintext

@dircategory GNU Libraries

@direntry

* VM Integration: (cp-vmintegration).  GNU Classpath VM Integration Guide

@end direntry

@end ifnotplaintext

@end ifinfo

@titlepage

@title GNU Classpath VM Integration Guide

@author John Keiser

@author C. Brian Jones

@author Mark Wielaard

@page

@vskip 0pt plus 1filll

Copyright @copyright{} 1998-2002 Free Software Foundation, Inc.

@sp 2

Permission is granted to make and distribute verbatim copies of

this document provided the copyright notice and this permission notice

are preserved on all copies.

Permission is granted to copy and distribute modified versions of this

document under the conditions for verbatim copying, provided that the

entire resulting derived work is distributed under the terms of a

permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual

into another language, under the above conditions for modified versions,

except that this permission notice may be stated in a translation

approved by the Free Software Foundation.

@end titlepage

@ifinfo

@node Top, Introduction, (dir), (dir)

@top GNU Classpath Hacker's Guide

This file contains important information you will need to know if you

are going to write an interface between GNU Classpath and a Virtual

Machine.

This document is incomplete, as we are still in alpha with the interface.

@end ifinfo

@menu

* Introduction::                An introduction to the Classpath project

* Initialization::              Initializing the classes

* Classpath Hooks::             Hooks from Classpath to the VM

* VM Hooks::                    Hooks from the underlying VM to Classpath

* JNI Implementation::          Hooking the VM to jni.h

* JVMTI Implementation::        Hooking the VM to jvmti.h

* Miscellaneous VM Requirements::

@end menu

@node Introduction, Initialization, Top, Top

@comment node-name, next, previous, up

@chapter Introduction

The Classpath Project's ambition to be a 100% clean room implementation

of the standard Java class libraries cannot be fulfilled without some

level of integration with the Virtual Machine, the underlying machinery

that actually runs Java.

There are several VMs out there, here is a small list.

@itemize @bullet

@item @uref{http://www.hungry.com/old-hungry/products/japhar/,Japhar}

Japhar was the first VM to use GNU Classpath.  Today you can see that

sort of relationship in the source tree which denotes several Japhar

specific files as a reference implementation of those pieces.  This VM

has been primarily tested against Linux and lacks garbage collections, a

JIT, and suffers recently from slow development.

@item @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}

Intel surprised us not long ago with the release of this rather advanced

VM that uses GNU Classpath for a set of class libraries and works on

Linux and Windows 2000.  As of June, 2004, it does not appear that ORP

is under active development.

@item @uref{http://www.sablevm.org/,SableVM}

SableVM is a robust, extremely portable, efficient, and

specifications-compliant Java Virtual Machine that aims to be easy to

maintain and to extend. It features a state-of-the-art, efficient

interpreter engine. Its source code is very accessible and easy to

understand, and has many robustness features that have been the object

of careful design.

@item @uref{http://www.kaffe.org,Kaffe}

Kaffe is an advanced VM and together with its own class libraries

provides a Java 1.1 compatible environment.

@item @uref{http://www.mozilla.org/projects/ef,Electrical Fire}

The Electrical File VM continues to be listed as a Mozilla project

though development has been somewhat quiet.  A number of concepts from

EF were expected at one point to be rolled into Japhar, but that

development has not occurred as of yet.

@item @uref{http://latte.snu.ac.kr/,LaTTe}

This VM project so far supports only Sun UltraSparc processors using the

proprietary Solaris 2.5.1 or higher operating system.  LaTTe was derived

from Kaffe but claims a number of improvements.

@item @uref{http://gcc.gnu.org/java/,GNU Compiler for Java (GCJ)}

This is a portable, optimizing, ahead-of-time compiler for the Java

Programming Language. It can compile Java source code directly to native

machine code, Java source code to Java bytecode (class files), and Java

bytecode to native machine code. Compiled applications are linked with the

GCJ runtime, libgcj which is based on the GNU Classpath code, which provides

the core class libraries, a garbage collector, and a bytecode interpreter.

libgcj can dynamically load and interpret class files, resulting in mixed

compiled/interpreted applications.

GCJ is part of the GNU Compiler Collection (@uref{http://gcc.gnu.org/,GCC}).

On March 6 2000 the libgcj and GNU Classpath projects were officially merged

and there is active work on merging all the classes between the projects.

Licensed under GPL+exception, just as GNU Classpath is.

@item @uref{http://kissme.sourceforge.net/,Kissme}

This is a free Java Virtual Machine that is being developed on GNU/Linux

and can run console Java applications.  Kissme also provides support for

orthogonally persistent Java.

@c I don't know what ``orthogonally persistent Java'' is, and I bet

@c there are other people don't know either. -- Steve Augart, 4 June 2004

@item @uref{http://jamvm.sourceforge.net/,JamVM}

A simple, small bytecode interpreter that works out-of-the-box with

pure GNU Classpath; it is emerging as the preferred platform for

quickly testing a new build of GNU Classpath.  Licensed under the GPL.

@item @uref{http://jikesrvm.sourceforge.net/,Jikes RVM}

A free runtime environment for Java, written in Java.  Works

out-of-the-box with pure GNU Classpath.  Features an optimizing JIT.

Runs on the x86 and PowerPC architectures, on the AIX, Linux, and Mac

OS/X operating systems.  Licensed under the CPL (Common Public

License).  Extensively documented.  Actively developed as of June,

2004.

@end itemize

In the past integration efforts were focused mainly on Japhar with an eye

towards getting Electrical Fire to work.  Most information contained in

this document is gleaned from these efforts. Recently more work has been

done on getting gcj, orp and kissme to work out of the box with GNU Classpath

but there is much to do before that becomes a reality.

@node Initialization, Classpath Hooks, Introduction, Top

@comment node-name, next, previous, up

@chapter Initialization

The order of initialization, as far as I can tell, doesn't matter just

yet.  However, when we move to 1.2 support, it probably will matter, so

we'll have a note in here at that time.

The initialization order is currently documented in the

@file{Runtime.java} source file.

@node Classpath Hooks, VM Hooks, Initialization, Top

@comment node-name, next, previous, up

@chapter Classpath Hooks

The primary method of interaction between Classpath and the VM is via

the helper classes, which are named after the relevant core library

class, but include an additional `VM' prefix.  The library classes from

Classpath call out to these to get certain VM-specific dirty work done.

A reference copy of each VM class exists.  The majority consist of a

series of static methods, some of which are simply declared

@code{native}, and some which provide a default implementation.  VMs may

either use these as is, or create their own local variations.  When

using the default implementations, the VM is responsible for

implementing any of the code marked as @code{native} which corresponds

to functionality they wish their VM to provide.  When using their own

versions of the classes, VM implementors may choose to change the mix of

native and non-native methods from that below, so as to best suit their

implementation.

@menu

* java.lang::

* gnu.classpath::

* java.util::

* java.io::

* java.security::

* java.net::

* java.nio::

* java.nio.channels::

* gnu.java.nio::

* java.lang.reflect::

* gnu.java.lang::

* gnu.java.lang.management::

* java.lang.management::

* Classpath Callbacks::

@end menu

@node java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks

@comment  node-name,  next,  previous,  up

@section @code{java.lang}

@code{java.lang} is the core Java package, being imported automatically by all

classes.  It includes basic classes as @code{Object} and @code{String}.

A VM must implement at least some parts of this package in order to

become operable.

@menu

* java.lang.VMClass::

* java.lang.VMObject::

* java.lang.VMClassLoader::

* java.lang.VMSystem::

* java.lang.VMThrowable::

* java.lang.VMCompiler::

* java.lang.VMDouble::

* java.lang.VMFloat::

* java.lang.VMProcess::

* java.lang.VMRuntime::

* java.lang.VMString::

* java.lang.VMThread::

* java.lang.VMMath::

@end menu

@node java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang

@subsection @code{java.lang.VMClass}

The core class, @code{java.lang.Class}, and the corresponding VM class,

@code{java.lang.VMClass}, provide two main functions within GNU Classpath.

@enumerate

@item For basic VM operation, @code{java.lang.Class} provides the link between

the Java-based representation of a class it embodies and the VM's own

internal structure for a class.  @xref{VM Hooks}.

@item As far as the user is concerned, the main function of

@code{java.lang.Class} is as an entry point to the reflection

facilities, and so it also provides this functionality, backed by the

VM class.

@end enumerate

This VM class lists the following methods, organized by the version of the

Java specification in which they occur.  All are @code{native}, unless

otherwise specified, and pertain to reflection.  As a result, the VM only

needs to implement these methods in order to provide reflection support,

and then only to the degree required.

@itemize @bullet

@item 1.0

@itemize @bullet

@item @code{isInterface(Class)} -- This is simply a property test, and matches

the presence of an appropriate flag within the class file.

@item @code{getName(Class)} -- Returns the fully-qualified name of the class.

@item @code{getSuperclass(Class)} -- Returns a @code{Class} instance which

represents the superclass.  Again, the class file contains an element directly

relating to this.  @code{null} is returned for primitives, interfaces and

@code{Object}.

@item @code{getInterfaces(Class)} -- Same as the above, but the implemented

or extended interfaces rather than the superclass.  An empty array should

be returned, rather than @code{null}.

@item @code{getDeclaredClasses(Class,boolean)} -- Returns the internal classes

this instance declares directly.  The flag determines whether or not the

VM should filter out non-public classes.

@item @code{getDeclaredFields(Class,boolean)} -- The same for fields.

@item @code{getDeclaredMethods(Class,boolean)} -- And for methods.

@item @code{getDeclaredConstructors(Class,boolean)} -- And constructors.

@item @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance

which is responsible for the specified class.

@item @code{forName(String, boolean, ClassLoader)} -- The VM should create a

@code{Class} instance corresponding to the named class.  As noted in

@ref{VM Hooks}, the internal content of the instance is the

responsibility of the VM@.  The supplied class loader is recorded as that

which loaded the class, and the boolean specifies whether or not to

run the class initializer.

@item @code{isArray(Class)} -- Another property test, corresponding to a

class file flag.

@item @code{initialize(Class)} -- The VM should initialize the class fully,

if it has not already done so.

@item @code{loadArrayClass(String,ClassLoader)} -- This is called if

@code{forName} returns @code{null} and the string specifies an array class.

The specified array class should be loaded with the supplied class loader.

@item @code{throwException(Throwable)} -- The VM should throw the supplied

checked exception, without declaring it.

@end itemize

@item 1.1

@itemize @bullet

@item @code{isInstance(Class,Object)} -- This is a reflection-based equivalent

of the @code{instanceof} operator.

@item @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand for the above,

removing the need to create an instance to test assignability.

@item @code{isPrimitive(Class)} -- Returns true if this class is simply

a representation of one of the primitive types: @code{boolean}, @code{byte},

@code{char}, @code{short}, @code{int}, @code{long}, @code{float},

@code{double} and @code{void}.

@item @code{getComponentType(Class)} -- Produces a @code{Class} instance which

represents the type of the members of the array the class instance represents.

Classes which don't represent an array type return @code{null}.

@item @code{getModifiers(Class,boolean)} -- Returns an integer which encodes

the class' modifiers, such as @code{public}.  Again, this relates to

information stored in the class file.

@item @code{getDeclaringClass(Class)} -- Returns the class that declared

an inner or member class, or @code{null} if the instance refers to a top-level

class.

@end itemize

@item 1.5

@itemize @bullet

@item @code{isSynthetic(Class)} -- Returns true if the flags for this class

mark it as synthetic.

@item @code{isAnnotation(Class)} -- Returns true if the flags for this class

mark it as an annotation.

@item @code{isEnum(Class)} -- Returns true if the flags for this class

mark it as an enumeration.

@item @code{getSimpleName(Class)} -- Returns the simple name of the class.

A default implementation is provided, but a more efficient version may instead

be provided by the VM.

@item @code{getCanonicalName(Class)} -- Returns the canonical name of the

class.  A default implementation is provided, but a more efficient

version may instead be provided by the VM.

@item @code{getEnclosingClass(Class)} -- Returns the immediately enclosing

class (null for a top-level class).

@item @code{getEnclosingConstructor(Class)} -- Returns the constructor

which immediately encloses the supplied class.

@item @code{getEnclosingMethod(Class)} -- Returns the method

which immediately encloses the supplied class.

@item @code{getClassSignature(Class)} -- Returns the generic signature of

the class or null if there isn't one.

@item @code{isAnonymousClass(Class)} -- Returns true if the class is an

anonymous class.

@item @code{isLocalClass(Class)} -- Returns true if the class is an

local class.

@item @code{isMemberClass(Class)} -- Returns true if the class is an

member class.

@end itemize

@end itemize

@node java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang

@subsection @code{java.lang.VMObject}

@code{VMObject} is the bridge between the low level @code{Object}

facilities such as making a clone, getting the class of the object and

the wait/notify semantics.  This is accomplished using the following

@code{native} methods.

@itemize @bullet

@item @code{getClass(Object)} -- Returns the @code{Class} instance for the

object.  @code{Class} objects are produced by the VM, as described in

@ref{VM Hooks}.

@item @code{clone(Cloneable)} -- The VM should produce a low-level clone of the

specified object, creating a field-by-field shallow copy of the original.

The only difference between the two is that the new object should still be

@code{finalizable}, even if the original is not.

@item @code{notify(Object)} -- The VM should choose one of the threads waiting

for a lock on the specified object arbitrarily, and wake it.  If the current

thread does not currently hold the lock on the object, then an

@code{IllegalMonitorStateException} should be thrown.

@item @code{notifyAll(Object)} -- Same as the above, but all threads are

awakened.

@item @code{wait(Object,long,int)} -- The VM should set the current thread

into a waiting state, which persists until it receives a notify signal or the

specified time (in milliseconds and nanoseconds) is exceeded.  The nanoseconds

restriction may be ignored if such granularity is not available, and a

@code{IllegalMonitorStateException} should be thrown if the current thread

doesn't own the object.

@end itemize

@node java.lang.VMClassLoader, java.lang.VMSystem, java.lang.VMObject, java.lang

@subsection @code{java.lang.VMClassLoader}

@code{VMClassLoader} provides methods for defining and resolving core and

primitive classes, as well as handling resources, packages and assertions.

The class is a mixture of @code{native} methods and Java-based

implementations, with some of the latter being @emph{stubs}.

@itemize @bullet

@item Native Methods

@itemize @bullet

@item @code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}

-- The VM should create a @code{Class} instance from the supplied byte array.

@item @code{resolveClass(Class)} -- Resolve references to other classes in the

supplied class.

@item @code{loadClass(name,boolean)} -- Load a class using the bootstrap

loader.

@item @code{getPrimitiveClass(char)} -- The VM should provide a @code{Class}

implementation for one of the primitive classes.  The supplied character

matches the JNI code for the primitive class e.g.@: `B' for byte and

`Z' for boolean.

@end itemize

@item Java Methods

@itemize @bullet

@item @code{getResource(String)} -- The default implementation calls

@code{getResources} and returns the first element in the returned enumeration,

or @code{null} if there are no elements.

@item @code{getResources(String)} -- By default, this compiles a list of

URLs via the boot class path.  Any matching files within a zip file are added,

and directories on the boot class path are automatically converted to file

URLs that refer to join the directory with the resource name (whether or not

it actually exists).

@item @code{getPackage(String)} -- Always returns null, which may be suitable

if the VM does not wish to return a @code{Package} implementation. Otherwise,

it may be necessary to make this a @code{native} method.

@item @code{getPackages()} -- As with the last, a default stub implementation

exists (returning an empty array) which may be replaced if support is

required.

@item @code{defaultAssertionStatus()} -- A stub which can be implemented

by VMs providing assertion support.  At present, it always returns @code{true}.

@item @code{packageAssertionStatus()} -- Much the same status as the above.

The method should return a map converting package names to boolean status

values.  The stub implementation provides an empty map.

@item @code{classAssertionStatus()} -- Same as the last, but for classes.

@item @code{getSystemClassLoader()} -- The default calls @code{ClassLoader}

to create a new auxiliary class loader with a system and extension class

loader.  The VM may wish to replace it if it wishes to supply its own custom

system class loader.

@end itemize

@end itemize

@node java.lang.VMSystem, java.lang.VMThrowable, java.lang.VMClassLoader, java.lang

@subsection @code{java.lang.VMSystem}

@code{VMSystem} handles the default I/O streams, provides access to the

system clock and environment variables and provides methods for

@code{System.arraycopy} and the @code{identityHashCode} of an

@code{Object}.  It consists of @code{native} methods, but the default

implementation also provides some helper methods to simplify stream

creation.

@itemize @bullet

@item Native Methods

@itemize @bullet

@item @code{arraycopy(Object,int,Object,int,int)} -- The VM should copy

a specified number of array objects from one array to another, with

appropriate checks for compatible typing, available elements and space.

The VM should be able to perform this more efficiently using native code

and direct memory manipulation than would have been achieved by using Java.

@item @code{identityHashCode(Object)} -- This is the hashcode for

@code{Object}, which relates to the actual location of the object in memory.

@item @code{setIn(InputStream)} -- Set the system input stream.

@item @code{setOut(PrintStream)} -- Set the system output stream.

@item @code{setErr(PrintStream)} -- Set the system error stream.

@item @code{currentTimeMillis()} -- Gets the system time in milliseconds.

@item @code{getenv(String)} -- Returns the value of the specified environment

variable.

@item @code{getenv()} -- Returns a list of `name=value' pairs which correspond

to the environment variables.

@end itemize

@item Java Methods

@itemize @bullet

@item @code{makeStandardInputStream()} -- Helps provide the functionality of

@code{System.in} by wrapping the appropriate file descriptor in a

buffered file input stream.  VMs may choose to create the stream from

the descriptor differently rather than using this method.

@item @code{makeStandardOutputStream()} -- Helps provide the functionality of

@code{System.out} by wrapping the appropriate file descriptor in a buffered

file output stream.  VMs may choose to create the stream from the descriptor

differently rather than using this method.

@item @code{makeStandardErrorStream()} -- Helps provide the functionality of

@code{System.err} by wrapping the appropriate file descriptor in a buffered

file output stream.  VMs may choose to create the stream from the descriptor

differently rather than using this method.

@end itemize

@end itemize

Classpath also provides native implementations of

@itemize @bullet

@item @code{setIn(InputStream)}

@item @code{setOut(PrintStream)}

@item @code{setErr(PrintStream)}

@item @code{currentTimeMillis()}

@item @code{getenv(String)}

@end itemize

making a VM implementation optional.

@node java.lang.VMThrowable, java.lang.VMCompiler, java.lang.VMSystem, java.lang

@subsection @code{java.lang.VMThrowable}

@code{VMThrowable} is used to hold the VM state of a throwable, created either

when a @code{Throwable} is created or the @code{fillInStackTrace()} method is

called (i.e., when the actual stack trace is needed, as a lot of exceptions are

never actually used).  The actual class has two @code{native} methods,

one (@code{fillInStackTrace()}) being a method of the class used to obtain

instances, and the other an instance method, @code{getStackTrace()}.

@itemize @bullet

@item @code{fillInStackTrace(Throwable)} -- The VM should return the current

execution state of the @code{Throwable} in the form of a @code{VMThrowable}

instance.  The VM may also return @code{null} if it does not support this

functionality.

@item @code{getStackTrace()} -- This is used to create a real

@code{StackTraceElement} array for the exception, using the state data

stored during creation of the instance.

@end itemize

@node java.lang.VMCompiler, java.lang.VMDouble, java.lang.VMThrowable, java.lang

@subsection @code{java.lang.VMCompiler}

@code{VMCompiler} provides an interface for VMs which wish to provide

JIT compilation support.  The default implementation is simply a series

of stubs. The property, @code{java.compiler}, should point to a library

containing the function @code{java_lang_Compiler_start()} if such support

is to be provided.

@itemize @bullet

@item @code{compileClass(Class)} -- Invoke the compiler to compile the specific

class, returning @code{true} if successful.

@item @code{compileClasses(String)} -- The compiler should compile the classes

matching the specified string, again returning @code{true} on success.

@item @code{command(Object)} -- The object represents a command given to the

compiler, and is specific to the compiler implementation.

@item @code{enable} -- Enable the operation of the compiler.

@item @code{disable} -- Disable compiler operation.

@end itemize

@node java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler, java.lang

@subsection @code{java.lang.VMDouble}

@code{VMDouble} provides native support for the conversion and parsing

of doubles.

@itemize @bullet

@item @code{doubleToRawLongBits(double)} -- Converts the double to the IEEE 754

bit layout, preserving NaNs.

@item @code{longBitsToDouble(long)} -- This is the inverse of the last method,

preserving NaNs so that the output of one can be fed into the other without

data loss.

@item @code{toString(double,boolean)} -- Converts the double to a string,

giving a shorter value if the flag @code{isFloat} is @code{true}, indicating

that the conversion was requested by @code{java.lang.Float} rather than

@code{java.lang.Double}.

@item @code{initIDs} -- Used by JNI-based solutions to initialize the cache

of the static field IDs.  The default @code{VMDouble} implementation has a

static initializer which loads the JNI library and calls this method.

@item @code{parseDouble} -- Turn the string into a usable double value.

@end itemize

Classpath provides native implementations of all these, making VM

implementation optional.

@node java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble, java.lang

@subsection @code{java.lang.VMFloat}

@code{VMFloat} provides native support for the conversion of floats.

@itemize @bullet

@item @code{floatToRawIntBits(float)} -- Converts the float to the IEEE 754

bit layout, preserving NaNs.

@item @code{intBitsToFloat(int)} -- This is the inverse of the last method,

preserving NaNs so that the output of one can be fed into the other without

data loss.

@end itemize

Classpath provides native implementations of all these, making VM

implementation optional.

@node java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat, java.lang

@subsection @code{java.lang.VMProcess}

@code{VMProcess} handles the execution of external processes.  In the

default implementation, threads are spawned and reaped by @code{ProcessThread}.

A constructor creates a new @code{VMProcess}, which extends rather than

complements @code{Process}, using an array of arguments, an array of

environment variables and a working directory.  The instance maintains

system input, output and error streams linked to the external process.

Three @code{native} methods are used, and implementations are provided

for all three by Classpath, making VM implementation optional.  These use

the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.

@itemize @bullet

@item @code{nativeSpawn(String[],String[],File,boolean)} -- The VM should

create a new process which uses the specified command-line arguments,

environment variables and working directory.  Unlike the other two

methods, this method is linked to an instance, and must call

@code{setProcessInfo()} with the results before returning.  The

boolean argument maps to the @code{redirectErrorStream} property of

@code{java.lang.ProcessBuilder}.  When true, the output and error streams

are merged.

@item @code{nativeReap()} -- This is called to perform a reap of any

zombie processes, and should not block, instead returning a boolean as to

whether reaping actually took place.

@item @code{nativeKill(long)} -- The VM should terminate the specified PID.

@end itemize

@node java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess, java.lang

@subsection @code{java.lang.VMRuntime}

The @code{VMRuntime} class provides a series of native methods

which divulge information about the runtime or invoke certain

operations.  This includes retrieving the amount of available memory,

and scheduling the garbage collector.  There are two exceptions: the

@code{enableShutdownHooks} method, which allows the VM to put in its own

shutdown hooks when @code{Runtime.addShutdownHook()} is first invoked,

and @code{exec(String[],String[],File)} which spawns an external process.

These are Java-based static methods instead.  The first is simply a stub by

default, while the second simply links to the functionality of

@code{VMProcess} (and should be changed if a different @code{Process}

implementation is used).

@itemize @bullet

@item @code{availableProcessors()} -- Returns the number of processors

available to the VM.

@item @code{freeMemory()} -- Returns the amount of memory the VM has available

on the heap for allocating.

@item @code{totalMemory()} -- Returns the size of the heap.

@item @code{maxMemory()} -- Returns the maximum memory block the VM will

attempt to allocate.  May be simply @code{Long.MAX_VALUE} (8 exabytes!)

@item @code{gc()} -- Allows users to explicitly invoke the garbage collector.

This is a suggestion to the VM, rather than a command, and the garbage

collector should run anyway @emph{without} it being invoked.

@item @code{runFinalization()} -- Like the above, but related to the

finalilzation of objects rather than the garbage collector.

@item @code{runFinalizationForExit()} -- Called immediately prior to VM

shutdown in order to finalize all objects (including `live' ones)

@item @code{traceInstructions(boolean)} -- This turns on and off the optional

VM functionality of printing a trace of executed bytecode instructions.

@item @code{traceMethodCalls(boolean)} -- This turns on and off the optional

VM functionality of printing a trace of methods called.

@item @code{runFinalizersOnExit(boolean)} -- A toggleable setting for

running the finalization process at exit.

@item @code{exit(int)} -- The VM should shutdown with the specified exit code.

@item @code{nativeLoad(String,ClassLoader)} -- Attempts to load a file,

returning an integer which is non-zero for success.  Nothing happens if the

file has already been loaded.

@item @code{mapLibraryName(String)} -- The VM should map the system-independent

library name supplied to the platform-dependent equivalent (e.g.@: a @code{.so}

or @code{.dll} file)

@end itemize

@node java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime, java.lang

@subsection @code{java.lang.VMString}

@code{VMString} is responsible for handling interned strings.  If two strings

are equal (using the @code{equals()} method), then the results of calling

the @code{intern()} method on each of them makes them equal

(using @code{==}).  Thus, the same string object is always returned by

@code{intern} if the two strings are equal.  The default implementation

is Java-based and implements @code{intern(String)} by maintaining a

@code{WeakHashMap} which links the strings to their @code{WeakReference}.

A new mapping is created for each new string being @code{intern}ed.

A VM may implement this differently by implementing this method,

which is @code{static} and the only one in @code{VMString}.

@node java.lang.VMThread, java.lang.VMMath, java.lang.VMString, java.lang

@subsection @code{java.lang.VMThread}

@code{VMThread} provides the link between Java's threads and the platform

threading support.  A @code{VMThread} is created via a private constructor

and linked to a @code{Thread} instance.  This occurs when the @code{Thread}

instance is started by the static @code{create(Thread,long)} method (the second

argument requests a certain stack size, usually zero).  The thread itself is

executed via the @code{run()} method, which handles any problems with the

running of the thread and its eventual death.

@code{VMThread} provides the following accessors and mutators for accessing

the thread state via @code{VMThread},

@itemize @bullet

@item @code{getName()}

@item @code{setName(String)}

@item @code{getPriority()}

@item @code{setPriotity(int)}

@item @code{isDaemon()}

@end itemize

all of which refer to the @code{Thread} instance. @code{setPriority(int)} also

calls the appropriate native method.  @code{stop(Throwable)} similarly wraps

a native method, merely adding in a check for the state of the thread.

The default implementation also provides Java-based implementations of

@code{join(long,int)}, @code{sleep(long,int)} and

@code{holdsLock(Object)}.  @code{join} and @code{sleep} simply wait for

the appropriate amount of time, with @code{join} additionally waiting

for the thread instance to become @code{null}.  @code{holdsLock} simply

checks if an object is locked by the current thread by trying to invoke

the @code{notify} method, and catching the failing exception if this is

not the case.

The remainder of the class is a series of @code{native} methods, some of

which are mandatory for VM implementation and others which provide optional

or deprecated functionality.

@itemize @bullet

@item Mandatory Instance Methods

@itemize @bullet

@item @code{start(long)} -- The VM should create the native thread and start

it running using the @code{run} method of the @code{VMThread} instance on

which this method is called.

@item @code{interrupt()} -- The VM should interrupt the running thread and

throw an appropriate exception.

@item @code{isInterrupted()} -- Checks the interrupted state of the thread.

@item @code{suspend()} -- The thread should be suspended until resumed.

@item @code{resume()} -- The thread should be resumed from its suspended state.

This pair of methods are deprecated, due to the possibility of a deadlock

occurring when a thread with locks is suspended.

@item @code{nativeSetPriority(int)} -- Called by @code{setPriority}

to allow the setting to flow down to the native thread.

@item @code{nativeStop(Throwable)} -- The VM should stop the thread abnormally

and throw the specified exception.  This is clearly deprecated, due to the

ambiguous state an abruptly-stopped thread may leave.

@item @code{getState()} -- Returns the VM's impression of the current state

of the thread.  The applicable states are supplied by the @code{State}

enumeration in @code{java.lang.Thread}.

@end itemize

@item Mandatory Class Methods

@itemize @bullet

@item @code{currentThread()} -- Return a reference to the thread currently

being executed.

@item @code{yield()} -- The VM should allow some other thread to run.

The current thread maintains its locks even though it stops executing for

the time being.

@item @code{interrupted()} -- A shortcut to obtaining the interrupted state

of the current thread.

@end itemize

@item Other Methods

@itemize @bullet

@item @code{countStackFrames()} -- Returns a count of the number of stack

frames in the thread.  This depends on the deprecated method @code{suspend()}

having returned true, and is thus deprecated as a result.

@end itemize

@end itemize

@node java.lang.VMMath,, java.lang.VMThread, java.lang

@subsection @code{java.lang.VMMath}

The @code{VMMath} class provides a series of native methods

for some of the mathematical functions present in @code{java.lang.Math}.

Classpath provides a default implementation of these which maps the

functions to those provided by @code{fdlibm}.  VM implementors are welcome

to replace this with more efficient implementations, as long as the accuracy

contract of these methods, specified in @code{java.lang.Math}, is maintained.

@itemize @bullet

@item 1.0

@itemize @bullet

@item @code{sin(double)} -- Returns the sine value for the given angle.

@item @code{cos(double)} -- Returns the cosine value for the given angle.

@item @code{tan(double)} -- Returns the tangent value for the given angle.

@item @code{asin(double)} -- Returns the arc sine value for the given angle.

@item @code{acos(double)} -- Returns the arc cosine value for the given angle.

@item @code{atan(double)} -- Returns the arc tangent value for the given angle.

@item @code{atan2(double,double)} -- Returns the arc tangent of the ratio of

the two arguments.

@item @code{exp(double)} -- Returns the exponent raised to the given power.

@item @code{log(double)} -- Returns the natural logarithm for the given value.

@item @code{sqrt(double)} -- Returns the square root of the value.

@item @code{pow(double,double)} -- Returns x to the power of y.

@item @code{IEEEremainder(double,double)} -- Returns the IEEE 754 remainder

for the two values.

@item @code{ceil(double)} -- Returns the nearest integer >= the value.

@item @code{floor(double)} -- Returns the nearest integer <= the value.

@item @code{rint(double)} -- Returns the nearest integer or the even one

if the distance between the two is equal.

@end itemize

@item 1.5

@itemize @bullet

@item @code{cbrt(double)} -- Returns the cube root of the value.

@item @code{cosh(double)} -- Returns the hyperbolic cosine value for the given

angle.

@item @code{expm1(double)} -- Returns the exponent of the value minus one.

@item @code{hypot(double,double)} -- Returns the hypotenuse corresponding to

x and y.

@item @code{log10(double)} -- Returns the base 10 logarithm of the given value.

@item @code{log1p(double)} -- Returns the natural logarithm of the value plus

one.

@item @code{sinh(double)} -- Returns the hyperbolic sine value for the given

angle.

@item @code{tanh(double)} -- Returns the hyperbolic tangent value for the given angle.

@end itemize

@end itemize

@node gnu.classpath, java.util, java.lang, Classpath Hooks

@section @code{gnu.classpath}

The @code{gnu.classpath} package provides Classpath-specific functionality,

primarily relating to the features in @code{java.lang}.  At present, this

includes the context of a class (the stack) and the system properties.

@menu

* gnu.classpath.VMStackWalker::

* gnu.classpath.VMSystemProperties::

* gnu.classpath.Unsafe::

@end menu

@node gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath

@subsection @code{gnu.classpath.VMStackWalker}

@code{VMStackWalker} provides access to the class context or stack.  The

default implementation consists of a @code{native} @code{static} method,

@code{getClassContext()}, which obtains the class context, and two helper

methods which obtain the calling class (the 3rd element in the context array)

and its class loader, respectively.

@itemize @bullet

@item @code{getClassContext()} -- The VM should return an array of

@code{Class} objects, each of which relates to the method currently being

executed at that point on the stack.  Thus, the first item (index 0) is the

class that contains this method.

@item @code{getCallingClass()} -- A Java-based helper method which returns

the @code{Class} object which contains the method that called the method

accessing @code{getCallingClass()}.

@item @code{getCallingClassLoader()} -- Like the last, but returning the class

loader of the class.

@end itemize

@node gnu.classpath.VMSystemProperties,gnu.classpath.Unsafe,gnu.classpath.VMStackWalker,gnu.classpath

@subsection @code{gnu.classpath.VMSystemProperties}

@code{VMSystemProperties} allows the VM to hook into the property creation

process, both before and after the system properties are added by GNU

Classpath.  The default implementation assumes that the VM will add its

properties first, by making the pre-initialisation method @code{native},

and that the Classpath properties may then be altered by a Java-based

post-initialisation method.

As these methods are called as part of the bootstrap process, caution should

be used as to what classes are used, and properties should only be set

using @code{Properties.setProperty()}.  Specifically, I/O classes should be

avoided at this early stage.

@itemize @bullet

@item @code{preInit(Properties)} -- Allows the VM to add properties

@emph{before} the Classpath properties are added. The default implementation

includes a full list of properties that @emph{must} be added by the VM, but

additional VM-specific ones may also be added.

@item @code{postInit(Properties)} -- Same as the last, but called after the

Classpath properties have been added.  The main purpose of this is to allow

the VM to alter the properties added by GNU Classpath to suit it.

@end itemize

@node gnu.classpath.Unsafe,,gnu.classpath.VMSystemProperties,gnu.classpath

@subsection @code{gnu.classpath.Unsafe}

The @code{Unsafe} class provides access to some low-level unsafe operations

as required by the addition of the java.util.concurrent classes.  These

focus on direct memory access to the fields within the VM and providing

atomic update methods.

@itemize @bullet

@item @code{objectFieldOffset(Field)} -- Provides the caller with the memory

offset of a particular field.

@item @code{compareAndSwap*(Object,long,*,*)} -- One of these methods is

provided for each of int, long and Object (hence the *s).  The value of

a field pointed to by the given Object and offset is compared with the

first value and replaced with the second if they are the same.  The reason

for this method is to make this change operation atomic.

@item @code{put/get*(Object,long,*)} -- These are like the last set of

methods, handling integers, longs and Objects, but the field is always

changed on a put.  Different methods are provided for different semantics.

Ordered variants perform a lazy put, in that the change does not

immediately propogate to other threads, while the others provide

volatile or 'normal' semantics.

@item @code{arrayBaseOffset(Class)} and @code{arrayIndexScale(Class)} --

These two methods allow an array class to be traversed by pointer

arithmetic, by gaining the address of the first element and then

scaling appropriately for the later ones.

@item @code{park(boolean,long)} and @code{unpark(Thread)} -- These methods

block and unblock threads respectively, with an optional timeout being

provided for the blocking.  @code{unpark} is unsafe as the thread may have

been destroyed by native code.

@end itemize

@node java.util, java.io, gnu.classpath, Classpath Hooks

@section java.util

The @code{java.util} VM hooks provide links between the mix of functionality

present in that package, which includes collections, date and time handling

and parsing.  At present, there is only one hook, which connects GNU Classpath

to the timezone information provided by the underlying platform.

@menu

* java.util.VMTimeZone::

@end menu

@node java.util.VMTimeZone,,java.util,java.util

@subsection @code{java.util.VMTimeZone}

@code{VMTimeZone} joins @code{TimeZone} to the platform timezone information

via the static method, @code{getDefaultTimeZoneId()}.  The VM hook is

expected to return a @code{TimeZone} instance that represents the current

timezone in use by the platform.  The default implementation provides

this functionality for POSIX or GNU-like systems, and VMs that want this

functionality can keep this implementation and implement the native

method, @code{getSystemTimeZoneId()}.  This method is only called when

obtaining the timezone name from the @code{TZ} environment variable,

@code{/etc/timezone} and @code{/etc/localtime} all fail.  This fallback

mechanism also means that a system which doesn't provide the above three

methods, but does provide a timezone in string form, can still use this

implementation.

@node java.io, java.security, java.util, Classpath Hooks

@section java.io

The @code{java.io} package is heavily reliant on access to the I/O facilities

of the underlying platform.  As far as its VM hooks go, they provide two

areas of functionality to GNU Classpath, these being

@itemize @bullet

@item File and directory queries and manipulation

@item Serialization of objects

@end itemize

The first corresponds directly to most of the @code{File} class, while

the latter underlies the functionality provided by the

@code{ObjectInputStream} and @code{ObjectOutputStream}.  More low-level I/O

is provided by @ref{java.nio}.

@menu

* java.io.VMFile::

* java.io.VMObjectInputStream::

* java.io.VMObjectStreamClass::

@end menu

@node java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io

@subsection @code{java.io.VMFile}

@code{VMFile} allows GNU Classpath's @code{File} representations to

probe and modify the file system using the native functions of the

platform.  The default implementation (which consists of both a

@code{VMFile} class and the native methods) is primarily UNIX-centric,

working with POSIX functions and assuming case-sensitive filenames,

without the restriction of the 8.3 format.  It consists mainly of

@code{static} @code{native} methods, with a few Java helper methods.

The native methods represent the file as a string containing its path,

rather than using the object itself.

@itemize @bullet

@item Native Methods

@itemize @bullet

@item @code{lastModified(String)} -- The native method should return a

@code{long} value that represents the last modified date of the file.

@item @code{setReadOnly(String)} -- Sets the file's permissions to read only,

in whichever way this is realised by the platform.