vmintegration.texinfo

linux下建立JAVA虚拟机的源码KAFFE

@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.VMInstrumentationImpl, 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
occuring 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.
@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.VMInstrumentationImpl, java.lang.VMMath, java.lang.VMThread, java.lang
@subsection @code{java.lang.VMInstrumentationImpl}

The @code{java.lang.VMInstrumentationImpl} and
@code{java.lang.InstrumentationImpl} classes provide an implementation of the
@code{java.lang.instrument.Instrument} interface. This interface is for java
1.5 and is only in the generics branch.
A @code{InstrumentationImpl} object should be created by the VM when agents
are given in the command line (see the @code{java.lang.instrument} package
documentation). The VM has to set the static field
@code{VMClassLoader.instrumenter} to this object. The VM should implement the
static native methods of the @code{VMInstrumentationImpl} class.

@itemize @bullet
@item @code{isRedefineClassesSupported()} -- Returns true if the JVM supports
class redefinition.
@item @code{redefineClasses()} -- Gives a set of classes with new bytecodes.
The VM must redefine the classes by reading the new bytecodes.
@item @code{getAllLoadedClass()} -- Returns an array of all loaded classes.
@item @code{getInitiatedClass()} -- Returns an array of all classes loaded
by a specific class loader.
@item @code{getObjectSize()} -- Gives the size of an object.
@end itemize

Instrumentation allows to modify the bytecode of a class before it gets read
by the VM. In GNU Classpath, the @code{ClassLoader.defineClass} method calls
the @code{VMClassLoader.defineClassWithTransformers} method which first checks
if @code{VMClassLoader.instrumenter} is @code{null}. If it's the case, it
directly calls @code{VMClassLoader.defineClass}. If it's not the case, the
method calls at first the @code{InstrumentationImpl.callTransformers} method,
which calls each transformer registered to the @code{InstrumentationImpl}
object and returns a new bytecode array. Then, it calls the
@code{VMClassLoader.defineClass} method with this new bytecode array.

The second use of instrumentation is to redefine a class after it has been
loaded by the VM. This is done in the Java application by calling the
@code{Instrumentation.redefineClasses} method of the standard interface on
a @code{Instrumentation} object. The @code{InstrumentationImpl.redefineClasses}
method calls the @code{VMInstrumentationImpl.redefineClasses} native method
which must be implemented by the VM. The implementation should call the
@code{InstrumentationImpl.callTransformers} method.

@node java.lang.VMMath, , java.lang.VMInstrumentationImpl, 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 efficent 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