Attached is a patch which updates the VM integration documentation to correctly represent the current state of the VM classes. I'd be grateful for any comments and/or additions on this from other developers, especially those working on a VM (hence the cc to classpath@), before I commit.
Thanks.
Changelog:
2005-06-30 Andrew John Hughes <[EMAIL PROTECTED]>
* doc/vmintegration.texinfo:
Updated 'Classpath Hooks' section.
--
Andrew :-)
Please avoid sending me Microsoft Office (e.g. Word, PowerPoint) attachments.
See http://www.fsf.org/philosophy/no-word-attachments.html
No software patents in Europe -- http://nosoftwarepatents.com
"Value your freedom, or you will lose it, teaches history.
`Don't bother us with politics' respond those who don't want to learn."
-- Richard Stallman
Escape the Java Trap with GNU Classpath!
http://www.gnu.org/philosophy/java-trap.html
public class gcj extends Freedom implements Java { ... }
Index: doc/vmintegration.texinfo
===================================================================
RCS file: /cvsroot/classpath/classpath/doc/vmintegration.texinfo,v
retrieving revision 1.17
diff -u -3 -p -u -r1.17 vmintegration.texinfo
--- doc/vmintegration.texinfo 24 Apr 2005 19:28:29 -0000 1.17
+++ doc/vmintegration.texinfo 30 Jun 2005 13:26:41 -0000
@@ -110,7 +110,7 @@ provides a Java 1.1 compatible environme
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 occured as of yet.
+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
@@ -175,42 +175,881 @@ The initialization order is currently do
@comment node-name, next, previous, up
@chapter Classpath Hooks
-Several core classes must be implemented by the VM for Classpath to
-work. These classes are:
+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
[EMAIL PROTECTED], 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.
+
[EMAIL PROTECTED]
+* java.lang::
+* gnu.classpath::
+* java.util::
+* java.io::
+* java.security::
+* java.net::
+* java.nio::
+* java.nio.channels::
+* gnu.java.nio::
+* Classpath Callbacks::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks
[EMAIL PROTECTED] node-name, next, previous, up
+
[EMAIL PROTECTED] @code{java.lang}
+
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED]
+* 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::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang
[EMAIL PROTECTED] @code{java.lang.VMClass}
+
+The core class, @code{java.lang.Class}, and the corresponding VM class,
[EMAIL PROTECTED], provide two main functions within GNU Classpath.
+
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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}.
+
[EMAIL PROTECTED] As far as the user is concerned, the main function of
[EMAIL PROTECTED] is as an entry point to the reflection
+facilities, and so it also provides this functionality, backed by the
+VM class.
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] java.lang.Class
[EMAIL PROTECTED] java.lang.Runtime
[EMAIL PROTECTED] java.lang.Thread
[EMAIL PROTECTED] java.lang.reflect.Constructor
[EMAIL PROTECTED] java.lang.reflect.Method
[EMAIL PROTECTED] java.lang.reflect.Field
[EMAIL PROTECTED] 1.0
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{isInterface(Class)} -- This is simply a property test,
and matches
+the presence of an appropriate flag within the class file.
[EMAIL PROTECTED] @code{getName(Class)} -- Returns the fully-qualified name of
the class.
[EMAIL PROTECTED] @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
[EMAIL PROTECTED]
[EMAIL PROTECTED] @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}.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{getDeclaredFields(Class,boolean)} -- The same for
fields.
[EMAIL PROTECTED] @code{getDeclaredMethods(Class,boolean)} -- And for methods.
[EMAIL PROTECTED] @code{getDeclaredConstructors(Class,boolean)} -- And
constructors.
[EMAIL PROTECTED] @code{getClassLoader(Class)} -- Returns the
@code{ClassLoader} instance
+which is responsible for the specified class.
[EMAIL PROTECTED] @code{forName(String)} -- 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.
[EMAIL PROTECTED] @code{isArray(Class)} -- Another property test, corresponding
to a
+class file flag.
[EMAIL PROTECTED] @code{initialize(Class)} -- The VM should initialize the
class fully,
+if it has not already done so.
[EMAIL PROTECTED] @code{loadArrayClass(String,ClassLoader)} -- This is called if
[EMAIL PROTECTED] returns @code{null} and the string specifies an array class.
+The specified array class should be loaded with the supplied class loader.
[EMAIL PROTECTED] @code{throwException(Throwable)} -- The VM should throw the
supplied
+checked exception, without declaring it.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] 1.1
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{isInstance(Class,Object)} -- This is a reflection-based
equivalent
+of the @code{instanceof} operator.
[EMAIL PROTECTED] @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand
for the above,
+removing the need to create an instance to test assignability.
[EMAIL PROTECTED] @code{isPrimitive(Class)} -- Returns true if this class is
simply
+a representation of one of the primitive types: @code{boolean}, @code{byte},
[EMAIL PROTECTED], @code{short}, @code{int}, @code{long}, @code{float},
[EMAIL PROTECTED] and @code{void}.
[EMAIL PROTECTED] @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}.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] java.lang.VMObject, java.lang.VMClassLoader,
java.lang.VMClass, java.lang
[EMAIL PROTECTED] @code{java.lang.VMObject}
+
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{getClass(Object)} -- Returns the @code{Class} instance
for the
+object. @code{Class} objects are produced by the VM, as described in
[EMAIL PROTECTED] Hooks}.
[EMAIL PROTECTED] @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
[EMAIL PROTECTED], even if the original is not.
[EMAIL PROTECTED] @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
[EMAIL PROTECTED] should be thrown.
[EMAIL PROTECTED] @code{notifyAll(Object)} -- Same as the above, but all
threads are
+awakened.
[EMAIL PROTECTED] @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
[EMAIL PROTECTED] should be thrown if the current thread
+doesn't own the object.
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] java.lang.VMClassLoader, java.lang.VMSystem,
java.lang.VMObject, java.lang
[EMAIL PROTECTED] @code{java.lang.VMClassLoader}
[EMAIL PROTECTED] 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}.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] Native Methods
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED]
@code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}
+-- The VM should create a @code{Class} instance from the supplied byte array.
[EMAIL PROTECTED] @code{resolveClass(Class)} -- Resolve references to other
classes in the
+supplied class.
[EMAIL PROTECTED] @code{loadClass(name,boolean)} -- Load a class using the
bootstrap
+loader.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] Java Methods
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{getResource(String)} -- The default implementation calls
[EMAIL PROTECTED] and returns the first element in the returned enumeration,
+or @code{null} if there are no elements.
[EMAIL PROTECTED] @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).
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{getPackages()} -- As with the last, a default stub
implementation
+exists (returning an empty array) which may be replaced if support is
+required.
[EMAIL PROTECTED] @code{defaultAssertionStatus()} -- A stub which can be
implemented
+by VMs providing assertion support. At present, it always returns @code{true}.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{classAssertionStatus()} -- Same as the last, but for
classes.
[EMAIL PROTECTED] @code{getSystemClassLoader()} -- The default calls
@code{ClassLoader}
+to create a new auxillary 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.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] java.lang.VMSystem, java.lang.VMThrowable,
java.lang.VMClassLoader, java.lang
[EMAIL PROTECTED] @code{java.lang.VMSystem}
[EMAIL PROTECTED] handles the default I/O streams, provides access to the
+system clock and environment variables and provides methods for
[EMAIL PROTECTED] and the @code{identityHashCode} of an
[EMAIL PROTECTED] It consists of @code{native} methods, but the default
+implementation also provides some helper methods to simplify stream
+creation.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] Native Methods
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{identityHashCode(Object)} -- This is the hashcode for
[EMAIL PROTECTED], which relates to the actual location of the object in memory.
[EMAIL PROTECTED] @code{setIn(InputStream)} -- Set the system input stream.
[EMAIL PROTECTED] @code{setOut(PrintStream)} -- Set the system output stream.
[EMAIL PROTECTED] @code{setErr(PrintStream)} -- Set the system error stream.
[EMAIL PROTECTED] @code{currentTimeMillis()} -- Gets the system time in
milliseconds.
[EMAIL PROTECTED] @code{getenv(String)} -- Returns the value of the specified
environment
+variable.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] Java Methods
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{makeStandardInputStream()} -- Helps provide the
functionality of
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] @code{makeStandardOutputStream()} -- Helps provide the
functionality of
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] @code{makeStandardErrorStream()} -- Helps provide the
functionality of
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] itemize
+
+Classpath also provides native implementations of
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{setIn(InputStream)}
[EMAIL PROTECTED] @code{setOut(PrintStream)}
[EMAIL PROTECTED] @code{setErr(PrintStream)}
[EMAIL PROTECTED] @code{currentTimeMillis()}
[EMAIL PROTECTED] @code{getenv(String)}
[EMAIL PROTECTED] itemize
+
+making a VM implementation optional.
+
[EMAIL PROTECTED] java.lang.VMThrowable, java.lang.VMCompiler,
java.lang.VMSystem, java.lang
[EMAIL PROTECTED] @code{java.lang.VMThrowable}
[EMAIL PROTECTED] 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()}.
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{getStackTrace()} -- This is used to create a real
[EMAIL PROTECTED] array for the exception, using the state data
+stored during creation of the instance.
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] java.lang.VMCompiler, java.lang.VMDouble,
java.lang.VMThrowable, java.lang
[EMAIL PROTECTED] @code{java.lang.VMCompiler}
+
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{compileClass(Class)} -- Invoke the compiler to compile
the specific
+class, returning @code{true} if successful.
[EMAIL PROTECTED] @code{compileClasses(String)} -- The compiler should compile
the classes
+matching the specified string, again returning @code{true} on success.
[EMAIL PROTECTED] @code{command(Object)} -- The object represents a command
given to the
+compiler, and is specific to the compiler implementation.
[EMAIL PROTECTED] @code{enable} -- Enable the operation of the compiler.
[EMAIL PROTECTED] @code{disable} -- Disable compiler operation.
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler,
java.lang
[EMAIL PROTECTED] @code{java.lang.VMDouble}
+
[EMAIL PROTECTED] provides native support for the conversion and parsing
+of doubles.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{doubleToLongBits(double)} -- Converts the double to the
IEEE 754
+bit layout, collapsing NaNs to @code{0x7ff8000000000000L}.
[EMAIL PROTECTED] @code{doubleToRawLongBits(double)} -- Same as the above, but
preserves
+NaNs.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @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
[EMAIL PROTECTED]
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{parseDouble} -- Turn the string into a usable double
value.
[EMAIL PROTECTED] itemize
+
+Classpath provides native implementations of all these, making VM
+implementation optional.
+
[EMAIL PROTECTED] java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble,
java.lang
[EMAIL PROTECTED] @code{java.lang.VMFloat}
+
[EMAIL PROTECTED] provides native support for the conversion of floats.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{floatToIntBits(float)} -- Converts the float to the
IEEE 754
+bit layout, collapsing NaNs to @code{0x7fc00000}.
[EMAIL PROTECTED] @code{floatToRawIntBits(float)} -- Same as the above, but
preserves
+NaNs.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] itemize
+
+Classpath provides native implementations of all these, making VM
+implementation optional.
+
[EMAIL PROTECTED] java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat,
java.lang
[EMAIL PROTECTED] @code{java.lang.VMProcess}
+
[EMAIL PROTECTED] 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()}.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{nativeSpawn(String[],String[],File)} -- 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.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{nativeKill(long)} -- The VM should terminate the
specified PID.
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess,
java.lang
[EMAIL PROTECTED] @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
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] (and should be changed if a different @code{Process}
+implementation is used).
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{availableProcessors()} -- Returns the number of
processors
+available to the VM.
[EMAIL PROTECTED] @code{freeMemory()} -- Returns the amount of memory the VM
has available
+on the heap for allocating.
[EMAIL PROTECTED] @code{totalMemory()} -- Returns the size of the heap.
[EMAIL PROTECTED] @code{maxMemory()} -- Returns the maximum memory block the VM
will
+attempt to allocate. May be simply @code{Long.MAX_VALUE} (8 exabytes!)
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{runFinalization()} -- Like the above, but related to the
+finalilzation of objects rather than the garbage collector.
[EMAIL PROTECTED] @code{runFinalizationForExit()} -- Called immediately prior
to VM
+shutdown in order to finalize all objects (including `live' ones)
[EMAIL PROTECTED] @code{traceInstructions(boolean)} -- This turns on and off
the optional
+VM functionality of printing a trace of executed bytecode instructions.
[EMAIL PROTECTED] @code{traceMethodCalls(boolean)} -- This turns on and off the
optional
+VM functionality of printing a trace of methods called.
[EMAIL PROTECTED] @code{runFinalizersOnExit(boolean)} -- A toggleable setting
for
+running the finalization process at exit.
[EMAIL PROTECTED] @code{exit(int)} -- The VM should shutdown with the specified
exit code.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @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)
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime,
java.lang
[EMAIL PROTECTED] @code{java.lang.VMString}
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] if the two strings are equal. The default implementation
+is Java-based and implements @code{intern(String)} by maintaining a
[EMAIL PROTECTED] 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}.
+
[EMAIL PROTECTED] java.lang.VMThread,, java.lang.VMString, java.lang
[EMAIL PROTECTED] @code{java.lang.VMThread}
+
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] provides the following accessors and mutators for accessing
+the thread state via @code{VMThread},
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{getName()}
[EMAIL PROTECTED] @code{setName(String)}
[EMAIL PROTECTED] @code{getPriority()}
[EMAIL PROTECTED] @code{setPriotity(int)}
[EMAIL PROTECTED] @code{isDaemon()}
[EMAIL PROTECTED] 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
[EMAIL PROTECTED](long,int)}, @code{sleep(long,int)} and
[EMAIL PROTECTED](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.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] Mandatory Instance Methods
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{interrupt()} -- The VM should interrupt the running
thread and
+throw an appropriate exception.
[EMAIL PROTECTED] @code{isInterrupted()} -- Checks the interrupted state of the
thread.
[EMAIL PROTECTED] @code{suspend()} -- The thread should be suspended until
resumed.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{nativeSetPriority(int)} -- Called by @code{setPriority}
+to allow the setting to flow down to the native thread.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] Mandatory Class Methods
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{currentThread()} -- Return a reference to the thread
currently
+being executed.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] @code{interrupted()} -- A shortcut to obtaining the
interrupted state
+of the current thread.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] Other Methods
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] gnu.classpath, java.util, java.lang, Classpath Hooks
[EMAIL PROTECTED] @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.
+
[EMAIL PROTECTED]
+* gnu.classpath.VMStackWalker::
+* gnu.classpath.VMSystemProperties::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED]
gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
[EMAIL PROTECTED] @code{gnu.classpath.VMStackWalker}
+
[EMAIL PROTECTED] provides access to the class context or stack. The
+default implementation consists of a @code{native} @code{static} method,
[EMAIL PROTECTED]()}, 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.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{getClassContext()} -- The VM should return an array of
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] @code{getCallingClass()} -- A Java-based helper method which
returns
+the @code{Class} object which contains the method that called the method
+accessing @code{getCallingClass()}.
[EMAIL PROTECTED] @code{getCallingClassLoader()} -- Like the last, but
returning the class
+loader of the class.
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED]
gnu.classpath.VMSystemProperties,,gnu.classpath.VMStackWalker,gnu.classpath
[EMAIL PROTECTED] @code{gnu.classpath.VMSystemProperties}
+
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{preInit(Properties)} -- Allows the VM to add properties
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] @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.
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] java.util, java.io, gnu.classpath, Classpath Hooks
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED]
+* java.util.VMTimeZone::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] java.util.VMTimeZone,,java.util,java.util
[EMAIL PROTECTED] @code{java.util.VMTimeZone}
+
[EMAIL PROTECTED] 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,
[EMAIL PROTECTED]/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.
+
[EMAIL PROTECTED] java.io, java.security, java.util, Classpath Hooks
[EMAIL PROTECTED] 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
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] File and directory queries and manipulation
[EMAIL PROTECTED] Serialization of objects
[EMAIL PROTECTED] itemize
+
+The first corresponds directly to most of the @code{File} class, while
+the latter underlies the functionality provided by the
[EMAIL PROTECTED] and @code{ObjectOutputStream}. More low-level I/O
+is provided by @ref{java.nio}.
+
[EMAIL PROTECTED]
+* java.io.VMFile::
+* java.io.VMObjectInputStream::
+* java.io.VMObjectStreamClass::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
[EMAIL PROTECTED] @code{java.io.VMFile}
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] @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.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] Native Methods
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{lastModified(String)} -- The native method should
return a
[EMAIL PROTECTED] value that represents the last modified date of the file.
[EMAIL PROTECTED] @code{setReadOnly(String)} -- Sets the file's permissions to
read only,
+in whichever way this is realised by the platform.
[EMAIL PROTECTED] @code{create(String)} -- Create the named file.
[EMAIL PROTECTED] @code{list(String)} -- The native method opens the named
directory,
+reads the contents and returns them as a Java @code{String} array.
[EMAIL PROTECTED] @code{renameTo(String,String)} -- Renames the first file to
the second.
[EMAIL PROTECTED] @code{length(String)} -- Returns a @code{long} value
representing
+the file size.
[EMAIL PROTECTED] @code{exists(String)} -- Tests for the existence of the named
file
+or directory.
[EMAIL PROTECTED] @code{delete(String)} -- Deletes the file or directory.
[EMAIL PROTECTED] @code{setLastModified(String,long)} -- Change the last
modified time.
[EMAIL PROTECTED] @code{mkdir(String)} -- Creates the named directory.
[EMAIL PROTECTED] @code{isFile(String)} -- Tests that the named path references
a file.
[EMAIL PROTECTED] @code{canWrite(String)} -- Tests that the file can be written
to.
+This method is @code{synchronized}, so the object is locked during the check.
[EMAIL PROTECTED] @code{canRead(String)} -- Complement of the last method.
[EMAIL PROTECTED] @code{isDirectory(String)} -- Tests that the named path
references
+a directory.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED] Java Helper Methods
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{canWriteDirectory(File)} -- Checks that the directory
can be
+written to, by trying to create a temporary file in it.
[EMAIL PROTECTED] @code{listRoots()} -- Returns the root of a GNU filesystem
i.e. `/'
+in an array.
[EMAIL PROTECTED] @code{isHidden(String)} -- Checks whether the file starts
with `.',
+which is how files are hidden on UNIX-style systems.
[EMAIL PROTECTED] @code{getName(String)} -- Pulls the actual filename from the
end of
+the path, by breaking off the characters after the last occurrence of the
+platform's file separator.
[EMAIL PROTECTED] @code{getCanonicalForm(String)} -- This converts a UNIX path
to
+its canonical form by removing the `.' and `..' sections that occur within.
@end itemize
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED]
java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
[EMAIL PROTECTED] @code{java.io.VMObjectInputStream}
+
+This class consists of two methods which provide functionality used in
+deserializing an object. @code{currentClassLoader()} provides the first
+user-defined class loader from the class context
+(@xref{gnu.classpath.VMStackWalker},) via a @code{PrivilegedAction}.
[EMAIL PROTECTED](Class,Class,Constructor)} is a @code{native} method
+(a reference implementation is provided) which creates an object but
+calls the constructor of another class, which is a superclass of the
+object's class.
+
[EMAIL PROTECTED]
java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
[EMAIL PROTECTED] @code{java.io.VMObjectStreamClass}
+
[EMAIL PROTECTED] is a series of @code{static} @code{native}
+methods that provide some of the groundwork for @code{ObjectStreamClass}
+and @code{ObjectStreamField}. @code{hasClassInitializer(Class)} works
+with the former, and checks for the presence of a static initializer.
+The remaining methods are of the form @code{setXXXNative(Field,Object,XXX)}
+and support @code{ObjectStreamField}. One exists for each of the main types
+(boolean, float, double, long, int, short, char, byte and object) and is used
+to set the specified field in the supplied instance to the given value.
+
+A default implementation is provided for all of them, so a VM implementation
+is optional.
+
[EMAIL PROTECTED] java.security, java.net, java.io, Classpath Hooks
[EMAIL PROTECTED] java.security
+
+The @code{java.security} package provides support for Java's security
+architecture. At present, @code{VMAccessController} represents the sole
+VM hook for this.
-You also need to implement some helper classes in java.lang that classes
-from Classpath call out to to get certain VM-specific dirty work done:
[EMAIL PROTECTED]
+* java.security.VMAccessController::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] java.security.VMAccessController,,java.security,java.security
[EMAIL PROTECTED] @code{java.security.VMAccessController}
+
+The @code{AccessController} is used to perform privileged actions. Its
+hook class, @code{VMAccessController}, maintains the
[EMAIL PROTECTED] and the default implementation is purely
+Java-based. The VM may choose to replace this with their own.
+The methods in the reference version are as follows:
@itemize @bullet
[EMAIL PROTECTED] @code{java.lang.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.
[EMAIL PROTECTED] @code{java.lang.VMClassLoader}
-provides methods for defining and resolving core and primitive classes.
[EMAIL PROTECTED] @code{java.lang.VMSystem}
-is used to initialize the @code{System} properties, the @code{System.arraycopy}
-method and the @code{identityHashCode} of an @code{Object}.
[EMAIL PROTECTED] @code{java.lang.VMSecurityManager}
-provides the class context (stack trace) of the currently
-executing thread and a way to get the currently active @code{ClassLoader}.
[EMAIL PROTECTED] @code{java.lang.VMThrowable}
-used to hold the VM state of a throwable, created when a @code{Throwable} is
-created or the @code{fillInStacktrace()} method is called, when the actual
stack
-trace is needed (a lot of exceptions are never actually used), the
[EMAIL PROTECTED]()} method is used to create a real @code{StackTraceElement}
array
-for the exception.
[EMAIL PROTECTED] @code{pushContext(AccessControlContext)} -- Adds a new
context to the
+stack for the current thread. This is called before a privileged action
+takes place.
[EMAIL PROTECTED] @code{popContext()} -- Removes the top context from the
stack. This
+is performed after the privileged action takes place.
[EMAIL PROTECTED] @code{getContext()} -- Either derives a context based on the
[EMAIL PROTECTED] of the call stack (see the next method) or returns
+the top of the context stack.
[EMAIL PROTECTED] @code{getStack()} -- Provides access to the call stack as a
pair of
+arrays of classes and method names. The actual implementation returns
+an empty array, indicating that there are no permissions.
@end itemize
[EMAIL PROTECTED] java.net, java.nio, java.security, Classpath Hooks
[EMAIL PROTECTED] java.net
+
+The @code{java.net} package is heavily reliant on access to the networking
+facilities of the underlying platform. The VM hooks provide information
+about the available network interfaces, and access to lookup facilities
+for network addresses.
+
[EMAIL PROTECTED]
+* java.net.VMInetAddress::
+* java.net.VMNetworkInterface::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED]
java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
[EMAIL PROTECTED] @code{java.net.VMInetAddress}
+
[EMAIL PROTECTED] is a series of @code{static} @code{native} methods
+which provide access to the platform's lookup facilities. All the methods
+are implemented by GNU Classpath, making VM implementation optional, and
+are as follows:
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{getLocalHostname()} -- Wraps the @code{gethostname}
function, and
+falls back on `localhost'.
[EMAIL PROTECTED] @code{lookupInaddrAny()} -- Returns the value of
@code{INADDR_ANY}.
[EMAIL PROTECTED] @code{getHostByAddr(byte[])} -- Looks up the hostname based
on an IP
+address.
[EMAIL PROTECTED] @code{getHostByName(String)} -- The reverse of the last
method, it
+returns the IP addresses which the given host name resolves to.
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
[EMAIL PROTECTED] @code{java.net.VMNetworkInterface}
+
[EMAIL PROTECTED] currently consists of a single @code{static}
[EMAIL PROTECTED] method, @code{getInterfaces()}, which retrieves the
+network interfaces available on the underlying platform as a @code{Vector}.
+The current GNU Classpath implementation is a native stub.
+
[EMAIL PROTECTED] java.nio, java.nio.channels, java.net, Classpath Hooks
[EMAIL PROTECTED] java.nio
+
+The @code{java.nio} package is part of the New I/O framework added in
+Java 1.4. This splits I/O into the concepts of @emph{buffers},
[EMAIL PROTECTED], @emph{channels} and @emph{selectors}, and
[EMAIL PROTECTED] defines the buffer classes. As far as native and VM
+code is concerned, the new package needs support for low-level efficient
+buffer operations.
+
[EMAIL PROTECTED]
+* java.nio.VMDirectByteBuffer::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] java.nio.VMDirectByteBuffer,,java.nio,java.nio
[EMAIL PROTECTED] @code{java.nio.VMDirectByteBuffer}
+
+A @code{ByteBuffer} maintains a buffer of bytes, and allows it to be
+manipulated using primitive operations such as @code{get}, @code{put},
[EMAIL PROTECTED] and @code{free}. A direct buffer avoids intermediate
+copying, and uses native data which shouldn't be manipulated by a
+garbage collector. The VM class consists of @code{static} @code{native}
+methods, all of which are given default implementations by GNU
+Classpath.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{init()} -- Creates an instance of an appropriate
[EMAIL PROTECTED] class. This class is not garbage
+collected, is created natively and is used in the other methods to reference
+the buffered data.
[EMAIL PROTECTED] @code{allocate(int)} -- Allocates the memory for the buffer
using
[EMAIL PROTECTED] and returns a reference to the @code{RawData} class.
[EMAIL PROTECTED] @code{free(RawData)} -- Frees the memory used by the buffer.
[EMAIL PROTECTED] @code{get(RawData,int)} -- Returns the data at the specified
index.
[EMAIL PROTECTED] @code{get(RawData,int,byte[],int,int)} -- Copies a section of
the
+data into a byte array using @code{memcpy}.
[EMAIL PROTECTED] @code{put(RawData,int,byte)} -- Puts the given data in the
buffer
+at the specified index.
[EMAIL PROTECTED] @code{adjustAddress(RawData,int)} -- Adjusts the pointer into
the buffer.
[EMAIL PROTECTED] @code{shiftDown(RawData,int,int,int)} -- Moves the content of
the buffer
+at an offset down to a new offset using @code{memmove}.
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] java.nio.channels, gnu.java.nio, java.nio, Classpath Hooks
[EMAIL PROTECTED] java.nio.channels
+
+Channels provide the data for the buffers with the New I/O packages.
+For example, a channel may wrap a file or a socket. The VM hooks,
+at the moment, simply allow the channels to be accessed by @code{java.io}
+streams.
+
[EMAIL PROTECTED]
+* java.nio.channels.VMChannels::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED]
java.nio.channels.VMChannels,,java.nio.channels,java.nio.channels
[EMAIL PROTECTED] @code{java.nio.channels.VMChannels}
+
[EMAIL PROTECTED] provides the methods that create the channels or
+streams. The default implementation is in pure Java and simply wraps
+the channels in standard I/O classes from @code{java.io}.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] @code{createStream(Class,Channel)} -- Creates a
@code{FileChannel}
+which wraps an instance of the specified stream class, created by reflection.
+This method is private, and is used by the other two.
[EMAIL PROTECTED] @code{newInputStream(ReadableByteChannel)} -- Wraps the
channel
+in a @code{FileInputStream}.
[EMAIL PROTECTED] @code{newOutputStream(WritableByteChannel)} -- Wraps the
channel
+in a @code{FileOutputStream}.
[EMAIL PROTECTED] itemize
+
[EMAIL PROTECTED] gnu.java.nio, Classpath Callbacks, java.nio.channels,
Classpath Hooks
[EMAIL PROTECTED] gnu.java.nio
+
+The @code{gnu.java.nio} class provides Classpath implementations of the
+interfaces provided by @code{java.nio}. The VM classes provide the native
+support necessary to implement @emph{pipes} and @emph{selectors}.
+
[EMAIL PROTECTED]
+* gnu.java.nio.VMPipe::
+* gnu.java.nio.VMSelector::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED]
gnu.java.nio.VMPipe,gnu.java.nio.VMSelector,gnu.java.nio,gnu.java.nio
[EMAIL PROTECTED] @code{gnu.java.nio.VMPipe}
+
[EMAIL PROTECTED] provides the native functionality for a uni-directional pipe
+between a source and a destination (sink) channel. It consists of one
[EMAIL PROTECTED] @code{native} method, @code{init(PipeImpl,SelectorProvider)},
+the reference implementation of which is currently a native stub. Ideally,
+this should initialise the pipe at the native level.
+
[EMAIL PROTECTED] gnu.java.nio.VMSelector,,gnu.java.nio.VMPipe,gnu.java.nio
[EMAIL PROTECTED] @code{gnu.java.nio.VMSelector}
+
+A @code{Selector} selects between multiple @code{SelectableChannel}s based
+on their readiness and a key set. The VM hook for the Classpath implementation
+of this is @code{VMSelector}, and this allows the actual @code{select()}
+operation to be performed. This is represented by the @code{static}
[EMAIL PROTECTED] method, @code{select(int[],int[],int[],long)}, and a default
+implementation of this is provided.
+
[EMAIL PROTECTED] Classpath Callbacks, , gnu.java.nio, Classpath Hooks
Some of the classes you implement for the VM will need to call back to
package-private methods in Classpath:
@@ -221,10 +1060,8 @@ the group.
@item @code{java.lang.ThreadGroup.removeThread(Thread)}
Call this method from @code{Thread} when a @code{Thread} is stopped or
destroyed.
-
@end itemize
-
@node VM Hooks, JNI Implementation, Classpath Hooks, Top
@comment node-name, next, previous, up
@chapter VM Hooks
@@ -234,22 +1071,51 @@ unfortunately are dependent on the inter
classes. This is a guide to all of the things the VM itself needs to
know about classes.
+Some of the core classes, while being implemented by GNU Classpath,
+provide space for state (in the form of a @code{vmdata} object) to be
+stored by the VM, and can not be constructed normally.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] java.lang.Class
[EMAIL PROTECTED] java.lang.ClassLoader
[EMAIL PROTECTED] itemize
+
+The default implementations of some VM classes also follow this methodology,
+when it is intended that most VMs will keep the default.
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] java.lang.VMThread
[EMAIL PROTECTED] java.lang.VMThrowable
[EMAIL PROTECTED] itemize
+
+Several core classes must be completely implemented by the VM for Classpath to
+work, although reference implementations are provided. These classes are:
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED] java.lang.reflect.Constructor
[EMAIL PROTECTED] java.lang.reflect.Method
[EMAIL PROTECTED] java.lang.reflect.Field
[EMAIL PROTECTED] itemize
+
+The following issues are of note;
+
@itemize @bullet
@item @code{java.lang.Class} @*
-You, the VM, get to create this @code{Class}, so you may define the internal
-structure any way you wish. You probably have code somewhere to
-translate your internal class structure into a @code{Class} object. That is
-the only known place where this matters. Some VMs do not create the
[EMAIL PROTECTED] object at the point where the class is defined; instead, they
wait
-until a @code{Class} object is actually used.
+The GNU Classpath implementation of @code{java.lang.Class} provides an
+object for storing the internal state of the class maintained by the VM.
+This is the only known place where this matters. The class is
+constructed with this data by the VM. Some VMs do not create the
[EMAIL PROTECTED] object at the point where the class is defined; instead,
+they wait until a @code{Class} object is actually used.
@item Array Classes @*
-When you are creating an array class, you should set the @code{ClassLoader} of
-the array class to the @code{ClassLoader} of its component type. Whenever you
-add a class to a @code{ClassLoader}, you need to notify the @code{ClassLoader}
and
-add the new @code{Class} to its internal cache of classes. To do this, call
[EMAIL PROTECTED](Class)}. @emph{Note: this is written in
-anticipation of 1.2 support and does not apply just yet.}
+When you are creating an array class, you should set the
[EMAIL PROTECTED] of the array class to the @code{ClassLoader} of its
+component type. Whenever you add a class to a @code{ClassLoader}, you
+need to notify the @code{ClassLoader} and add the new @code{Class} to
+its internal cache of classes. To do this, call
[EMAIL PROTECTED](Class)}. @emph{Note: this is
+written in anticipation of 1.2 support and does not apply just yet.}
@item Primordial Class Loader @*
When the primordial class loader loads a class, it needs to tell
@@ -422,3 +1288,4 @@ to the value of the @code{LD_LIBRARY_PAT
@bye
+
signature.asc
Description: Digital signature
_______________________________________________ Classpath mailing list [email protected] http://lists.gnu.org/mailman/listinfo/classpath
