/[classpath]/classpath/doc/vmintegration.texinfo
ViewVC logotype

Diff of /classpath/doc/vmintegration.texinfo

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.18 by mark, Fri Jul 15 08:54:10 2005 UTC revision 1.19 by mark, Fri Jul 15 09:04:46 2005 UTC
# Line 110  provides a Java 1.1 compatible environme Line 110  provides a Java 1.1 compatible environme
110  The Electrical File VM continues to be listed as a Mozilla project  The Electrical File VM continues to be listed as a Mozilla project
111  though development has been somewhat quiet.  A number of concepts from  though development has been somewhat quiet.  A number of concepts from
112  EF were expected at one point to be rolled into Japhar, but that  EF were expected at one point to be rolled into Japhar, but that
113  development has not occured as of yet.  development has not occurred as of yet.
114    
115  @item @uref{http://latte.snu.ac.kr/,LaTTe}  @item @uref{http://latte.snu.ac.kr/,LaTTe}
116  This VM project so far supports only Sun UltraSparc processors using the  This VM project so far supports only Sun UltraSparc processors using the
# Line 175  The initialization order is currently do Line 175  The initialization order is currently do
175  @comment node-name, next, previous, up  @comment node-name, next, previous, up
176  @chapter Classpath Hooks  @chapter Classpath Hooks
177    
178  Several core classes must be implemented by the VM for Classpath to  The primary method of interaction between Classpath and the VM is via
179  work.  These classes are:  the helper classes, which are named after the relevant core library
180    class, but include an additional `VM' prefix.  The library classes from
181    Classpath call out to these to get certain VM-specific dirty work done.
182    A reference copy of each VM class exists.  The majority consist of a
183    series of static methods, some of which are simply declared
184    @code{native}, and some which provide a default implementation.  VMs may
185    either use these as is, or create their own local variations.  When
186    using the default implementations, the VM is responsible for
187    implementing any of the code marked as @code{native} which corresponds
188    to functionality they wish their VM to provide.  When using their own
189    versions of the classes, VM implementors may choose to change the mix of
190    native and non-native methods from that below, so as to best suit their
191    implementation.
192    
193    @menu
194    * java.lang::
195    * gnu.classpath::
196    * java.util::
197    * java.io::
198    * java.security::
199    * java.net::
200    * java.nio::
201    * java.nio.channels::
202    * gnu.java.nio::
203    * Classpath Callbacks::
204    @end menu
205    
206    @node java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks
207    @comment  node-name,  next,  previous,  up
208    
209    @section @code{java.lang}
210    
211    @code{java.lang} is the core Java package, being imported automatically by all
212    classes.  It includes basic classes as @code{Object} and @code{String}.
213    A VM must implement at least some parts of this package in order to
214    become operable.
215    
216    @menu
217    * java.lang.VMClass::
218    * java.lang.VMObject::
219    * java.lang.VMClassLoader::
220    * java.lang.VMSystem::
221    * java.lang.VMThrowable::
222    * java.lang.VMCompiler::
223    * java.lang.VMDouble::
224    * java.lang.VMFloat::
225    * java.lang.VMProcess::
226    * java.lang.VMRuntime::
227    * java.lang.VMString::
228    * java.lang.VMThread::
229    @end menu
230    
231    @node java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang
232    @subsection @code{java.lang.VMClass}
233    
234    The core class, @code{java.lang.Class}, and the corresponding VM class,
235    @code{java.lang.VMClass}, provide two main functions within GNU Classpath.
236    
237    @enumerate
238    @item For basic VM operation, @code{java.lang.Class} provides the link between
239    the Java-based representation of a class it embodies and the VM's own
240    internal structure for a class.  @xref{VM Hooks}.
241    
242    @item As far as the user is concerned, the main function of
243    @code{java.lang.Class} is as an entry point to the reflection
244    facilities, and so it also provides this functionality, backed by the
245    VM class.
246    @end enumerate
247    
248    This VM class lists the following methods, organized by the version of the
249    Java specification in which they occur.  All are @code{native}, unless
250    otherwise specified, and pertain to reflection.  As a result, the VM only
251    needs to implement these methods in order to provide reflection support,
252    and then only to the degree required.
253    
254  @itemize @bullet  @itemize @bullet
255  @item java.lang.Class  @item 1.0
256  @item java.lang.Runtime  @itemize @bullet
257  @item java.lang.Thread  @item @code{isInterface(Class)} -- This is simply a property test, and matches
258  @item java.lang.reflect.Constructor  the presence of an appropriate flag within the class file.
259  @item java.lang.reflect.Method  @item @code{getName(Class)} -- Returns the fully-qualified name of the class.
260  @item java.lang.reflect.Field  @item @code{getSuperclass(Class)} -- Returns a @code{Class} instance which
261    represents the superclass.  Again, the class file contains an element directly
262    relating to this.  @code{null} is returned for primitives, interfaces and
263    @code{Object}.
264    @item @code{getInterfaces(Class)} -- Same as the above, but the implemented
265    or extended interfaces rather than the superclass.  An empty array should
266    be returned, rather than @code{null}.
267    @item @code{getDeclaredClasses(Class,boolean)} -- Returns the internal classes
268    this instance declares directly.  The flag determines whether or not the
269    VM should filter out non-public classes.
270    @item @code{getDeclaredFields(Class,boolean)} -- The same for fields.
271    @item @code{getDeclaredMethods(Class,boolean)} -- And for methods.
272    @item @code{getDeclaredConstructors(Class,boolean)} -- And constructors.
273    @item @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance
274    which is responsible for the specified class.
275    @item @code{forName(String)} -- The VM should create a @code{Class} instance
276    corresponding to the named class.  As noted in @ref{VM Hooks}, the internal
277    content of the instance is the responsibility of the VM.
278    @item @code{isArray(Class)} -- Another property test, corresponding to a
279    class file flag.
280    @item @code{initialize(Class)} -- The VM should initialize the class fully,
281    if it has not already done so.
282    @item @code{loadArrayClass(String,ClassLoader)} -- This is called if
283    @code{forName} returns @code{null} and the string specifies an array class.
284    The specified array class should be loaded with the supplied class loader.
285    @item @code{throwException(Throwable)} -- The VM should throw the supplied
286    checked exception, without declaring it.
287    @end itemize
288    @item 1.1
289    @itemize @bullet
290    @item @code{isInstance(Class,Object)} -- This is a reflection-based equivalent
291    of the @code{instanceof} operator.
292    @item @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand for the above,
293    removing the need to create an instance to test assignability.  
294    @item @code{isPrimitive(Class)} -- Returns true if this class is simply
295    a representation of one of the primitive types: @code{boolean}, @code{byte},
296    @code{char}, @code{short}, @code{int}, @code{long}, @code{float},
297    @code{double} and @code{void}.
298    @item @code{getComponentType(Class)} -- Produces a @code{Class} instance which
299    represents the type of the members of the array the class instance represents.
300    Classes which don't represent an array type return @code{null}.
301    @item @code{getModifiers(Class,boolean)} -- Returns an integer which encodes
302    the class' modifiers, such as @code{public}.  Again, this relates to
303    information stored in the class file.
304    @item @code{getDeclaringClass(Class)} -- Returns the class that declared
305    an inner or member class, or @code{null} if the instance refers to a top-level
306    class.
307    @end itemize
308    @end itemize
309    
310    @node java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang
311    @subsection @code{java.lang.VMObject}
312    
313    @code{VMObject} is the bridge between the low level @code{Object} facilities
314    such as making a clone, getting the class of the object and the wait/notify
315    semantics.  This is accomplished using the following @code{native}
316    methods.
317    
318    @itemize @bullet
319    @item @code{getClass(Object)} -- Returns the @code{Class} instance for the
320    object.  @code{Class} objects are produced by the VM, as described in
321    @ref{VM Hooks}.
322    @item @code{clone(Cloneable)} -- The VM should produce a low-level clone of the
323    specified object, creating a field-by-field shallow copy of the original.
324    The only difference between the two is that the new object should still be
325    @code{finalizable}, even if the original is not.
326    @item @code{notify(Object)} -- The VM should choose one of the threads waiting
327    for a lock on the specified object arbitrarily, and wake it.  If the current
328    thread does not currently hold the lock on the object, then an
329    @code{IllegalMonitorStateException} should be thrown.
330    @item @code{notifyAll(Object)} -- Same as the above, but all threads are
331    awakened.
332    @item @code{wait(Object,long,int)} -- The VM should set the current thread
333    into a waiting state, which persists until it receives a notify signal or the
334    specified time (in milliseconds and nanoseconds) is exceeded.  The nanoseconds
335    restriction may be ignored if such granularity is not available, and a
336    @code{IllegalMonitorStateException} should be thrown if the current thread
337    doesn't own the object.
338    @end itemize
339    
340    @node java.lang.VMClassLoader, java.lang.VMSystem, java.lang.VMObject, java.lang
341    @subsection @code{java.lang.VMClassLoader}
342    @code{VMClassLoader} provides methods for defining and resolving core and
343    primitive classes, as well as handling resources, packages and assertions.
344    The class is a mixture of @code{native} methods and Java-based
345    implementations, with some of the latter being @emph{stubs}.
346    
347    @itemize @bullet
348    @item Native Methods
349    @itemize @bullet
350    @item @code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}
351    -- The VM should create a @code{Class} instance from the supplied byte array.
352    @item @code{resolveClass(Class)} -- Resolve references to other classes in the
353    supplied class.
354    @item @code{loadClass(name,boolean)} -- Load a class using the bootstrap
355    loader.
356    @item @code{getPrimitiveClass(char)} -- The VM should provide a @code{Class}
357    implementation for one of the primitive classes.  The supplied character
358    matches the JNI code for the primitive class e.g. `B' for byte and
359    `Z' for boolean.
360    @end itemize
361    @item Java Methods
362    @itemize @bullet
363    @item @code{getResource(String)} -- The default implementation calls
364    @code{getResources} and returns the first element in the returned enumeration,
365    or @code{null} if there are no elements.
366    @item @code{getResources(String)} -- By default, this compiles a list of
367    URLs via the boot class path.  Any matching files within a zip file are added,
368    and directories on the boot class path are automatically converted to file
369    URLs that refer to join the directory with the resource name (whether or not
370    it actually exists).
371    @item @code{getPackage(String)} -- Always returns null, which may be suitable
372    if the VM does not wish to return a @code{Package} implementation. Otherwise,
373    it may be necessary to make this a @code{native} method.
374    @item @code{getPackages()} -- As with the last, a default stub implementation
375    exists (returning an empty array) which may be replaced if support is
376    required.
377    @item @code{defaultAssertionStatus()} -- A stub which can be implemented
378    by VMs providing assertion support.  At present, it always returns @code{true}.
379    @item @code{packageAssertionStatus()} -- Much the same status as the above.
380    The method should return a map converting package names to boolean status
381    values.  The stub implementation provides an empty map.
382    @item @code{classAssertionStatus()} -- Same as the last, but for classes.
383    @item @code{getSystemClassLoader()} -- The default calls @code{ClassLoader}
384    to create a new auxillary class loader with a system and extension class
385    loader.  The VM may wish to replace it if it wishes to supply its own custom
386    system class loader.
387    @end itemize
388    @end itemize
389    @node java.lang.VMSystem, java.lang.VMThrowable, java.lang.VMClassLoader, java.lang
390    @subsection @code{java.lang.VMSystem}
391    @code{VMSystem} handles the default I/O streams, provides access to the
392    system clock and environment variables and provides methods for
393    @code{System.arraycopy} and the @code{identityHashCode} of an
394    @code{Object}.  It consists of @code{native} methods, but the default
395    implementation also provides some helper methods to simplify stream
396    creation.  
397    
398    @itemize @bullet
399    @item Native Methods
400    @itemize @bullet
401    @item @code{arraycopy(Object,int,Object,int,int)} -- The VM should copy
402    a specified number of array objects from one array to another, with
403    appropriate checks for compatible typing, available elements and space.
404    The VM should be able to perform this more efficiently using native code
405    and direct memory manipulation than would have been achieved by using Java.
406    @item @code{identityHashCode(Object)} -- This is the hashcode for
407    @code{Object}, which relates to the actual location of the object in memory.
408    @item @code{setIn(InputStream)} -- Set the system input stream.
409    @item @code{setOut(PrintStream)} -- Set the system output stream.
410    @item @code{setErr(PrintStream)} -- Set the system error stream.
411    @item @code{currentTimeMillis()} -- Gets the system time in milliseconds.
412    @item @code{getenv(String)} -- Returns the value of the specified environment
413    variable.
414    @end itemize
415    @item Java Methods
416    @itemize @bullet
417    @item @code{makeStandardInputStream()} -- Helps provide the functionality of
418    @code{System.in} by wrapping the appropriate file descriptor in a buffered
419    file input stream.  VMs may choose to create the stream from the descriptor
420    differently rather than using this method.
421    @item @code{makeStandardOutputStream()} -- Helps provide the functionality of
422    @code{System.out} by wrapping the appropriate file descriptor in a buffered
423    file output stream.  VMs may choose to create the stream from the descriptor
424    differently rather than using this method.
425    @item @code{makeStandardErrorStream()} -- Helps provide the functionality of
426    @code{System.err} by wrapping the appropriate file descriptor in a buffered
427    file output stream.  VMs may choose to create the stream from the descriptor
428    differently rather than using this method.
429    @end itemize
430    @end itemize
431    
432    Classpath also provides native implementations of
433    
434    @itemize @bullet
435    @item @code{setIn(InputStream)}
436    @item @code{setOut(PrintStream)}
437    @item @code{setErr(PrintStream)}
438    @item @code{currentTimeMillis()}
439    @item @code{getenv(String)}
440    @end itemize
441    
442    making a VM implementation optional.
443    
444    @node java.lang.VMThrowable, java.lang.VMCompiler, java.lang.VMSystem, java.lang
445    @subsection @code{java.lang.VMThrowable}
446    @code{VMThrowable} is used to hold the VM state of a throwable, created either
447    when a @code{Throwable} is created or the @code{fillInStackTrace()} method is
448    called (i.e. when the actual stack trace is needed, as a lot of exceptions are
449    never actually used).  The actual class has two @code{native} methods,
450    one (@code{fillInStackTrace()}) being a method of the class used to obtain
451    instances, and the other an instance method, @code{getStackTrace()}.
452    @itemize @bullet
453    @item @code{fillInStackTrace(Throwable)} -- The VM should return the current
454    execution state of the @code{Throwable} in the form of a @code{VMThrowable}
455    instance.  The VM may also return @code{null} if it does not support this
456    functionality.
457    @item @code{getStackTrace()} -- This is used to create a real
458    @code{StackTraceElement} array for the exception, using the state data
459    stored during creation of the instance.
460    @end itemize
461    
462    @node java.lang.VMCompiler, java.lang.VMDouble, java.lang.VMThrowable, java.lang
463    @subsection @code{java.lang.VMCompiler}
464    
465    @code{VMCompiler} provides an interface for VMs which wish to provide
466    JIT compilation support.  The default implementation is simply a series
467    of stubs. The property, @code{java.compiler}, should point to a library
468    containing the function @code{java_lang_Compiler_start()} if such support
469    is to be provided.
470    
471    @itemize @bullet
472    @item @code{compileClass(Class)} -- Invoke the compiler to compile the specific
473    class, returning @code{true} if successful.
474    @item @code{compileClasses(String)} -- The compiler should compile the classes
475    matching the specified string, again returning @code{true} on success.
476    @item @code{command(Object)} -- The object represents a command given to the
477    compiler, and is specific to the compiler implementation.
478    @item @code{enable} -- Enable the operation of the compiler.
479    @item @code{disable} -- Disable compiler operation.
480    @end itemize
481    
482    @node java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler, java.lang
483    @subsection @code{java.lang.VMDouble}
484    
485    @code{VMDouble} provides native support for the conversion and parsing
486    of doubles.
487    
488    @itemize @bullet
489    @item @code{doubleToLongBits(double)} -- Converts the double to the IEEE 754
490    bit layout, collapsing NaNs to @code{0x7ff8000000000000L}.
491    @item @code{doubleToRawLongBits(double)} -- Same as the above, but preserves
492    NaNs.
493    @item @code{longBitsToDouble(long)} -- This is the inverse of the last method,
494    preserving NaNs so that the output of one can be fed into the other without
495    data loss.
496    @item @code{toString(double,boolean)} -- Converts the double to a string,
497    giving a shorter value if the flag @code{isFloat} is @code{true}, indicating
498    that the conversion was requested by @code{java.lang.Float} rather than
499    @code{java.lang.Double}.
500    @item @code{initIDs} -- Used by JNI-based solutions to initialize the cache
501    of the static field IDs.  The default @code{VMDouble} implementation has a
502    static initializer which loads the JNI library and calls this method.
503    @item @code{parseDouble} -- Turn the string into a usable double value.
504    @end itemize
505    
506    Classpath provides native implementations of all these, making VM
507    implementation optional.
508    
509    @node java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble, java.lang
510    @subsection @code{java.lang.VMFloat}
511    
512    @code{VMFloat} provides native support for the conversion of floats.
513    
514    @itemize @bullet
515    @item @code{floatToIntBits(float)} -- Converts the float to the IEEE 754
516    bit layout, collapsing NaNs to @code{0x7fc00000}.
517    @item @code{floatToRawIntBits(float)} -- Same as the above, but preserves
518    NaNs.
519    @item @code{intBitsToFloat(int)} -- This is the inverse of the last method,
520    preserving NaNs so that the output of one can be fed into the other without
521    data loss.
522    @end itemize
523    
524    Classpath provides native implementations of all these, making VM
525    implementation optional.
526    
527    @node java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat, java.lang
528    @subsection @code{java.lang.VMProcess}
529    
530    @code{VMProcess} handles the execution of external processes.  In the
531    default implementation, threads are spawned and reaped by @code{ProcessThread}.
532    A constructor creates a new @code{VMProcess}, which extends rather than
533    complements @code{Process}, using an array of arguments, an array of
534    environment variables and a working directory.  The instance maintains
535    system input, output and error streams linked to the external process.
536    Three @code{native} methods are used, and implementations are provided
537    for all three by Classpath, making VM implementation optional.  These use
538    the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.
539    
540    @itemize @bullet
541    @item @code{nativeSpawn(String[],String[],File)} -- The VM should create a
542    new process which uses the specified command-line arguments, environment
543    variables and working directory.  Unlike the other two methods, this
544    method is linked to an instance, and must call @code{setProcessInfo()} with
545    the results before returning.
546    @item @code{nativeReap()} -- This is called to perform a reap of any
547    zombie processes, and should not block, instead returning a boolean as to
548    whether reaping actually took place.
549    @item @code{nativeKill(long)} -- The VM should terminate the specified PID.
550    @end itemize
551    
552    @node java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess, java.lang
553    @subsection @code{java.lang.VMRuntime}
554    
555    The @code{VMRuntime} class provides a series of native methods
556    which divulge information about the runtime or invoke certain
557    operations.  This includes retrieving the amount of available memory,
558    and scheduling the garbage collector.  There are two exceptions: the
559    @code{enableShutdownHooks} method, which allows the VM to put in its own
560    shutdown hooks when @code{Runtime.addShutdownHook()} is first invoked,
561    and @code{exec(String[],String[],File)} which spawns an external process.
562    These are Java-based static methods instead.  The first is simply a stub by
563    default, while the second simply links to the functionality of
564    @code{VMProcess} (and should be changed if a different @code{Process}
565    implementation is used).
566    
567    @itemize @bullet
568    @item @code{availableProcessors()} -- Returns the number of processors
569    available to the VM.
570    @item @code{freeMemory()} -- Returns the amount of memory the VM has available
571    on the heap for allocating.
572    @item @code{totalMemory()} -- Returns the size of the heap.
573    @item @code{maxMemory()} -- Returns the maximum memory block the VM will
574    attempt to allocate.  May be simply @code{Long.MAX_VALUE} (8 exabytes!)
575    @item @code{gc()} -- Allows users to explicitly invoke the garbage collector.
576    This is a suggestion to the VM, rather than a command, and the garbage
577    collector should run anyway @emph{without} it being invoked.
578    @item @code{runFinalization()} -- Like the above, but related to the
579    finalilzation of objects rather than the garbage collector.
580    @item @code{runFinalizationForExit()} -- Called immediately prior to VM
581    shutdown in order to finalize all objects (including `live' ones)
582    @item @code{traceInstructions(boolean)} -- This turns on and off the optional
583    VM functionality of printing a trace of executed bytecode instructions.
584    @item @code{traceMethodCalls(boolean)} -- This turns on and off the optional
585    VM functionality of printing a trace of methods called.
586    @item @code{runFinalizersOnExit(boolean)} -- A toggleable setting for
587    running the finalization process at exit.
588    @item @code{exit(int)} -- The VM should shutdown with the specified exit code.
589    @item @code{nativeLoad(String,ClassLoader)} -- Attempts to load a file,
590    returning an integer which is non-zero for success.  Nothing happens if the
591    file has already been loaded.
592    @item @code{mapLibraryName(String)} -- The VM should map the system-independent
593    library name supplied to the platform-dependent equivalent (e.g. a @code{.so}
594    or @code{.dll} file)
595    @end itemize
596    
597    @node java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime, java.lang
598    @subsection @code{java.lang.VMString}
599    @code{VMString} is responsible for handling interned strings.  If two strings
600    are equal (using the @code{equals()} method), then the results of calling
601    the @code{intern()} method on each of them makes them equal
602    (using @code{==}).  Thus, the same string object is always returned by
603    @code{intern} if the two strings are equal.  The default implementation
604    is Java-based and implements @code{intern(String)} by maintaining a
605    @code{WeakHashMap} which links the strings to their @code{WeakReference}.
606    A new mapping is created for each new string being @code{intern}ed.  
607    A VM may implement this differently by implementing this method,
608    which is @code{static} and the only one in @code{VMString}.
609    
610    @node java.lang.VMThread,, java.lang.VMString, java.lang
611    @subsection @code{java.lang.VMThread}
612    
613    @code{VMThread} provides the link between Java's threads and the platform
614    threading support.  A @code{VMThread} is created via a private constructor
615    and linked to a @code{Thread} instance.  This occurs when the @code{Thread}
616    instance is started by the static @code{create(Thread,long)} method (the second
617    argument requests a certain stack size, usually zero).  The thread itself is
618    executed via the @code{run()} method, which handles any problems with the
619    running of the thread and its eventual death.
620    
621    @code{VMThread} provides the following accessors and mutators for accessing
622    the thread state via @code{VMThread},
623    
624    @itemize @bullet
625    @item @code{getName()}
626    @item @code{setName(String)}
627    @item @code{getPriority()}
628    @item @code{setPriotity(int)}
629    @item @code{isDaemon()}
630    @end itemize
631    
632    all of which refer to the @code{Thread} instance. @code{setPriority(int)} also
633    calls the appropriate native method.  @code{stop(Throwable)} similarly wraps
634    a native method, merely adding in a check for the state of the thread.
635    
636    The default implementation also provides Java-based implementations of
637    @code{join(long,int)}, @code{sleep(long,int)} and
638    @code{holdsLock(Object)}.  @code{join} and @code{sleep} simply wait for
639    the appropriate amount of time, with @code{join} additionally waiting
640    for the thread instance to become @code{null}.  @code{holdsLock} simply
641    checks if an object is locked by the current thread by trying to invoke
642    the @code{notify} method, and catching the failing exception if this is
643    not the case.
644    
645    The remainder of the class is a series of @code{native} methods, some of
646    which are mandatory for VM implementation and others which provide optional
647    or deprecated functionality.
648    
649    @itemize @bullet
650    @item Mandatory Instance Methods
651    @itemize @bullet
652    @item @code{start(long)} -- The VM should create the native thread and start
653    it running using the @code{run} method of the @code{VMThread} instance on
654    which this method is called.
655    @item @code{interrupt()} -- The VM should interrupt the running thread and
656    throw an appropriate exception.
657    @item @code{isInterrupted()} -- Checks the interrupted state of the thread.
658    @item @code{suspend()} -- The thread should be suspended until resumed.
659    @item @code{resume()} -- The thread should be resumed from its suspended state.
660    This pair of methods are deprecated, due to the possibility of a deadlock
661    occuring when a thread with locks is suspended.
662    @item @code{nativeSetPriority(int)} -- Called by @code{setPriority}
663    to allow the setting to flow down to the native thread.
664    @item @code{nativeStop(Throwable)} -- The VM should stop the thread abnormally
665    and throw the specified exception.  This is clearly deprecated, due to the
666    ambiguous state an abruptly-stopped thread may leave.
667    @end itemize
668    @item Mandatory Class Methods
669    @itemize @bullet
670    @item @code{currentThread()} -- Return a reference to the thread currently
671    being executed.
672    @item @code{yield()} -- The VM should allow some other thread to run.
673    The current thread maintains its locks even though it stops executing for
674    the time being.
675    @item @code{interrupted()} -- A shortcut to obtaining the interrupted state
676    of the current thread.
677    @end itemize
678    @item Other Methods
679    @itemize @bullet
680    @item @code{countStackFrames()} -- Returns a count of the number of stack
681    frames in the thread.  This depends on the deprecated method @code{suspend()}
682    having returned true, and is thus deprecated as a result.
683    @end itemize
684    @end itemize
685    
686    @node gnu.classpath, java.util, java.lang, Classpath Hooks
687    @section @code{gnu.classpath}
688    
689    The @code{gnu.classpath} package provides Classpath-specific functionality,
690    primarily relating to the features in @code{java.lang}.  At present, this
691    includes the context of a class (the stack) and the system properties.
692    
693    @menu
694    * gnu.classpath.VMStackWalker::
695    * gnu.classpath.VMSystemProperties::
696    @end menu
697    
698    @node gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
699    @subsection @code{gnu.classpath.VMStackWalker}
700    
701    @code{VMStackWalker} provides access to the class context or stack.  The
702    default implementation consists of a @code{native} @code{static} method,
703    @code{getClassContext()}, which obtains the class context, and two helper
704    methods which obtain the calling class (the 3rd element in the context array)
705    and its class loader, respectively.
706    
707    @itemize @bullet
708    @item @code{getClassContext()} -- The VM should return an array of
709    @code{Class} objects, each of which relates to the method currently being
710    executed at that point on the stack.  Thus, the first item (index 0) is the
711    class that contains this method.
712    @item @code{getCallingClass()} -- A Java-based helper method which returns
713    the @code{Class} object which contains the method that called the method
714    accessing @code{getCallingClass()}.
715    @item @code{getCallingClassLoader()} -- Like the last, but returning the class
716    loader of the class.
717    @end itemize
718    
719    @node gnu.classpath.VMSystemProperties,,gnu.classpath.VMStackWalker,gnu.classpath
720    @subsection @code{gnu.classpath.VMSystemProperties}
721    
722    @code{VMSystemProperties} allows the VM to hook into the property creation
723    process, both before and after the system properties are added by GNU
724    Classpath.  The default implementation assumes that the VM will add its
725    properties first, by making the pre-initialisation method @code{native},
726    and that the Classpath properties may then be altered by a Java-based
727    post-initialisation method.
728    
729    As these methods are called as part of the bootstrap process, caution should
730    be used as to what classes are used, and properties should only be set
731    using @code{Properties.setProperty()}.  Specifically, I/O classes should be
732    avoided at this early stage.
733    
734    @itemize @bullet
735    @item @code{preInit(Properties)} -- Allows the VM to add properties
736    @emph{before} the Classpath properties are added. The default implementation
737    includes a full list of properties that @emph{must} be added by the VM, but
738    additional VM-specific ones may also be added.  
739    @item @code{postInit(Properties)} -- Same as the last, but called after the
740    Classpath properties have been added.  The main purpose of this is to allow
741    the VM to alter the properties added by GNU Classpath to suit it.
742    @end itemize
743    
744    @node java.util, java.io, gnu.classpath, Classpath Hooks
745    @section java.util
746    
747    The @code{java.util} VM hooks provide links between the mix of functionality
748    present in that package, which includes collections, date and time handling
749    and parsing.  At present, there is only one hook, which connects GNU Classpath
750    to the timezone information provided by the underlying platform.
751    
752    @menu
753    * java.util.VMTimeZone::
754    @end menu
755    
756    @node java.util.VMTimeZone,,java.util,java.util
757    @subsection @code{java.util.VMTimeZone}
758    
759    @code{VMTimeZone} joins @code{TimeZone} to the platform timezone information
760    via the static method, @code{getDefaultTimeZoneId()}.  The VM hook is
761    expected to return a @code{TimeZone} instance that represents the current
762    timezone in use by the platform.  The default implementation provides
763    this functionality for POSIX or GNU-like systems, and VMs that want this
764    functionality can keep this implementation and implement the native
765    method, @code{getSystemTimeZoneId()}.  This method is only called when
766    obtaining the timezone name from the @code{TZ} environment variable,
767    @code{/etc/timezone} and @code{/etc/localtime} all fail.  This fallback
768    mechanism also means that a system which doesn't provide the above three
769    methods, but does provide a timezone in string form, can still use this
770    implementation.
771    
772    @node java.io, java.security, java.util, Classpath Hooks
773    @section java.io
774    
775    The @code{java.io} package is heavily reliant on access to the I/O facilities
776    of the underlying platform.  As far as its VM hooks go, they provide two
777    areas of functionality to GNU Classpath, these being
778    
779    @itemize @bullet
780    @item File and directory queries and manipulation
781    @item Serialization of objects
782    @end itemize
783    
784    The first corresponds directly to most of the @code{File} class, while
785    the latter underlies the functionality provided by the
786    @code{ObjectInputStream} and @code{ObjectOutputStream}.  More low-level I/O
787    is provided by @ref{java.nio}.
788    
789    @menu
790    * java.io.VMFile::
791    * java.io.VMObjectInputStream::
792    * java.io.VMObjectStreamClass::
793    @end menu
794    
795    @node java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
796    @subsection @code{java.io.VMFile}
797    
798    @code{VMFile} allows GNU Classpath's @code{File} representations to
799    probe and modify the file system using the native functions of the
800    platform.  The default implementation (which consists of both a
801    @code{VMFile} class and the native methods) is primarily UNIX-centric,
802    working with POSIX functions and assuming case-sensitive filenames,
803    without the restriction of the 8.3 format.  It consists mainly of
804    @code{static} @code{native} methods, with a few Java helper methods.
805    The native methods represent the file as a string containing its path,
806    rather than using the object itself.
807    
808    @itemize @bullet
809    @item Native Methods
810    @itemize @bullet
811    @item @code{lastModified(String)} -- The native method should return a
812    @code{long} value that represents the last modified date of the file.
813    @item @code{setReadOnly(String)} -- Sets the file's permissions to read only,
814    in whichever way this is realised by the platform.
815    @item @code{create(String)} -- Create the named file.
816    @item @code{list(String)} -- The native method opens the named directory,
817    reads the contents and returns them as a Java @code{String} array.
818    @item @code{renameTo(String,String)} -- Renames the first file to the second.
819    @item @code{length(String)} -- Returns a @code{long} value representing
820    the file size.
821    @item @code{exists(String)} -- Tests for the existence of the named file
822    or directory.
823    @item @code{delete(String)} -- Deletes the file or directory.
824    @item @code{setLastModified(String,long)} -- Change the last modified time.
825    @item @code{mkdir(String)} -- Creates the named directory.
826    @item @code{isFile(String)} -- Tests that the named path references a file.
827    @item @code{canWrite(String)} -- Tests that the file can be written to.
828    This method is @code{synchronized}, so the object is locked during the check.
829    @item @code{canRead(String)} -- Complement of the last method.
830    @item @code{isDirectory(String)} -- Tests that the named path references
831    a directory.
832    @end itemize
833    @item Java Helper Methods
834    @itemize @bullet
835    @item @code{canWriteDirectory(File)} -- Checks that the directory can be
836    written to, by trying to create a temporary file in it.
837    @item @code{listRoots()} -- Returns the root of a GNU filesystem i.e. `/'
838    in an array.
839    @item @code{isHidden(String)} -- Checks whether the file starts with `.',
840    which is how files are hidden on UNIX-style systems.
841    @item @code{getName(String)} -- Pulls the actual filename from the end of
842    the path, by breaking off the characters after the last occurrence of the
843    platform's file separator.
844    @item @code{getCanonicalForm(String)} -- This converts a UNIX path to
845    its canonical form by removing the `.' and `..' sections that occur within.
846  @end itemize  @end itemize
847    @end itemize
848    
849    @node java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
850    @subsection @code{java.io.VMObjectInputStream}
851    
852    This class consists of two methods which provide functionality used in
853    deserializing an object.  @code{currentClassLoader()} provides the first
854    user-defined class loader from the class context
855    (@xref{gnu.classpath.VMStackWalker},) via a @code{PrivilegedAction}.
856    @code{allocateObject(Class,Class,Constructor)} is a @code{native} method
857    (a reference implementation is provided) which creates an object but
858    calls the constructor of another class, which is a superclass of the
859    object's class.
860    
861    @node java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
862    @subsection @code{java.io.VMObjectStreamClass}
863    
864    @code{VMObjectStreamClass} is a series of @code{static} @code{native}
865    methods that provide some of the groundwork for @code{ObjectStreamClass}
866    and @code{ObjectStreamField}.  @code{hasClassInitializer(Class)} works
867    with the former, and checks for the presence of a static initializer.
868    The remaining methods are of the form @code{setXXXNative(Field,Object,XXX)}
869    and support @code{ObjectStreamField}.  One exists for each of the main types
870    (boolean, float, double, long, int, short, char, byte and object) and is used
871    to set the specified field in the supplied instance to the given value.
872    
873    A default implementation is provided for all of them, so a VM implementation
874    is optional.
875    
876    @node java.security, java.net, java.io, Classpath Hooks
877    @section java.security
878    
879    The @code{java.security} package provides support for Java's security
880    architecture.  At present, @code{VMAccessController} represents the sole
881    VM hook for this.
882    
883  You also need to implement some helper classes in java.lang that classes  @menu
884  from Classpath call out to to get certain VM-specific dirty work done:  * java.security.VMAccessController::
885    @end menu
886    
887    @node java.security.VMAccessController,,java.security,java.security
888    @subsection @code{java.security.VMAccessController}
889    
890    The @code{AccessController} is used to perform privileged actions.  Its
891    hook class, @code{VMAccessController}, maintains the
892    @code{AccessControlContext} and the default implementation is purely
893    Java-based.  The VM may choose to replace this with their own.
894    The methods in the reference version are as follows:
895    
896  @itemize @bullet  @itemize @bullet
897  @item @code{java.lang.VMObject}  @item @code{pushContext(AccessControlContext)} -- Adds a new context to the
898  is the bridge between the low level @code{Object} facilities such  stack for the current thread.  This is called before a privileged action
899  as making a clone, getting the class of the object and the wait/notify  takes place.
900  semantics.  @item @code{popContext()} -- Removes the top context from the stack.  This
901  @item @code{java.lang.VMClassLoader}  is performed after the privileged action takes place.
902  provides methods for defining and resolving core and primitive classes.  @item @code{getContext()} -- Either derives a context based on the
903  @item @code{java.lang.VMSystem}  @code{ProtectionDomain}s of the call stack (see the next method) or returns
904  is used to initialize the @code{System} properties, the @code{System.arraycopy}  the top of the context stack.
905  method and the @code{identityHashCode} of an @code{Object}.  @item @code{getStack()} -- Provides access to the call stack as a pair of
906  @item @code{java.lang.VMSecurityManager}  arrays of classes and method names.  The actual implementation returns
907  provides the class context (stack trace) of the currently  an empty array, indicating that there are no permissions.
 executing thread and a way to get the currently active @code{ClassLoader}.  
 @item @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  
 @code{getStackTrace()} method is used to create a real @code{StackTraceElement} array  
 for the exception.  
908  @end itemize  @end itemize
909    
910    @node java.net, java.nio, java.security, Classpath Hooks
911    @section java.net
912    
913    The @code{java.net} package is heavily reliant on access to the networking
914    facilities of the underlying platform.  The VM hooks provide information
915    about the available network interfaces, and access to lookup facilities
916    for network addresses.
917    
918    @menu
919    * java.net.VMInetAddress::
920    * java.net.VMNetworkInterface::
921    @end menu
922    
923    @node java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
924    @subsection @code{java.net.VMInetAddress}
925    
926    @code{VMInetAddress} is a series of @code{static} @code{native} methods
927    which provide access to the platform's lookup facilities.  All the methods
928    are implemented by GNU Classpath, making VM implementation optional, and
929    are as follows:
930    
931    @itemize @bullet
932    @item @code{getLocalHostname()} -- Wraps the @code{gethostname} function, and
933    falls back on `localhost'.
934    @item @code{lookupInaddrAny()} -- Returns the value of @code{INADDR_ANY}.
935    @item @code{getHostByAddr(byte[])} -- Looks up the hostname based on an IP
936    address.
937    @item @code{getHostByName(String)} -- The reverse of the last method, it
938    returns the IP addresses which the given host name resolves to.
939    @end itemize
940    
941    @node java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
942    @subsection @code{java.net.VMNetworkInterface}
943    
944    @code{VMNetworkInterface} currently consists of a single @code{static}
945    @code{native} method, @code{getInterfaces()}, which retrieves the
946    network interfaces available on the underlying platform as a @code{Vector}.
947    The current GNU Classpath implementation is a native stub.
948    
949    @node java.nio, java.nio.channels, java.net, Classpath Hooks
950    @section java.nio
951    
952    The @code{java.nio} package is part of the New I/O framework added in
953    Java 1.4.  This splits I/O into the concepts of @emph{buffers},
954    @emph{charsets}, @emph{channels} and @emph{selectors}, and
955    @code{java.nio} defines the buffer classes.  As far as native and VM
956    code is concerned, the new package needs support for low-level efficient
957    buffer operations.
958    
959    @menu
960    * java.nio.VMDirectByteBuffer::
961    @end menu
962    
963    @node java.nio.VMDirectByteBuffer,,java.nio,java.nio
964    @subsection @code{java.nio.VMDirectByteBuffer}
965    
966    A @code{ByteBuffer} maintains a buffer of bytes, and allows it to be
967    manipulated using primitive operations such as @code{get}, @code{put},
968    @code{allocate} and @code{free}.  A direct buffer avoids intermediate
969    copying, and uses native data which shouldn't be manipulated by a
970    garbage collector.  The VM class consists of @code{static} @code{native}
971    methods, all of which are given default implementations by GNU
972    Classpath.
973    
974    @itemize @bullet
975    @item @code{init()} -- Creates an instance of an appropriate
976    @code{gnu.classpath.RawData} class.  This class is not garbage
977    collected, is created natively and is used in the other methods to reference
978    the buffered data.
979    @item @code{allocate(int)} -- Allocates the memory for the buffer using
980    @code{malloc} and returns a reference to the @code{RawData} class.
981    @item @code{free(RawData)} -- Frees the memory used by the buffer.
982    @item @code{get(RawData,int)}  -- Returns the data at the specified index.
983    @item @code{get(RawData,int,byte[],int,int)} -- Copies a section of the
984    data into a byte array using @code{memcpy}.
985    @item @code{put(RawData,int,byte)} -- Puts the given data in the buffer
986    at the specified index.
987    @item @code{adjustAddress(RawData,int)} -- Adjusts the pointer into the buffer.
988    @item @code{shiftDown(RawData,int,int,int)} -- Moves the content of the buffer
989    at an offset down to a new offset using @code{memmove}.
990    @end itemize
991    
992    @node java.nio.channels, gnu.java.nio, java.nio, Classpath Hooks
993    @section java.nio.channels
994    
995    Channels provide the data for the buffers with the New I/O packages.
996    For example, a channel may wrap a file or a socket.  The VM hooks,
997    at the moment, simply allow the channels to be accessed by @code{java.io}
998    streams.
999    
1000    @menu
1001    * java.nio.channels.VMChannels::
1002    @end menu
1003    
1004    @node java.nio.channels.VMChannels,,java.nio.channels,java.nio.channels
1005    @subsection @code{java.nio.channels.VMChannels}
1006    
1007    @code{VMChannels} provides the methods that create the channels or
1008    streams.  The default implementation is in pure Java and simply wraps
1009    the channels in standard I/O classes from @code{java.io}.
1010    
1011    @itemize @bullet
1012    @item @code{createStream(Class,Channel)} -- Creates a @code{FileChannel}
1013    which wraps an instance of the specified stream class, created by reflection.
1014    This method is private, and is used by the other two.
1015    @item @code{newInputStream(ReadableByteChannel)} -- Wraps the channel
1016    in a @code{FileInputStream}.
1017    @item @code{newOutputStream(WritableByteChannel)} -- Wraps the channel
1018    in a @code{FileOutputStream}.
1019    @end itemize
1020    
1021    @node gnu.java.nio, Classpath Callbacks, java.nio.channels, Classpath Hooks
1022    @section gnu.java.nio
1023    
1024    The @code{gnu.java.nio} class provides Classpath implementations of the
1025    interfaces provided by @code{java.nio}.  The VM classes provide the native
1026    support necessary to implement @emph{pipes} and @emph{selectors}.
1027    
1028    @menu
1029    * gnu.java.nio.VMPipe::
1030    * gnu.java.nio.VMSelector::
1031    @end menu
1032    
1033    @node gnu.java.nio.VMPipe,gnu.java.nio.VMSelector,gnu.java.nio,gnu.java.nio
1034    @subsection @code{gnu.java.nio.VMPipe}
1035    
1036    @code{VMPipe} provides the native functionality for a uni-directional pipe
1037    between a source and a destination (sink) channel.  It consists of one
1038    @code{static} @code{native} method, @code{init(PipeImpl,SelectorProvider)},
1039    the reference implementation of which is currently a native stub.  Ideally,
1040    this should initialise the pipe at the native level.
1041    
1042    @node gnu.java.nio.VMSelector,,gnu.java.nio.VMPipe,gnu.java.nio
1043    @subsection @code{gnu.java.nio.VMSelector}
1044    
1045    A @code{Selector} selects between multiple @code{SelectableChannel}s based
1046    on their readiness and a key set.  The VM hook for the Classpath implementation
1047    of this is @code{VMSelector}, and this allows the actual @code{select()}
1048    operation to be performed.  This is represented by the @code{static}
1049    @code{native} method, @code{select(int[],int[],int[],long)}, and a default
1050    implementation of this is provided.
1051    
1052    @node Classpath Callbacks, , gnu.java.nio, Classpath Hooks
1053  Some of the classes you implement for the VM will need to call back to  Some of the classes you implement for the VM will need to call back to
1054  package-private methods in Classpath:  package-private methods in Classpath:
1055    
# Line 221  the group. Line 1060  the group.
1060    
1061  @item @code{java.lang.ThreadGroup.removeThread(Thread)}  @item @code{java.lang.ThreadGroup.removeThread(Thread)}
1062  Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.  Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.
   
1063  @end itemize  @end itemize
1064    
   
1065  @node VM Hooks, JNI Implementation, Classpath Hooks, Top  @node VM Hooks, JNI Implementation, Classpath Hooks, Top
1066  @comment node-name, next, previous, up  @comment node-name, next, previous, up
1067  @chapter VM Hooks  @chapter VM Hooks
# Line 234  unfortunately are dependent on the inter Line 1071  unfortunately are dependent on the inter
1071  classes.  This is a guide to all of the things the VM itself needs to  classes.  This is a guide to all of the things the VM itself needs to
1072  know about classes.  know about classes.
1073    
1074    Some of the core classes, while being implemented by GNU Classpath,
1075    provide space for state (in the form of a @code{vmdata} object) to be
1076    stored by the VM, and can not be constructed normally.
1077    
1078    @itemize @bullet
1079    @item java.lang.Class
1080    @item java.lang.ClassLoader
1081    @end itemize
1082    
1083    The default implementations of some VM classes also follow this methodology,
1084    when it is intended that most VMs will keep the default.
1085    
1086    @itemize @bullet
1087    @item java.lang.VMThread
1088    @item java.lang.VMThrowable
1089    @end itemize
1090    
1091    Several core classes must be completely implemented by the VM for Classpath to
1092    work, although reference implementations are provided.  These classes are:
1093    
1094    @itemize @bullet
1095    @item java.lang.reflect.Constructor
1096    @item java.lang.reflect.Method
1097    @item java.lang.reflect.Field
1098    @end itemize
1099    
1100    The following issues are of note;
1101    
1102  @itemize @bullet  @itemize @bullet
1103  @item @code{java.lang.Class} @*  @item @code{java.lang.Class} @*
1104  You, the VM, get to create this @code{Class}, so you may define the internal  The GNU Classpath implementation of @code{java.lang.Class} provides an
1105  structure any way you wish.  You probably have code somewhere to  object for storing the internal state of the class maintained by the VM.
1106  translate your internal class structure into a @code{Class} object.  That is  This is the only known place where this matters.  The class is
1107  the only known place where this matters.  Some VMs do not create the  constructed with this data by the VM.  Some VMs do not create the
1108  @code{Class} object at the point where the class is defined; instead, they wait  @code{Class} object at the point where the class is defined; instead,
1109  until a @code{Class} object is actually used.  they wait until a @code{Class} object is actually used.
1110    
1111  @item Array Classes @*  @item Array Classes @*
1112  When you are creating an array class, you should set the @code{ClassLoader} of  When you are creating an array class, you should set the
1113  the array class to the @code{ClassLoader} of its component type.  Whenever you  @code{ClassLoader} of the array class to the @code{ClassLoader} of its
1114  add a class to a @code{ClassLoader}, you need to notify the @code{ClassLoader} and  component type.  Whenever you add a class to a @code{ClassLoader}, you
1115  add the new @code{Class} to its internal cache of classes.  To do this, call  need to notify the @code{ClassLoader} and add the new @code{Class} to
1116  @code{ClassLoader.addVMCreatedClass(Class)}.  @emph{Note: this is written in  its internal cache of classes.  To do this, call
1117  anticipation of 1.2 support and does not apply just yet.}  @code{ClassLoader.addVMCreatedClass(Class)}.  @emph{Note: this is
1118    written in anticipation of 1.2 support and does not apply just yet.}
1119    
1120  @item Primordial Class Loader @*  @item Primordial Class Loader @*
1121  When the primordial class loader loads a class, it needs to tell  When the primordial class loader loads a class, it needs to tell
# Line 422  to the value of the @code{LD_LIBRARY_PAT Line 1288  to the value of the @code{LD_LIBRARY_PAT
1288  @bye  @bye
1289    
1290    
1291    

Legend:
Removed from v.1.18  
changed lines
  Added in v.1.19

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26