OSDN Git Service

4d54e30f44c988a4a19eba62d3a024ca84eef028
[pf3gnuchains/gcc-fork.git] / libjava / classpath / doc / cp-vmintegration.texinfo
1 \input texinfo @c -*-texinfo-*-
2
3 @c %**start of header
4 @setfilename cp-vmintegration.info
5 @settitle GNU Classpath VM Integration Guide
6 @c %**end of header
7
8 @setchapternewpage off
9
10 @ifinfo
11 This file contains important information you will need to know if you
12 are going to write an interface between GNU Classpath and a Virtual
13 Machine.
14
15 Copyright (C) 1998-2002, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
16
17 @ifnotplaintext
18 @dircategory GNU Libraries
19 @direntry
20 * VM Integration: (cp-vmintegration).  GNU Classpath VM Integration Guide
21 @end direntry
22 @end ifnotplaintext
23 @end ifinfo
24
25 @titlepage
26 @title GNU Classpath VM Integration Guide
27 @author John Keiser
28 @author C. Brian Jones
29 @author Mark Wielaard
30
31 @page
32 @vskip 0pt plus 1filll
33 Copyright @copyright{} 1998-2002 Free Software Foundation, Inc.
34 @sp 2
35 Permission is granted to make and distribute verbatim copies of
36 this document provided the copyright notice and this permission notice
37 are preserved on all copies.
38
39 Permission is granted to copy and distribute modified versions of this
40 document under the conditions for verbatim copying, provided that the
41 entire resulting derived work is distributed under the terms of a
42 permission notice identical to this one.
43
44 Permission is granted to copy and distribute translations of this manual
45 into another language, under the above conditions for modified versions,
46 except that this permission notice may be stated in a translation
47 approved by the Free Software Foundation.
48
49 @end titlepage
50
51 @ifinfo
52 @node Top, Introduction, (dir), (dir)
53 @top GNU Classpath Hacker's Guide
54
55 This file contains important information you will need to know if you
56 are going to write an interface between GNU Classpath and a Virtual
57 Machine.
58
59 This document is incomplete, as we are still in alpha with the interface.
60
61 @end ifinfo
62
63 @menu
64 * Introduction::                An introduction to the Classpath project
65 * Initialization::              Initializing the classes
66 * Classpath Hooks::             Hooks from Classpath to the VM
67 * VM Hooks::                    Hooks from the underlying VM to Classpath
68 * JNI Implementation::          Hooking the VM to jni.h
69 * JVMTI Implementation::        Hooking the VM to jvmti.h
70 * Miscellaneous VM Requirements::  
71 @end menu
72
73 @node Introduction, Initialization, Top, Top
74 @comment node-name, next, previous, up
75 @chapter Introduction
76
77 The Classpath Project's ambition to be a 100% clean room implementation
78 of the standard Java class libraries cannot be fulfilled without some
79 level of integration with the Virtual Machine, the underlying machinery
80 that actually runs Java.
81
82 There are several VMs out there, here is a small list.
83
84 @itemize @bullet
85 @item @uref{http://www.hungry.com/old-hungry/products/japhar/,Japhar}
86 Japhar was the first VM to use GNU Classpath.  Today you can see that
87 sort of relationship in the source tree which denotes several Japhar
88 specific files as a reference implementation of those pieces.  This VM
89 has been primarily tested against Linux and lacks garbage collections, a
90 JIT, and suffers recently from slow development.
91
92 @item @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}
93 Intel surprised us not long ago with the release of this rather advanced
94 VM that uses GNU Classpath for a set of class libraries and works on
95 Linux and Windows 2000.  As of June, 2004, it does not appear that ORP
96 is under active development.
97
98 @item @uref{http://www.sablevm.org/,SableVM}
99 SableVM is a robust, extremely portable, efficient, and
100 specifications-compliant Java Virtual Machine that aims to be easy to
101 maintain and to extend. It features a state-of-the-art, efficient
102 interpreter engine. Its source code is very accessible and easy to
103 understand, and has many robustness features that have been the object
104 of careful design.
105
106 @item @uref{http://www.kaffe.org,Kaffe}
107 Kaffe is an advanced VM and together with its own class libraries
108 provides a Java 1.1 compatible environment.
109
110 @item @uref{http://www.mozilla.org/projects/ef,Electrical Fire}
111 The Electrical File VM continues to be listed as a Mozilla project
112 though development has been somewhat quiet.  A number of concepts from
113 EF were expected at one point to be rolled into Japhar, but that
114 development has not occurred as of yet.
115
116 @item @uref{http://latte.snu.ac.kr/,LaTTe}
117 This VM project so far supports only Sun UltraSparc processors using the
118 proprietary Solaris 2.5.1 or higher operating system.  LaTTe was derived
119 from Kaffe but claims a number of improvements.
120
121 @item @uref{http://gcc.gnu.org/java/,GNU Compiler for Java (GCJ)}
122 This is a portable, optimizing, ahead-of-time compiler for the Java
123 Programming Language. It can compile Java source code directly to native
124 machine code, Java source code to Java bytecode (class files), and Java
125 bytecode to native machine code. Compiled applications are linked with the
126 GCJ runtime, libgcj which is based on the GNU Classpath code, which provides
127 the core class libraries, a garbage collector, and a bytecode interpreter.
128 libgcj can dynamically load and interpret class files, resulting in mixed
129 compiled/interpreted applications.
130 GCJ is part of the GNU Compiler Collection (@uref{http://gcc.gnu.org/,GCC}).
131 On March 6 2000 the libgcj and GNU Classpath projects were officially merged
132 and there is active work on merging all the classes between the projects.
133 Licensed under GPL+exception, just as GNU Classpath is.
134
135 @item @uref{http://kissme.sourceforge.net/,Kissme}
136 This is a free Java Virtual Machine that is being developed on GNU/Linux
137 and can run console Java applications.  Kissme also provides support for
138 orthogonally persistent Java.
139 @c I don't know what ``orthogonally persistent Java'' is, and I bet
140 @c there are other people don't know either. -- Steve Augart, 4 June 2004
141
142 @item @uref{http://jamvm.sourceforge.net/,JamVM}
143 A simple, small bytecode interpreter that works out-of-the-box with
144 pure GNU Classpath; it is emerging as the preferred platform for
145 quickly testing a new build of GNU Classpath.  Licensed under the GPL.
146
147 @item @uref{http://jikesrvm.sourceforge.net/,Jikes RVM}
148 A free runtime environment for Java, written in Java.  Works
149 out-of-the-box with pure GNU Classpath.  Features an optimizing JIT.
150 Runs on the x86 and PowerPC architectures, on the AIX, Linux, and Mac
151 OS/X operating systems.  Licensed under the CPL (Common Public
152 License).  Extensively documented.  Actively developed as of June,
153 2004.
154
155 @end itemize
156
157 In the past integration efforts were focused mainly on Japhar with an eye
158 towards getting Electrical Fire to work.  Most information contained in
159 this document is gleaned from these efforts. Recently more work has been
160 done on getting gcj, orp and kissme to work out of the box with GNU Classpath
161 but there is much to do before that becomes a reality.
162
163
164 @node Initialization, Classpath Hooks, Introduction, Top
165 @comment node-name, next, previous, up
166 @chapter Initialization
167
168 The order of initialization, as far as I can tell, doesn't matter just
169 yet.  However, when we move to 1.2 support, it probably will matter, so
170 we'll have a note in here at that time.
171
172 The initialization order is currently documented in the
173 @file{Runtime.java} source file.
174
175 @node Classpath Hooks, VM Hooks, Initialization, Top
176 @comment node-name, next, previous, up
177 @chapter Classpath Hooks
178
179 The primary method of interaction between Classpath and the VM is via
180 the helper classes, which are named after the relevant core library
181 class, but include an additional `VM' prefix.  The library classes from
182 Classpath call out to these to get certain VM-specific dirty work done.
183 A reference copy of each VM class exists.  The majority consist of a
184 series of static methods, some of which are simply declared
185 @code{native}, and some which provide a default implementation.  VMs may
186 either use these as is, or create their own local variations.  When
187 using the default implementations, the VM is responsible for
188 implementing any of the code marked as @code{native} which corresponds
189 to functionality they wish their VM to provide.  When using their own
190 versions of the classes, VM implementors may choose to change the mix of
191 native and non-native methods from that below, so as to best suit their
192 implementation.
193
194 @menu
195 * java.lang::
196 * gnu.classpath::
197 * java.util::
198 * java.io::
199 * java.security::
200 * java.net::
201 * java.nio::
202 * java.nio.channels::
203 * gnu.java.nio::
204 * java.lang.reflect::
205 * gnu.java.lang::
206 * gnu.java.lang.management::
207 * java.lang.management::
208 * Classpath Callbacks::
209 @end menu
210
211 @node java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks
212 @comment  node-name,  next,  previous,  up
213
214 @section @code{java.lang}
215
216 @code{java.lang} is the core Java package, being imported automatically by all
217 classes.  It includes basic classes as @code{Object} and @code{String}.
218 A VM must implement at least some parts of this package in order to
219 become operable.
220
221 @menu
222 * java.lang.VMClass::
223 * java.lang.VMObject::
224 * java.lang.VMClassLoader::
225 * java.lang.VMSystem::
226 * java.lang.VMThrowable::
227 * java.lang.VMCompiler::
228 * java.lang.VMDouble::
229 * java.lang.VMFloat::
230 * java.lang.VMProcess::
231 * java.lang.VMRuntime::
232 * java.lang.VMString::
233 * java.lang.VMThread::
234 * java.lang.VMMath::
235 @end menu
236
237 @node java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang
238 @subsection @code{java.lang.VMClass}
239
240 The core class, @code{java.lang.Class}, and the corresponding VM class,
241 @code{java.lang.VMClass}, provide two main functions within GNU Classpath.
242
243 @enumerate
244 @item For basic VM operation, @code{java.lang.Class} provides the link between
245 the Java-based representation of a class it embodies and the VM's own
246 internal structure for a class.  @xref{VM Hooks}.
247
248 @item As far as the user is concerned, the main function of
249 @code{java.lang.Class} is as an entry point to the reflection
250 facilities, and so it also provides this functionality, backed by the
251 VM class.
252 @end enumerate
253
254 This VM class lists the following methods, organized by the version of the
255 Java specification in which they occur.  All are @code{native}, unless
256 otherwise specified, and pertain to reflection.  As a result, the VM only
257 needs to implement these methods in order to provide reflection support,
258 and then only to the degree required.
259
260 @itemize @bullet
261 @item 1.0
262 @itemize @bullet
263 @item @code{isInterface(Class)} -- This is simply a property test, and matches
264 the presence of an appropriate flag within the class file.
265 @item @code{getName(Class)} -- Returns the fully-qualified name of the class.
266 @item @code{getSuperclass(Class)} -- Returns a @code{Class} instance which
267 represents the superclass.  Again, the class file contains an element directly
268 relating to this.  @code{null} is returned for primitives, interfaces and
269 @code{Object}.
270 @item @code{getInterfaces(Class)} -- Same as the above, but the implemented
271 or extended interfaces rather than the superclass.  An empty array should
272 be returned, rather than @code{null}.
273 @item @code{getDeclaredClasses(Class,boolean)} -- Returns the internal classes
274 this instance declares directly.  The flag determines whether or not the
275 VM should filter out non-public classes.
276 @item @code{getDeclaredFields(Class,boolean)} -- The same for fields.
277 @item @code{getDeclaredMethods(Class,boolean)} -- And for methods.
278 @item @code{getDeclaredConstructors(Class,boolean)} -- And constructors.
279 @item @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance
280 which is responsible for the specified class.
281 @item @code{forName(String, boolean, ClassLoader)} -- The VM should create a
282 @code{Class} instance corresponding to the named class.  As noted in
283 @ref{VM Hooks}, the internal content of the instance is the
284 responsibility of the VM.  The supplied class loader is recorded as that
285 which loaded the class, and the boolean specifies whether or not to
286 run the class initializer.
287 @item @code{isArray(Class)} -- Another property test, corresponding to a
288 class file flag.
289 @item @code{initialize(Class)} -- The VM should initialize the class fully,
290 if it has not already done so.
291 @item @code{loadArrayClass(String,ClassLoader)} -- This is called if
292 @code{forName} returns @code{null} and the string specifies an array class.
293 The specified array class should be loaded with the supplied class loader.
294 @item @code{throwException(Throwable)} -- The VM should throw the supplied
295 checked exception, without declaring it.
296 @end itemize
297 @item 1.1
298 @itemize @bullet
299 @item @code{isInstance(Class,Object)} -- This is a reflection-based equivalent
300 of the @code{instanceof} operator.
301 @item @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand for the above,
302 removing the need to create an instance to test assignability.  
303 @item @code{isPrimitive(Class)} -- Returns true if this class is simply
304 a representation of one of the primitive types: @code{boolean}, @code{byte},
305 @code{char}, @code{short}, @code{int}, @code{long}, @code{float},
306 @code{double} and @code{void}.
307 @item @code{getComponentType(Class)} -- Produces a @code{Class} instance which
308 represents the type of the members of the array the class instance represents.
309 Classes which don't represent an array type return @code{null}.
310 @item @code{getModifiers(Class,boolean)} -- Returns an integer which encodes
311 the class' modifiers, such as @code{public}.  Again, this relates to
312 information stored in the class file.
313 @item @code{getDeclaringClass(Class)} -- Returns the class that declared
314 an inner or member class, or @code{null} if the instance refers to a top-level
315 class.
316 @end itemize
317 @item 1.5
318 @itemize @bullet
319 @item @code{isSynthetic(Class)} -- Returns true if the flags for this class
320 mark it as synthetic.
321 @item @code{isAnnotation(Class)} -- Returns true if the flags for this class
322 mark it as an annotation.
323 @item @code{isEnum(Class)} -- Returns true if the flags for this class
324 mark it as an enumeration.
325 @item @code{getSimpleName(Class)} -- Returns the simple name of the class.
326 A default implementation is provided, but a more efficient version may instead
327 be provided by the VM.
328 @item @code{getCanonicalName(Class)} -- Returns the canonical name of the
329 class.  A default implementation is provided, but a more efficient
330 version may instead be provided by the VM.
331 @item @code{getEnclosingClass(Class)} -- Returns the immediately enclosing
332 class (null for a top-level class).
333 @item @code{getEnclosingConstructor(Class)} -- Returns the constructor
334 which immediately encloses the supplied class.
335 @item @code{getEnclosingMethod(Class)} -- Returns the method
336 which immediately encloses the supplied class.
337 @item @code{getClassSignature(Class)} -- Returns the generic signature of
338 the class or null if there isn't one.
339 @item @code{isAnonymousClass(Class)} -- Returns true if the class is an
340 anonymous class.
341 @item @code{isLocalClass(Class)} -- Returns true if the class is an
342 local class.
343 @item @code{isMemberClass(Class)} -- Returns true if the class is an
344 member class.
345 @end itemize
346 @end itemize
347
348 @node java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang
349 @subsection @code{java.lang.VMObject}
350
351 @code{VMObject} is the bridge between the low level @code{Object}
352 facilities such as making a clone, getting the class of the object and
353 the wait/notify semantics.  This is accomplished using the following
354 @code{native} methods.
355
356 @itemize @bullet
357 @item @code{getClass(Object)} -- Returns the @code{Class} instance for the
358 object.  @code{Class} objects are produced by the VM, as described in
359 @ref{VM Hooks}.
360 @item @code{clone(Cloneable)} -- The VM should produce a low-level clone of the
361 specified object, creating a field-by-field shallow copy of the original.
362 The only difference between the two is that the new object should still be
363 @code{finalizable}, even if the original is not.
364 @item @code{notify(Object)} -- The VM should choose one of the threads waiting
365 for a lock on the specified object arbitrarily, and wake it.  If the current
366 thread does not currently hold the lock on the object, then an
367 @code{IllegalMonitorStateException} should be thrown.
368 @item @code{notifyAll(Object)} -- Same as the above, but all threads are
369 awakened.
370 @item @code{wait(Object,long,int)} -- The VM should set the current thread
371 into a waiting state, which persists until it receives a notify signal or the
372 specified time (in milliseconds and nanoseconds) is exceeded.  The nanoseconds
373 restriction may be ignored if such granularity is not available, and a
374 @code{IllegalMonitorStateException} should be thrown if the current thread
375 doesn't own the object.
376 @end itemize
377
378 @node java.lang.VMClassLoader, java.lang.VMSystem, java.lang.VMObject, java.lang
379 @subsection @code{java.lang.VMClassLoader}
380 @code{VMClassLoader} provides methods for defining and resolving core and
381 primitive classes, as well as handling resources, packages and assertions.
382 The class is a mixture of @code{native} methods and Java-based
383 implementations, with some of the latter being @emph{stubs}.
384
385 @itemize @bullet
386 @item Native Methods
387 @itemize @bullet
388 @item @code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}
389 -- The VM should create a @code{Class} instance from the supplied byte array.
390 @item @code{resolveClass(Class)} -- Resolve references to other classes in the
391 supplied class.
392 @item @code{loadClass(name,boolean)} -- Load a class using the bootstrap
393 loader.
394 @item @code{getPrimitiveClass(char)} -- The VM should provide a @code{Class}
395 implementation for one of the primitive classes.  The supplied character
396 matches the JNI code for the primitive class e.g. `B' for byte and
397 `Z' for boolean.
398 @end itemize
399 @item Java Methods
400 @itemize @bullet
401 @item @code{getResource(String)} -- The default implementation calls
402 @code{getResources} and returns the first element in the returned enumeration,
403 or @code{null} if there are no elements.
404 @item @code{getResources(String)} -- By default, this compiles a list of
405 URLs via the boot class path.  Any matching files within a zip file are added,
406 and directories on the boot class path are automatically converted to file
407 URLs that refer to join the directory with the resource name (whether or not
408 it actually exists).
409 @item @code{getPackage(String)} -- Always returns null, which may be suitable
410 if the VM does not wish to return a @code{Package} implementation. Otherwise,
411 it may be necessary to make this a @code{native} method.
412 @item @code{getPackages()} -- As with the last, a default stub implementation
413 exists (returning an empty array) which may be replaced if support is
414 required. 
415 @item @code{defaultAssertionStatus()} -- A stub which can be implemented
416 by VMs providing assertion support.  At present, it always returns @code{true}.
417 @item @code{packageAssertionStatus()} -- Much the same status as the above.
418 The method should return a map converting package names to boolean status
419 values.  The stub implementation provides an empty map.
420 @item @code{classAssertionStatus()} -- Same as the last, but for classes.
421 @item @code{getSystemClassLoader()} -- The default calls @code{ClassLoader}
422 to create a new auxillary class loader with a system and extension class
423 loader.  The VM may wish to replace it if it wishes to supply its own custom
424 system class loader.
425 @end itemize
426 @end itemize
427 @node java.lang.VMSystem, java.lang.VMThrowable, java.lang.VMClassLoader, java.lang
428 @subsection @code{java.lang.VMSystem}
429 @code{VMSystem} handles the default I/O streams, provides access to the
430 system clock and environment variables and provides methods for
431 @code{System.arraycopy} and the @code{identityHashCode} of an
432 @code{Object}.  It consists of @code{native} methods, but the default
433 implementation also provides some helper methods to simplify stream
434 creation.  
435
436 @itemize @bullet
437 @item Native Methods
438 @itemize @bullet
439 @item @code{arraycopy(Object,int,Object,int,int)} -- The VM should copy
440 a specified number of array objects from one array to another, with 
441 appropriate checks for compatible typing, available elements and space.
442 The VM should be able to perform this more efficiently using native code
443 and direct memory manipulation than would have been achieved by using Java.
444 @item @code{identityHashCode(Object)} -- This is the hashcode for
445 @code{Object}, which relates to the actual location of the object in memory.
446 @item @code{setIn(InputStream)} -- Set the system input stream.
447 @item @code{setOut(PrintStream)} -- Set the system output stream.
448 @item @code{setErr(PrintStream)} -- Set the system error stream.
449 @item @code{currentTimeMillis()} -- Gets the system time in milliseconds.
450 @item @code{getenv(String)} -- Returns the value of the specified environment
451 variable.
452 @item @code{getenv()} -- Returns a list of `name=value' pairs which correspond
453 to the environment variables.
454 @end itemize
455 @item Java Methods
456 @itemize @bullet
457 @item @code{makeStandardInputStream()} -- Helps provide the functionality of
458 @code{System.in} by wrapping the appropriate file descriptor in a
459 buffered file input stream.  VMs may choose to create the stream from
460 the descriptor differently rather than using this method.
461 @item @code{makeStandardOutputStream()} -- Helps provide the functionality of
462 @code{System.out} by wrapping the appropriate file descriptor in a buffered
463 file output stream.  VMs may choose to create the stream from the descriptor
464 differently rather than using this method.
465 @item @code{makeStandardErrorStream()} -- Helps provide the functionality of
466 @code{System.err} by wrapping the appropriate file descriptor in a buffered
467 file output stream.  VMs may choose to create the stream from the descriptor
468 differently rather than using this method.
469 @end itemize
470 @end itemize
471
472 Classpath also provides native implementations of
473
474 @itemize @bullet
475 @item @code{setIn(InputStream)} 
476 @item @code{setOut(PrintStream)} 
477 @item @code{setErr(PrintStream)} 
478 @item @code{currentTimeMillis()} 
479 @item @code{getenv(String)}
480 @end itemize
481
482 making a VM implementation optional.
483
484 @node java.lang.VMThrowable, java.lang.VMCompiler, java.lang.VMSystem, java.lang
485 @subsection @code{java.lang.VMThrowable}
486 @code{VMThrowable} is used to hold the VM state of a throwable, created either
487 when a @code{Throwable} is created or the @code{fillInStackTrace()} method is
488 called (i.e. when the actual stack trace is needed, as a lot of exceptions are
489 never actually used).  The actual class has two @code{native} methods,
490 one (@code{fillInStackTrace()}) being a method of the class used to obtain
491 instances, and the other an instance method, @code{getStackTrace()}.
492 @itemize @bullet
493 @item @code{fillInStackTrace(Throwable)} -- The VM should return the current
494 execution state of the @code{Throwable} in the form of a @code{VMThrowable}
495 instance.  The VM may also return @code{null} if it does not support this
496 functionality.
497 @item @code{getStackTrace()} -- This is used to create a real
498 @code{StackTraceElement} array for the exception, using the state data
499 stored during creation of the instance.
500 @end itemize
501
502 @node java.lang.VMCompiler, java.lang.VMDouble, java.lang.VMThrowable, java.lang
503 @subsection @code{java.lang.VMCompiler}
504
505 @code{VMCompiler} provides an interface for VMs which wish to provide
506 JIT compilation support.  The default implementation is simply a series
507 of stubs. The property, @code{java.compiler}, should point to a library
508 containing the function @code{java_lang_Compiler_start()} if such support
509 is to be provided.
510
511 @itemize @bullet
512 @item @code{compileClass(Class)} -- Invoke the compiler to compile the specific
513 class, returning @code{true} if successful.
514 @item @code{compileClasses(String)} -- The compiler should compile the classes
515 matching the specified string, again returning @code{true} on success.
516 @item @code{command(Object)} -- The object represents a command given to the
517 compiler, and is specific to the compiler implementation.
518 @item @code{enable} -- Enable the operation of the compiler.
519 @item @code{disable} -- Disable compiler operation.
520 @end itemize
521
522 @node java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler, java.lang
523 @subsection @code{java.lang.VMDouble}
524
525 @code{VMDouble} provides native support for the conversion and parsing
526 of doubles.
527
528 @itemize @bullet
529 @item @code{doubleToLongBits(double)} -- Converts the double to the IEEE 754
530 bit layout, collapsing NaNs to @code{0x7ff8000000000000L}.
531 @item @code{doubleToRawLongBits(double)} -- Same as the above, but preserves
532 NaNs.
533 @item @code{longBitsToDouble(long)} -- This is the inverse of the last method,
534 preserving NaNs so that the output of one can be fed into the other without
535 data loss.
536 @item @code{toString(double,boolean)} -- Converts the double to a string,
537 giving a shorter value if the flag @code{isFloat} is @code{true}, indicating
538 that the conversion was requested by @code{java.lang.Float} rather than
539 @code{java.lang.Double}.
540 @item @code{initIDs} -- Used by JNI-based solutions to initialize the cache
541 of the static field IDs.  The default @code{VMDouble} implementation has a
542 static initializer which loads the JNI library and calls this method.
543 @item @code{parseDouble} -- Turn the string into a usable double value.
544 @end itemize
545
546 Classpath provides native implementations of all these, making VM
547 implementation optional.
548
549 @node java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble, java.lang
550 @subsection @code{java.lang.VMFloat}
551
552 @code{VMFloat} provides native support for the conversion of floats.
553
554 @itemize @bullet
555 @item @code{floatToIntBits(float)} -- Converts the float to the IEEE 754
556 bit layout, collapsing NaNs to @code{0x7fc00000}.
557 @item @code{floatToRawIntBits(float)} -- Same as the above, but preserves
558 NaNs.
559 @item @code{intBitsToFloat(int)} -- This is the inverse of the last method,
560 preserving NaNs so that the output of one can be fed into the other without
561 data loss.
562 @end itemize
563
564 Classpath provides native implementations of all these, making VM
565 implementation optional.
566
567 @node java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat, java.lang
568 @subsection @code{java.lang.VMProcess}
569
570 @code{VMProcess} handles the execution of external processes.  In the
571 default implementation, threads are spawned and reaped by @code{ProcessThread}.
572 A constructor creates a new @code{VMProcess}, which extends rather than
573 complements @code{Process}, using an array of arguments, an array of
574 environment variables and a working directory.  The instance maintains
575 system input, output and error streams linked to the external process.
576 Three @code{native} methods are used, and implementations are provided
577 for all three by Classpath, making VM implementation optional.  These use
578 the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.
579
580 @itemize @bullet
581 @item @code{nativeSpawn(String[],String[],File,boolean)} -- The VM should
582 create a new process which uses the specified command-line arguments,
583 environment variables and working directory.  Unlike the other two
584 methods, this method is linked to an instance, and must call
585 @code{setProcessInfo()} with the results before returning.  The
586 boolean argument maps to the @code{redirectErrorStream} property of
587 @code{java.lang.ProcessBuilder}.  When true, the output and error streams
588 are merged.
589 @item @code{nativeReap()} -- This is called to perform a reap of any
590 zombie processes, and should not block, instead returning a boolean as to
591 whether reaping actually took place.
592 @item @code{nativeKill(long)} -- The VM should terminate the specified PID.
593 @end itemize
594
595 @node java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess, java.lang
596 @subsection @code{java.lang.VMRuntime}
597
598 The @code{VMRuntime} class provides a series of native methods
599 which divulge information about the runtime or invoke certain
600 operations.  This includes retrieving the amount of available memory,
601 and scheduling the garbage collector.  There are two exceptions: the
602 @code{enableShutdownHooks} method, which allows the VM to put in its own
603 shutdown hooks when @code{Runtime.addShutdownHook()} is first invoked,
604 and @code{exec(String[],String[],File)} which spawns an external process.
605 These are Java-based static methods instead.  The first is simply a stub by
606 default, while the second simply links to the functionality of
607 @code{VMProcess} (and should be changed if a different @code{Process}
608 implementation is used).
609
610 @itemize @bullet
611 @item @code{availableProcessors()} -- Returns the number of processors 
612 available to the VM.
613 @item @code{freeMemory()} -- Returns the amount of memory the VM has available
614 on the heap for allocating.
615 @item @code{totalMemory()} -- Returns the size of the heap.
616 @item @code{maxMemory()} -- Returns the maximum memory block the VM will
617 attempt to allocate.  May be simply @code{Long.MAX_VALUE} (8 exabytes!)
618 @item @code{gc()} -- Allows users to explicitly invoke the garbage collector.
619 This is a suggestion to the VM, rather than a command, and the garbage
620 collector should run anyway @emph{without} it being invoked.
621 @item @code{runFinalization()} -- Like the above, but related to the
622 finalilzation of objects rather than the garbage collector.
623 @item @code{runFinalizationForExit()} -- Called immediately prior to VM
624 shutdown in order to finalize all objects (including `live' ones)
625 @item @code{traceInstructions(boolean)} -- This turns on and off the optional
626 VM functionality of printing a trace of executed bytecode instructions.
627 @item @code{traceMethodCalls(boolean)} -- This turns on and off the optional
628 VM functionality of printing a trace of methods called.
629 @item @code{runFinalizersOnExit(boolean)} -- A toggleable setting for
630 running the finalization process at exit.
631 @item @code{exit(int)} -- The VM should shutdown with the specified exit code.
632 @item @code{nativeLoad(String,ClassLoader)} -- Attempts to load a file,
633 returning an integer which is non-zero for success.  Nothing happens if the
634 file has already been loaded.
635 @item @code{mapLibraryName(String)} -- The VM should map the system-independent
636 library name supplied to the platform-dependent equivalent (e.g. a @code{.so}
637 or @code{.dll} file)
638 @end itemize
639
640 @node java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime, java.lang
641 @subsection @code{java.lang.VMString}
642 @code{VMString} is responsible for handling interned strings.  If two strings
643 are equal (using the @code{equals()} method), then the results of calling
644 the @code{intern()} method on each of them makes them equal
645 (using @code{==}).  Thus, the same string object is always returned by
646 @code{intern} if the two strings are equal.  The default implementation
647 is Java-based and implements @code{intern(String)} by maintaining a
648 @code{WeakHashMap} which links the strings to their @code{WeakReference}.
649 A new mapping is created for each new string being @code{intern}ed.  
650 A VM may implement this differently by implementing this method,
651 which is @code{static} and the only one in @code{VMString}.
652
653 @node java.lang.VMThread, java.lang.VMMath, java.lang.VMString, java.lang
654 @subsection @code{java.lang.VMThread}
655
656 @code{VMThread} provides the link between Java's threads and the platform
657 threading support.  A @code{VMThread} is created via a private constructor
658 and linked to a @code{Thread} instance.  This occurs when the @code{Thread}
659 instance is started by the static @code{create(Thread,long)} method (the second
660 argument requests a certain stack size, usually zero).  The thread itself is
661 executed via the @code{run()} method, which handles any problems with the
662 running of the thread and its eventual death.
663
664 @code{VMThread} provides the following accessors and mutators for accessing
665 the thread state via @code{VMThread},
666
667 @itemize @bullet
668 @item @code{getName()}
669 @item @code{setName(String)}
670 @item @code{getPriority()}
671 @item @code{setPriotity(int)}
672 @item @code{isDaemon()}
673 @end itemize
674
675 all of which refer to the @code{Thread} instance. @code{setPriority(int)} also
676 calls the appropriate native method.  @code{stop(Throwable)} similarly wraps
677 a native method, merely adding in a check for the state of the thread.
678
679 The default implementation also provides Java-based implementations of
680 @code{join(long,int)}, @code{sleep(long,int)} and
681 @code{holdsLock(Object)}.  @code{join} and @code{sleep} simply wait for
682 the appropriate amount of time, with @code{join} additionally waiting
683 for the thread instance to become @code{null}.  @code{holdsLock} simply
684 checks if an object is locked by the current thread by trying to invoke
685 the @code{notify} method, and catching the failing exception if this is
686 not the case.
687
688 The remainder of the class is a series of @code{native} methods, some of
689 which are mandatory for VM implementation and others which provide optional
690 or deprecated functionality.
691
692 @itemize @bullet
693 @item Mandatory Instance Methods
694 @itemize @bullet
695 @item @code{start(long)} -- The VM should create the native thread and start
696 it running using the @code{run} method of the @code{VMThread} instance on
697 which this method is called.
698 @item @code{interrupt()} -- The VM should interrupt the running thread and
699 throw an appropriate exception.
700 @item @code{isInterrupted()} -- Checks the interrupted state of the thread.
701 @item @code{suspend()} -- The thread should be suspended until resumed.
702 @item @code{resume()} -- The thread should be resumed from its suspended state.
703 This pair of methods are deprecated, due to the possibility of a deadlock
704 occuring when a thread with locks is suspended.
705 @item @code{nativeSetPriority(int)} -- Called by @code{setPriority}
706 to allow the setting to flow down to the native thread.
707 @item @code{nativeStop(Throwable)} -- The VM should stop the thread abnormally
708 and throw the specified exception.  This is clearly deprecated, due to the
709 ambiguous state an abruptly-stopped thread may leave.
710 @item @code{getState()} -- Returns the VM's impression of the current state
711 of the thread.  The applicable states are supplied by the @code{State}
712 enumeration in @code{java.lang.Thread}.
713 @end itemize
714 @item Mandatory Class Methods
715 @itemize @bullet
716 @item @code{currentThread()} -- Return a reference to the thread currently
717 being executed.
718 @item @code{yield()} -- The VM should allow some other thread to run.
719 The current thread maintains its locks even though it stops executing for
720 the time being.
721 @item @code{interrupted()} -- A shortcut to obtaining the interrupted state
722 of the current thread.
723 @end itemize
724 @item Other Methods
725 @itemize @bullet
726 @item @code{countStackFrames()} -- Returns a count of the number of stack
727 frames in the thread.  This depends on the deprecated method @code{suspend()}
728 having returned true, and is thus deprecated as a result.
729 @end itemize
730 @end itemize
731
732 @node java.lang.VMMath,, java.lang.VMThread, java.lang
733 @subsection @code{java.lang.VMMath}
734
735 The @code{VMMath} class provides a series of native methods
736 for some of the mathematical functions present in @code{java.lang.Math}.
737 Classpath provides a default implementation of these which maps the
738 functions to those provided by @code{fdlibm}.  VM implementors are welcome
739 to replace this with more efficent implementations, as long as the accuracy
740 contract of these methods, specified in @code{java.lang.Math}, is maintained.
741
742 @itemize @bullet
743 @item 1.0
744 @itemize @bullet
745 @item @code{sin(double)} -- Returns the sine value for the given angle.
746 @item @code{cos(double)} -- Returns the cosine value for the given angle.
747 @item @code{tan(double)} -- Returns the tangent value for the given angle.
748 @item @code{asin(double)} -- Returns the arc sine value for the given angle.
749 @item @code{acos(double)} -- Returns the arc cosine value for the given angle.
750 @item @code{atan(double)} -- Returns the arc tangent value for the given angle.
751 @item @code{atan2(double,double)} -- Returns the arc tangent of the ratio of
752 the two arguments.
753 @item @code{exp(double)} -- Returns the exponent raised to the given power.
754 @item @code{log(double)} -- Returns the natural logarithm for the given value.
755 @item @code{sqrt(double)} -- Returns the square root of the value.
756 @item @code{pow(double,double)} -- Returns x to the power of y.
757 @item @code{IEEEremainder(double,double)} -- Returns the IEEE 754 remainder
758 for the two values.
759 @item @code{ceil(double)} -- Returns the nearest integer >= the value.
760 @item @code{floor(double)} -- Returns the nearest integer <= the value.
761 @item @code{rint(double)} -- Returns the nearest integer or the even one
762 if the distance between the two is equal.
763 @end itemize
764 @item 1.5
765 @itemize @bullet
766 @item @code{cbrt(double)} -- Returns the cube root of the value.
767 @item @code{cosh(double)} -- Returns the hyperbolic cosine value for the given
768 angle.
769 @item @code{expm1(double)} -- Returns the exponent of the value minus one.
770 @item @code{hypot(double,double)} -- Returns the hypotenuse corresponding to
771 x and y.
772 @item @code{log10(double)} -- Returns the base 10 logarithm of the given value.
773 @item @code{log1p(double)} -- Returns the natural logarithm of the value plus
774 one.
775 @item @code{sinh(double)} -- Returns the hyperbolic sine value for the given
776 angle.
777 @item @code{tanh(double)} -- Returns the hyperbolic tangent value for the given angle.
778 @end itemize
779 @end itemize
780
781 @node gnu.classpath, java.util, java.lang, Classpath Hooks
782 @section @code{gnu.classpath}
783
784 The @code{gnu.classpath} package provides Classpath-specific functionality,
785 primarily relating to the features in @code{java.lang}.  At present, this
786 includes the context of a class (the stack) and the system properties.
787
788 @menu
789 * gnu.classpath.VMStackWalker::
790 * gnu.classpath.VMSystemProperties::
791 * gnu.classpath.Unsafe::
792 @end menu
793
794 @node gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
795 @subsection @code{gnu.classpath.VMStackWalker}
796
797 @code{VMStackWalker} provides access to the class context or stack.  The
798 default implementation consists of a @code{native} @code{static} method,
799 @code{getClassContext()}, which obtains the class context, and two helper
800 methods which obtain the calling class (the 3rd element in the context array)
801 and its class loader, respectively.
802
803 @itemize @bullet
804 @item @code{getClassContext()} -- The VM should return an array of
805 @code{Class} objects, each of which relates to the method currently being
806 executed at that point on the stack.  Thus, the first item (index 0) is the
807 class that contains this method.
808 @item @code{getCallingClass()} -- A Java-based helper method which returns
809 the @code{Class} object which contains the method that called the method
810 accessing @code{getCallingClass()}. 
811 @item @code{getCallingClassLoader()} -- Like the last, but returning the class
812 loader of the class.
813 @end itemize
814
815 @node gnu.classpath.VMSystemProperties,gnu.classpath.Unsafe,gnu.classpath.VMStackWalker,gnu.classpath
816 @subsection @code{gnu.classpath.VMSystemProperties}
817
818 @code{VMSystemProperties} allows the VM to hook into the property creation
819 process, both before and after the system properties are added by GNU
820 Classpath.  The default implementation assumes that the VM will add its
821 properties first, by making the pre-initialisation method @code{native},
822 and that the Classpath properties may then be altered by a Java-based
823 post-initialisation method.
824
825 As these methods are called as part of the bootstrap process, caution should
826 be used as to what classes are used, and properties should only be set
827 using @code{Properties.setProperty()}.  Specifically, I/O classes should be
828 avoided at this early stage.
829
830 @itemize @bullet
831 @item @code{preInit(Properties)} -- Allows the VM to add properties
832 @emph{before} the Classpath properties are added. The default implementation
833 includes a full list of properties that @emph{must} be added by the VM, but
834 additional VM-specific ones may also be added.  
835 @item @code{postInit(Properties)} -- Same as the last, but called after the
836 Classpath properties have been added.  The main purpose of this is to allow
837 the VM to alter the properties added by GNU Classpath to suit it.
838 @end itemize
839
840 @node gnu.classpath.Unsafe,,gnu.classpath.VMSystemProperties,gnu.classpath
841 @subsection @code{gnu.classpath.Unsafe}
842
843 The @code{Unsafe} class provides access to some low-level unsafe operations
844 as required by the addition of the java.util.concurrent classes.  These
845 focus on direct memory access to the fields within the VM and providing
846 atomic update methods.
847
848 @itemize @bullet
849 @item @code{objectFieldOffset(Field)} -- Provides the caller with the memory
850 offset of a particular field.
851 @item @code{compareAndSwap*(Object,long,*,*)} -- One of these methods is
852 provided for each of int, long and Object (hence the *s).  The value of
853 a field pointed to by the given Object and offset is compared with the
854 first value and replaced with the second if they are the same.  The reason
855 for this method is to make this change operation atomic.
856 @item @code{put/get*(Object,long,*)} -- These are like the last set of
857 methods, handling integers, longs and Objects, but the field is always
858 changed on a put.  Different methods are provided for different semantics.
859 Ordered variants perform a lazy put, in that the change does not
860 immediately propogate to other threads, while the others provide
861 volatile or 'normal' semantics.
862 @item @code{arrayBaseOffset(Class)} and @code{arrayIndexScale(Class)} --
863 These two methods allow an array class to be traversed by pointer
864 arithmetic, by gaining the address of the first element and then
865 scaling appropriately for the later ones.
866 @item @code{park(boolean,long)} and @code{unpark(Thread)} -- These methods
867 block and unblock threads respectively, with an optional timeout being
868 provided for the blocking.  @code{unpark} is unsafe as the thread may have
869 been destroyed by native code. 
870 @end itemize
871
872 @node java.util, java.io, gnu.classpath, Classpath Hooks
873 @section java.util
874
875 The @code{java.util} VM hooks provide links between the mix of functionality
876 present in that package, which includes collections, date and time handling
877 and parsing.  At present, there is only one hook, which connects GNU Classpath
878 to the timezone information provided by the underlying platform.
879
880 @menu
881 * java.util.VMTimeZone::
882 @end menu
883
884 @node java.util.VMTimeZone,,java.util,java.util
885 @subsection @code{java.util.VMTimeZone}
886
887 @code{VMTimeZone} joins @code{TimeZone} to the platform timezone information
888 via the static method, @code{getDefaultTimeZoneId()}.  The VM hook is
889 expected to return a @code{TimeZone} instance that represents the current
890 timezone in use by the platform.  The default implementation provides
891 this functionality for POSIX or GNU-like systems, and VMs that want this
892 functionality can keep this implementation and implement the native
893 method, @code{getSystemTimeZoneId()}.  This method is only called when
894 obtaining the timezone name from the @code{TZ} environment variable,
895 @code{/etc/timezone} and @code{/etc/localtime} all fail.  This fallback
896 mechanism also means that a system which doesn't provide the above three
897 methods, but does provide a timezone in string form, can still use this
898 implementation.
899
900 @node java.io, java.security, java.util, Classpath Hooks
901 @section java.io
902
903 The @code{java.io} package is heavily reliant on access to the I/O facilities
904 of the underlying platform.  As far as its VM hooks go, they provide two
905 areas of functionality to GNU Classpath, these being
906
907 @itemize @bullet
908 @item File and directory queries and manipulation
909 @item Serialization of objects
910 @end itemize
911
912 The first corresponds directly to most of the @code{File} class, while
913 the latter underlies the functionality provided by the
914 @code{ObjectInputStream} and @code{ObjectOutputStream}.  More low-level I/O
915 is provided by @ref{java.nio}.
916
917 @menu
918 * java.io.VMFile::
919 * java.io.VMObjectInputStream::
920 * java.io.VMObjectStreamClass::
921 @end menu
922
923 @node java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
924 @subsection @code{java.io.VMFile}
925
926 @code{VMFile} allows GNU Classpath's @code{File} representations to
927 probe and modify the file system using the native functions of the
928 platform.  The default implementation (which consists of both a
929 @code{VMFile} class and the native methods) is primarily UNIX-centric,
930 working with POSIX functions and assuming case-sensitive filenames,
931 without the restriction of the 8.3 format.  It consists mainly of
932 @code{static} @code{native} methods, with a few Java helper methods.
933 The native methods represent the file as a string containing its path,
934 rather than using the object itself.
935
936 @itemize @bullet
937 @item Native Methods
938 @itemize @bullet
939 @item @code{lastModified(String)} -- The native method should return a
940 @code{long} value that represents the last modified date of the file.
941 @item @code{setReadOnly(String)} -- Sets the file's permissions to read only,
942 in whichever way this is realised by the platform.
943 @item @code{create(String)} -- Create the named file.
944 @item @code{list(String)} -- The native method opens the named directory,
945 reads the contents and returns them as a Java @code{String} array.
946 @item @code{renameTo(String,String)} -- Renames the first file to the second.
947 @item @code{length(String)} -- Returns a @code{long} value representing
948 the file size.
949 @item @code{exists(String)} -- Tests for the existence of the named file
950 or directory.
951 @item @code{delete(String)} -- Deletes the file or directory.
952 @item @code{setLastModified(String,long)} -- Change the last modified time.
953 @item @code{mkdir(String)} -- Creates the named directory.
954 @item @code{isFile(String)} -- Tests that the named path references a file.
955 @item @code{canWrite(String)} -- Tests that the file can be written to.
956 This method is @code{synchronized}, so the object is locked during the check.
957 @item @code{canRead(String)} -- Complement of the last method.
958 @item @code{isDirectory(String)} -- Tests that the named path references
959 a directory.
960 @end itemize
961 @item Java Helper Methods
962 @itemize @bullet
963 @item @code{canWriteDirectory(File)} -- Checks that the directory can be
964 written to, by trying to create a temporary file in it.
965 @item @code{listRoots()} -- Returns the root of a GNU filesystem i.e. `/'
966 in an array.
967 @item @code{isHidden(String)} -- Checks whether the file starts with `.',
968 which is how files are hidden on UNIX-style systems.
969 @item @code{getName(String)} -- Pulls the actual filename from the end of
970 the path, by breaking off the characters after the last occurrence of the
971 platform's file separator.
972 @item @code{getCanonicalForm(String)} -- This converts a UNIX path to
973 its canonical form by removing the `.' and `..' sections that occur within.
974 @end itemize
975 @end itemize
976
977 @node java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
978 @subsection @code{java.io.VMObjectInputStream}
979
980 This class consists of two methods which provide functionality used in
981 deserializing an object.  @code{currentClassLoader()} provides the first
982 user-defined class loader from the class context
983 (@xref{gnu.classpath.VMStackWalker},) via a @code{PrivilegedAction}.
984 @code{allocateObject(Class,Class,Constructor)} is a @code{native} method
985 (a reference implementation is provided) which creates an object but
986 calls the constructor of another class, which is a superclass of the
987 object's class.
988
989 @node java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
990 @subsection @code{java.io.VMObjectStreamClass}
991
992 @code{VMObjectStreamClass} is a series of @code{static} @code{native}
993 methods that provide some of the groundwork for @code{ObjectStreamClass}
994 and @code{ObjectStreamField}.  @code{hasClassInitializer(Class)} works
995 with the former, and checks for the presence of a static initializer.
996 The remaining methods are of the form @code{setXXXNative(Field,Object,XXX)}
997 and support @code{ObjectStreamField}.  One exists for each of the main types
998 (boolean, float, double, long, int, short, char, byte and object) and is used
999 to set the specified field in the supplied instance to the given value.
1000
1001 A default implementation is provided for all of them, so a VM implementation
1002 is optional.
1003
1004 @node java.security, java.net, java.io, Classpath Hooks
1005 @section java.security
1006
1007 The @code{java.security} package provides support for Java's security
1008 architecture.  
1009
1010 @menu
1011 * java.security.VMAccessController::
1012 * java.security.VMSecureRandom::
1013 @end menu
1014
1015 @node java.security.VMAccessController,java.security.VMSecureRandom,java.security,java.security
1016 @subsection @code{java.security.VMAccessController}
1017
1018 The @code{AccessController} is used to perform privileged actions.  Its
1019 hook class, @code{VMAccessController}, maintains the
1020 @code{AccessControlContext} and the default implementation is purely
1021 Java-based.  The VM may choose to replace this with their own.
1022 The methods in the reference version are as follows:
1023
1024 @itemize @bullet
1025 @item @code{pushContext(AccessControlContext)} -- Adds a new context to the
1026 stack for the current thread.  This is called before a privileged action
1027 takes place.
1028 @item @code{popContext()} -- Removes the top context from the stack.  This
1029 is performed after the privileged action takes place.
1030 @item @code{getContext()} -- Either derives a context based on the 
1031 @code{ProtectionDomain}s of the call stack (see the next method) or returns
1032 the top of the context stack.
1033 @item @code{getStack()} -- Provides access to the call stack as a pair of
1034 arrays of classes and method names.  The actual implementation returns
1035 an empty array, indicating that there are no permissions.
1036 @end itemize
1037
1038 @node java.security.VMSecureRandom,,java.security.VMAccessController,java.security
1039 @subsection @code{java.security.VMSecureRandom}
1040
1041 The @code{VMSecureRandom} class is used to provide access to
1042 cryptographically secure random numbers.  The default implementation
1043 of the class runs eight threads that increment counters in a tight
1044 loop, and XORs each counter to produce one byte of seed data. This is
1045 not very efficient, and is not guaranteed to be random (the thread
1046 scheduler is probably deterministic, after all). VM implementors
1047 should provide a version of this class, which implements the method
1048 @code{generateSeed(byte[],int,int)}, so that it fills the buffer using
1049 a random seed from a system facility, such as a system entropy
1050 gathering device or hardware random number generator.  The parameters
1051 are the usual set of buffer, offset and length and the method returns
1052 the number of bytes actually generated, which may be less than that
1053 requested.
1054
1055 @node java.net, java.nio, java.security, Classpath Hooks
1056 @section java.net
1057
1058 The @code{java.net} package is heavily reliant on access to the networking
1059 facilities of the underlying platform.  The VM hooks provide information
1060 about the available network interfaces, and access to lookup facilities
1061 for network addresses.
1062
1063 @menu
1064 * java.net.VMInetAddress::
1065 * java.net.VMNetworkInterface::
1066 @end menu
1067
1068 @node java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
1069 @subsection @code{java.net.VMInetAddress}
1070
1071 @code{VMInetAddress} is a series of @code{static} @code{native} methods
1072 which provide access to the platform's lookup facilities.  All the methods
1073 are implemented by GNU Classpath, making VM implementation optional, and
1074 are as follows:
1075
1076 @itemize @bullet
1077 @item @code{getLocalHostname()} -- Wraps the @code{gethostname} function, and
1078 falls back on `localhost'.
1079 @item @code{lookupInaddrAny()} -- Returns the value of @code{INADDR_ANY}.
1080 @item @code{getHostByAddr(byte[])} -- Looks up the hostname based on an IP
1081 address.
1082 @item @code{getHostByName(String)} -- The reverse of the last method, it
1083 returns the IP addresses which the given host name resolves to.
1084 @end itemize
1085
1086 @node java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
1087 @subsection @code{java.net.VMNetworkInterface}
1088
1089 @code{VMNetworkInterface} currently consists of a single @code{static}
1090 @code{native} method, @code{getInterfaces()}, which retrieves the
1091 network interfaces available on the underlying platform as a @code{Vector}.
1092 The current GNU Classpath implementation is a native stub.
1093
1094 @node java.nio, java.nio.channels, java.net, Classpath Hooks
1095 @section java.nio
1096
1097 The @code{java.nio} package is part of the New I/O framework added in
1098 Java 1.4.  This splits I/O into the concepts of @emph{buffers},
1099 @emph{charsets}, @emph{channels} and @emph{selectors}, and
1100 @code{java.nio} defines the buffer classes.  As far as native and VM
1101 code is concerned, the new package needs support for low-level efficient
1102 buffer operations.
1103
1104 @menu
1105 * java.nio.VMDirectByteBuffer::
1106 @end menu
1107
1108 @node java.nio.VMDirectByteBuffer,,java.nio,java.nio
1109 @subsection @code{java.nio.VMDirectByteBuffer}
1110
1111 A @code{ByteBuffer} maintains a buffer of bytes, and allows it to be
1112 manipulated using primitive operations such as @code{get}, @code{put},
1113 @code{allocate} and @code{free}.  A direct buffer avoids intermediate
1114 copying, and uses native data which shouldn't be manipulated by a
1115 garbage collector.  The VM class consists of @code{static} @code{native}
1116 methods, all of which are given default implementations by GNU
1117 Classpath.
1118
1119 @itemize @bullet
1120 @item @code{init()} -- Creates an instance of an appropriate
1121 @code{gnu.classpath.RawData} class.  This class is not garbage
1122 collected, is created natively and is used in the other methods to reference
1123 the buffered data.
1124 @item @code{allocate(int)} -- Allocates the memory for the buffer using
1125 @code{malloc} and returns a reference to the @code{RawData} class.
1126 @item @code{free(RawData)} -- Frees the memory used by the buffer.
1127 @item @code{get(RawData,int)}  -- Returns the data at the specified index.
1128 @item @code{get(RawData,int,byte[],int,int)} -- Copies a section of the
1129 data into a byte array using @code{memcpy}.
1130 @item @code{put(RawData,int,byte)} -- Puts the given data in the buffer
1131 at the specified index.
1132 @item @code{adjustAddress(RawData,int)} -- Adjusts the pointer into the buffer.
1133 @item @code{shiftDown(RawData,int,int,int)} -- Moves the content of the buffer
1134 at an offset down to a new offset using @code{memmove}.
1135 @end itemize
1136  
1137 @node java.nio.channels, gnu.java.nio, java.nio, Classpath Hooks
1138 @section java.nio.channels
1139
1140 Channels provide the data for the buffers with the New I/O packages.
1141 For example, a channel may wrap a file or a socket.  The VM hooks,
1142 at the moment, simply allow the channels to be accessed by @code{java.io}
1143 streams.
1144
1145 @menu
1146 * java.nio.channels.VMChannels::
1147 @end menu
1148
1149 @node java.nio.channels.VMChannels,,java.nio.channels,java.nio.channels
1150 @subsection @code{java.nio.channels.VMChannels}
1151
1152 @code{VMChannels} provides the methods that create the channels or
1153 streams.  The default implementation is in pure Java and simply wraps
1154 the channels in standard I/O classes from @code{java.io}.
1155
1156 @itemize @bullet
1157 @item @code{createStream(Class,Channel)} -- Creates a @code{FileChannel}
1158 which wraps an instance of the specified stream class, created by reflection.
1159 This method is private, and is used by the other two.
1160 @item @code{newInputStream(ReadableByteChannel)} -- Wraps the channel
1161 in a @code{FileInputStream}.
1162 @item @code{newOutputStream(WritableByteChannel)} -- Wraps the channel
1163 in a @code{FileOutputStream}.
1164 @end itemize
1165
1166 @node gnu.java.nio, java.lang.reflect, java.nio.channels, Classpath Hooks
1167 @section gnu.java.nio
1168
1169 The @code{gnu.java.nio} class provides Classpath implementations of the
1170 interfaces provided by @code{java.nio}.  The VM classes provide the native
1171 support necessary to implement @emph{pipes} and @emph{selectors}.
1172
1173 @menu
1174 * gnu.java.nio.VMPipe::
1175 * gnu.java.nio.VMSelector::
1176 @end menu
1177
1178 @node gnu.java.nio.VMPipe,gnu.java.nio.VMSelector,gnu.java.nio,gnu.java.nio
1179 @subsection @code{gnu.java.nio.VMPipe}
1180
1181 @code{VMPipe} provides the native functionality for a uni-directional pipe
1182 between a source and a destination (sink) channel.  It consists of one 
1183 @code{static} @code{native} method, @code{init(PipeImpl,SelectorProvider)},
1184 the reference implementation of which is currently a native stub.  Ideally,
1185 this should initialise the pipe at the native level.
1186
1187 @node gnu.java.nio.VMSelector,,gnu.java.nio.VMPipe,gnu.java.nio
1188 @subsection @code{gnu.java.nio.VMSelector}
1189
1190 A @code{Selector} selects between multiple @code{SelectableChannel}s based
1191 on their readiness and a key set.  The VM hook for the Classpath implementation
1192 of this is @code{VMSelector}, and this allows the actual @code{select()}
1193 operation to be performed.  This is represented by the @code{static}
1194 @code{native} method, @code{select(int[],int[],int[],long)}, and a default
1195 implementation of this is provided.
1196
1197 @node java.lang.reflect, gnu.java.lang, gnu.java.nio, Classpath Hooks
1198 @section @code{java.lang.reflect}
1199 @code{java.lang.reflect} provides the interface to Java's reflection
1200 facilities.  Via reflection, programmers can obtain type information about
1201 a particular instance at runtime or dynamically create new instances.
1202
1203 @menu
1204 * java.lang.reflect.VMArray::
1205 @end menu
1206
1207 @node java.lang.reflect.VMArray,,,java.lang.reflect
1208 @subsection @code{java.lang.reflect.VMArray}
1209
1210 The @code{VMArray} class provides a hook, @code{createObjectArray},
1211 which the VM uses to generate a new non-primitive array of a
1212 particular class and size.  The default implementation simply passes
1213 the job down to the standard JNI function, @code{NewObjectArray}.
1214
1215 @node gnu.java.lang, gnu.java.lang.management, java.lang.reflect, Classpath Hooks
1216 @section @code{gnu.java.lang}
1217
1218 @code{gnu.java.lang} provides VM interfaces for the GNU
1219 implementations of features in java.lang.  Currently, this includes the
1220 implementation of instrumentation.
1221
1222 @menu
1223 * gnu.java.lang.VMInstrumentationImpl::
1224 @end menu
1225
1226 @node gnu.java.lang.VMInstrumentationImpl,,,gnu.java.lang
1227 @subsection @code{gnu.java.lang.VMInstrumentationImpl}
1228
1229 The @code{gnu.java.lang.VMInstrumentationImpl} and
1230 @code{gnu.java.lang.InstrumentationImpl} classes provide an implementation of the
1231 @code{java.lang.instrument.Instrument} interface. 
1232 A @code{InstrumentationImpl} object should be created by the VM when agents
1233 are given in the command line (see the @code{java.lang.instrument} package
1234 documentation). The VM has to set the static field
1235 @code{VMClassLoader.instrumenter} to this object. The VM should implement the
1236 static native methods of the @code{VMInstrumentationImpl} class.
1237
1238 @itemize @bullet
1239 @item @code{isRedefineClassesSupported()} -- Returns true if the JVM supports
1240 class redefinition.
1241 @item @code{redefineClasses()} -- Gives a set of classes with new bytecodes.
1242 The VM must redefine the classes by reading the new bytecodes.
1243 @item @code{getAllLoadedClass()} -- Returns an array of all loaded classes.
1244 @item @code{getInitiatedClass()} -- Returns an array of all classes loaded
1245 by a specific class loader.
1246 @item @code{getObjectSize()} -- Gives the size of an object.
1247 @end itemize
1248
1249 Instrumentation allows to modify the bytecode of a class before it gets read
1250 by the VM. In GNU Classpath, the @code{ClassLoader.defineClass} method calls
1251 the @code{VMClassLoader.defineClassWithTransformers} method which first checks
1252 if @code{VMClassLoader.instrumenter} is @code{null}. If it's the case, it
1253 directly calls @code{VMClassLoader.defineClass}. If it's not the case, the
1254 method calls at first the @code{InstrumentationImpl.callTransformers} method,
1255 which calls each transformer registered to the @code{InstrumentationImpl}
1256 object and returns a new bytecode array. Then, it calls the
1257 @code{VMClassLoader.defineClass} method with this new bytecode array.
1258
1259 The second use of instrumentation is to redefine a class after it has been
1260 loaded by the VM. This is done in the Java application by calling the
1261 @code{Instrumentation.redefineClasses} method of the standard interface on
1262 a @code{Instrumentation} object. The @code{InstrumentationImpl.redefineClasses}
1263 method calls the @code{VMInstrumentationImpl.redefineClasses} native method
1264 which must be implemented by the VM. The implementation should call the
1265 @code{InstrumentationImpl.callTransformers} method.
1266
1267 @node gnu.java.lang.management, java.lang.management, gnu.java.lang, Classpath Hooks
1268 @section @code{gnu.java.lang.management}
1269
1270 @code{gnu.java.lang.management} provides the VM interfaces for the GNU
1271 implementations of the management beans.  
1272
1273 @menu
1274 * gnu.java.lang.management.VMRuntimeMXBeanImpl::
1275 * gnu.java.lang.management.VMClassLoadingMXBeanImpl::
1276 * gnu.java.lang.management.VMThreadMXBeanImpl::
1277 * gnu.java.lang.management.VMMemoryMXBeanImpl::
1278 * gnu.java.lang.management.VMCompilationMXBeanImpl::
1279 * gnu.java.lang.management.VMMemoryPoolMXBeanImpl::
1280 * gnu.java.lang.management.VMMemoryManagerMXBeanImpl::
1281 * gnu.java.lang.management.VMGarbageCollectorMXBeanImpl::
1282 @end menu
1283
1284 @node gnu.java.lang.management.VMRuntimeMXBeanImpl,gnu.java.lang.management.VMClassLoadingMXBeanImpl,,gnu.java.lang.management
1285 @subsection @code{gnu.java.lang.management.VMRuntimeMXBeanImpl}
1286
1287 The @code{gnu.java.lang.management.RuntimeMXBeanImpl} provides an
1288 implementation of the @code{java.lang.management.RuntimeMXBean} interface,
1289 and is supported by VM functionality in the form of
1290 @code{gnu.java.lang.management.VMRuntimeMXBeanImpl}.  This provides a
1291 series of methods, which should be implemented by the virtual machine
1292 in order to provide the required information for the bean.  The VM
1293 methods are generally representative of information that is only
1294 available from the virtual machine, such as the command-line arguments
1295 it was given at startup.
1296
1297 The methods are as follows:
1298
1299 @itemize @bullet
1300 @item @code{(getInputArguments())} -- The VM should supply
1301 a @code{String} array containing each of the command-line
1302 arguments, excluding those that are directed at the
1303 @code{main()} method.  The reference implementation expects
1304 this to be a native method.
1305 @item @code{(getName())} -- The VM developer should choose
1306 an appropriate name for the virtual machine.  This name can
1307 be instance-specific e.g. it can include things like the
1308 process identifier or host name of the machine, which only
1309 apply to the current running instance.  Thus, the intention is
1310 that this name refers to the entity that the other information
1311 refers to, rather than the VM in general.  The reference
1312 implementation supplies a default concatenation of the VM
1313 name and version.
1314 @item @code{(getStartTime())} -- This should return the number
1315 of milliseconds at which the virtual machine was started.
1316 The uptime property of the bean is provided relative to this
1317 value.  Again, the reference implementation also expects
1318 this method to be native.
1319 @end itemize
1320
1321 The virtual machine also needs to provide either the
1322 @code{sun.boot.class.path} or @code{java.boot.class.path}
1323 property in order to support the optional boot class path
1324 retrieval functionality.
1325
1326 @node gnu.java.lang.management.VMClassLoadingMXBeanImpl,gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management.VMRuntimeMXBeanImpl,gnu.java.lang.management
1327 @subsection @code{gnu.java.lang.management.VMClassLoadingMXBeanImpl}
1328
1329 The @code{gnu.java.lang.management.ClassLoadingMXBeanImpl} provides an
1330 implementation of the @code{java.lang.management.ClassLoadingMXBean} interface,
1331 and is supported by VM functionality in the form of
1332 @code{gnu.java.lang.management.VMClassLoadingMXBeanImpl}.  This provides a
1333 series of methods, which should be implemented by the virtual machine
1334 in order to provide the required information for the bean.  Implementing
1335 this bean requires the VM to monitor when classes are loaded and unloaded,
1336 and provide the option of verbose class loading output.
1337
1338 The methods are as follows:
1339
1340 @itemize @bullet
1341 @item @code{(getLoadedClassCount())} -- This should return
1342 the number of classes that are currently loaded by the VM.
1343 @item @code{(getUnloadedClassCount())} -- This should return
1344 the number of classes that have been loaded by the VM, but
1345 have since been unloaded.
1346 @item @code{(isVerbose())} -- This should return @code{true}
1347 or @code{false}, depending on whether verbose class loading
1348 output is turned or not, respectively.
1349 @item @code{(setVerbose(boolean))} -- This should allow the
1350 verbose class loading output to be turned on and off.
1351 @end itemize
1352
1353 @node gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management.VMClassLoadingMXBeanImpl,gnu.java.lang.management
1354 @subsection @code{gnu.java.lang.management.VMThreadMXBeanImpl}
1355
1356 The @code{gnu.java.lang.management.ThreadMXBeanImpl} provides an
1357 implementation of the @code{java.lang.management.ThreadMXBean} interface,
1358 and is supported by VM functionality in the form of
1359 @code{gnu.java.lang.management.VMThreadMXBeanImpl}.  This provides a
1360 series of methods, which should be implemented by the virtual machine
1361 in order to provide the required information for the bean.  Implementing
1362 this bean requires the VM to monitor thread-related statistics such as
1363 how often the blocked and waiting states have been entered, as well as
1364 additional optional support for time and contention monitoring.
1365
1366 Optional support is determined by the following properties:
1367
1368 @itemize @bullet
1369 @item @code{gnu.java.lang.management.CurrentThreadTimeSupport} --
1370 This property should be present if the VM supports monitoring the
1371 time used by the current thread.  If time monitoring for all threads
1372 is supported, this need not be provided.
1373 @item @code{gnu.java.lang.management.ThreadTimeSupport} --
1374 This property should be present if the VM supports monitoring the
1375 time used by all threads.
1376 @item @code{gnu.java.lang.management.ThreadContentionSupport} --
1377 This property should be present if the VM supports thread contention
1378 monitoring.
1379 @item @code{gnu.java.lang.management.MonitorUsageMonitoringSupport} --
1380 This property should be present if the VM supports the monitoring
1381 of object monitor usage.
1382 @item @code{gnu.java.lang.management.OwnableSynchronizerUsageMonitoringSupport} --
1383 This property should be present if the VM supports the monitoring
1384 of ownable synchronizer usage.
1385 @end itemize
1386
1387 In addition, the property
1388 @code{gnu.java.lang.management.ThreadTimeInitallyEnabled} may be
1389 set to the @code{String} value, @code{"true"}, if time monitoring
1390 is enabled at startup.
1391
1392 The methods are as follows:
1393
1394 @itemize @bullet
1395 @item @code{(findDeadlockedThreads())} -- This should return
1396 an array of thread identifiers which match threads involved in
1397 deadlock cycles (where each thread is waiting to obtain a lock
1398 held by one of the others) on object monitors or ownable
1399 synchronizers.  This is specified as a native method in the
1400 reference implementation, and is optional.  It is only called
1401 when the VM supports ownable synchronizer monitoring.
1402 @item @code{(findMonitorDeadlockedThreads())} -- This should return
1403 an array of thread identifiers which match threads involved in
1404 deadlock cycles (where each thread is waiting to obtain a lock
1405 held by one of the others) on object monitors.  This is specified
1406 as a native method in the reference implementation.
1407 @item @code{(getAllThreads())} -- This should return an array of
1408 all live threads and set the @code{filled} variable to the number
1409 found.  A default implementation is provided.
1410 @item @code{(getAllThreadIds())} -- This should return an array of
1411 all live thread identifiers.  An implementation is provided against
1412 @code{getAllThreads()} by default.
1413 @item @code{(getCurrentThreadCpuTime())} -- This should return the
1414 approximate number of nanoseconds of CPU time the current thread
1415 has used.  This is an optional native method, which is used by VMs
1416 supporting time monitoring.
1417 @item @code{(getCurrentThreadUserTime())} -- This should return the
1418 approximate number of nanoseconds of user time the current thread
1419 has used.  This is an optional native method, which is used by VMs
1420 supporting time monitoring.
1421 @item @code{(getDaemonThreadCount())} -- This should return the number
1422 of live daemon threads.  A default implementation is provided, based
1423 on @code{getAllThreads()}.
1424 @item @code{(getLockInfo(ThreadInfo))} -- This is an optional native
1425 method called when the VM supports ownable synchronizer usage monitoring
1426 and the user has requested information for a particular thread.  The
1427 supplied @code{ThreadInfo} object should be filled out with an
1428 array of @code{LockInfo} objects, providing details on each lock. 
1429 @item @code{(getMonitorInfo(ThreadInfo))} -- This is an optional native
1430 method called when the VM supports object monitor usage monitoring
1431 and the user has requested information for a particular thread.  The
1432 supplied @code{ThreadInfo} object should be filled out with an
1433 array of @code{MonitorInfo} objects, providing details on each lock. 
1434 @item @code{(getPeakThreadCount())} -- The VM should maintain a record
1435 of the peak number of live threads, and return it when this method is
1436 called.  This is specified as a native method in the reference
1437 implementation.
1438 @item @code{(resetPeakThreadCount())} -- This should reset the record
1439 of the peak number of live threads to the current number of live
1440 threads.  This is specified as a native method in the reference
1441 implementation.
1442 @item @code{(getThreadCount())} -- This should return the number of
1443 live threads.  A default implementation is provided, based on
1444 @code{getAllThreads()}.
1445 @item @code{(getThreadCpuTime(long))} -- This should return the
1446 approximate number of nanoseconds of CPU time the specified thread
1447 has used.  This is an optional native method, which is used by VMs
1448 supporting time monitoring.
1449 @item @code{(getThreadUserTime(long))} -- This should return the
1450 approximate number of nanoseconds of CPU time the specified thread
1451 has used.  This is an optional native method, which is used by VMs
1452 supporting time monitoring.
1453 @item @code{(getThreadInfoForId(long, int))} -- This return an instance
1454 of @code{java.lang.management.ThreadInfo} for the specified thread.
1455 The class includes a private constructor which VMs should use to initialise
1456 it with the appropriate values for the thread.  The second argument
1457 given here specifies the depth of the stack trace supplied on construction
1458 of the instance.  Special values are 0 (return an empty array) and
1459 @code{Integer.MAX_VALUE} (return the maximum depth possible).  This
1460 is specified as a native method in the reference implementation.
1461 @item @code{(getTotalStartedThreadCount())} -- This should return the
1462 total number of threads that have been started by the VM, including ones
1463 that have died.  This is specified as a native method in the reference
1464 implementation.
1465 @end itemize
1466
1467 @node gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management
1468 @subsection @code{gnu.java.lang.management.VMMemoryMXBeanImpl}
1469
1470 The @code{gnu.java.lang.management.MemoryMXBeanImpl} provides an
1471 implementation of the @code{java.lang.management.MemoryMXBean} interface,
1472 and is supported by VM functionality in the form of
1473 @code{gnu.java.lang.management.VMMemoryMXBeanImpl}.  This provides a
1474 series of methods, which should be implemented by the virtual machine
1475 in order to provide the required information for the bean.  Implementing
1476 this bean requires the VM to monitor the levels of heap and non-heap
1477 memory, and provide the number of objects which are eligible for garbage
1478 collection.
1479
1480 The methods are as follows:
1481
1482 @itemize @bullet
1483 @item @code{(getHeapMemoryUsage())} -- This should return
1484 an instance of @code{java.lang.management.MemoryUsage} with
1485 values pertaining to the heap.  A default implementation is
1486 provided, based on @code{java.lang.Runtime}'s methods.
1487 @item @code{(getNonHeapMemoryUsage())} -- This should return
1488 an instance of @code{java.lang.management.MemoryUsage} with
1489 values pertaining to non-heap memory.
1490 @item @code{(getObjectPendingFinalizationCount())} -- Returns
1491 the number of objects which are no longer referenced, and which
1492 will thus be garbage collected on the next run of the garbage
1493 collector.
1494 @item @code{(isVerbose())} -- This should return @code{true}
1495 or @code{false}, depending on whether verbose memory management
1496 output is turned or not, respectively.
1497 @item @code{(setVerbose(boolean))} -- This should allow the
1498 verbose memory management output to be turned on and off.
1499 @end itemize
1500
1501 @node gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management
1502 @subsection @code{gnu.java.lang.management.VMCompilationMXBeanImpl}
1503
1504 The @code{gnu.java.lang.management.CompilationMXBeanImpl} provides an
1505 implementation of the optional @code{java.lang.management.CompilationMXBean}
1506 interface, and is supported by VM functionality in the form of
1507 @code{gnu.java.lang.management.VMCompilationMXBeanImpl}.  This provides a
1508 single method for returning the number of milliseconds the virtual
1509 machine's Just-In-Time (JIT) compiler has spent compiling.  Even if
1510 a JIT compiler is available and an instance of the bean supplied, this
1511 method is still optional.
1512
1513 Optional support is determined by the following properties:
1514
1515 @itemize @bullet
1516 @item @code{gnu.java.lang.compiler.name} -- This property should
1517 specify the name of the JIT compiler.  Classpath also uses this,
1518 within @code{java.lang.management.ManagementFactory}, to determine
1519 whether a bean should be created.  If this property is set to a
1520 non-null value, a bean will be created and its @code{getName()}
1521 method will return this value.
1522 @item @code{gnu.java.lang.management.CompilationTimeSupport} --
1523 This property should be present if the VM supports monitoring the
1524 time spent compiling.
1525 @end itemize
1526
1527 Time support is implemented by the following method:
1528
1529 @itemize @bullet
1530 @item @code{(getTotalCompilationTime())} -- This should return the
1531 number of milliseconds the JIT compiler has spent compiling.
1532 @end itemize
1533
1534 @node gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management
1535 @subsection @code{gnu.java.lang.management.VMMemoryPoolMXBeanImpl}
1536
1537 The @code{gnu.java.lang.management.MemoryPoolMXBeanImpl} provides an
1538 implementation of the optional @code{java.lang.management.MemoryPoolMXBean}
1539 interface, and is supported by VM functionality in the form of
1540 @code{gnu.java.lang.management.VMMemoryPoolMXBeanImpl}.  Providing
1541 this interface requires implementing a number of methods for each supported
1542 pool.  These return statistics on memory usage, and, optionally, allows
1543 monitoring of when memory usage exceedes a preset threshold.
1544
1545 Optional support is determined by the following properties:
1546
1547 @itemize @bullet
1548 @item @code{gnu.java.lang.management.CollectionUsageThresholdSupport} --
1549 This property should be present if the VM supports setting a collection
1550 usage threshold and monitoring when it is matched or exceeded.  Collection
1551 usage thresholds are related to the remaining memory usage following a
1552 garbage collection cycle.
1553 @item @code{gnu.java.lang.management.UsageThresholdSupport} --
1554 This property should be present if the VM supports setting a 
1555 usage threshold and monitoring when it is matched or exceeded.  
1556 @end itemize
1557
1558 The methods are as follows (all take a pool name as their
1559 first parameter):
1560
1561 @itemize @bullet
1562 @item @code{(getCollectionUsage(String))} -- Returns a
1563 @code{java.lang.management.MemoryUsage} object, containing the
1564 memory usage statistics following a garbage collection cycle
1565 for the specified pool.  This may also return @code{null} if
1566 the pool isn't an appropriate pool for this particular task.
1567 @item @code{(getCollectionUsageThreshold(String))} -- Returns
1568 the pool's collection usage threshold, if supported.
1569 @item @code{(getCollectionUsageThresholdCount(String))} -- Returns
1570 the number of times the specified pool has matched or exceeded
1571 its collection usage threshold, if supported.
1572 @item @code{(getMemoryManagerNames(String))} -- Returns a list
1573 of names of memory managers which manage the specified pool.
1574 @item @code{(getPeakUsage(String))} -- Returns a
1575 @code{java.lang.management.MemoryUsage} object for the peak
1576 usage level of the specified pool.
1577 @item @code{(getType(String))} -- Returns a string containing
1578 either @code{"HEAP"} or @code{"NON_HEAP"} which indicates the type of
1579 memory used by the specified pool.
1580 @item @code{(getUsage(String))} -- Returns a
1581 @code{java.lang.management.MemoryUsage} object for the current
1582 usage level of the specified pool.
1583 @item @code{(getUsageThreshold(String))} -- Returns
1584 the pool's usage threshold, if supported.
1585 @item @code{(getUsageThresholdCount(String))} -- Returns
1586 the number of times the specified pool has matched or exceeded
1587 its usage threshold, if supported.
1588 @item @code{(isValid(String))} -- Returns true if the pool
1589 is still in use by the virtual machine.
1590 @item @code{(resetPeakUsage(String))} -- Resets the peak usage
1591 levels to the current usage levels for the specified pool.
1592 @item @code{(setCollectionUsageThreshold(String, long))} -- Sets
1593 the pool's collection usage threshold, if supported.
1594 @item @code{(setUsageThreshold(String, long))} -- Sets
1595 the pool's usage threshold, if supported.
1596 @end itemize
1597
1598 @node gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management.VMGarbageCollectorMXBeanImpl,gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management
1599 @subsection @code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}
1600
1601 The @code{gnu.java.lang.management.MemoryManagerMXBeanImpl} provides an
1602 implementation of the optional @code{java.lang.management.MemoryManagerMXBean}
1603 interface, and is supported by VM functionality in the form of
1604 @code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}.  Providing
1605 this interface requires implementing two methods (each takes the name
1606 of the manager as the first argument):
1607
1608 @itemize @bullet
1609 @item @code{(getMemoryPoolNames(String))} -- Returns a list of the
1610 memory pools that the manager maintains.  A default implementation
1611 which scans the results of @code{getMemoryManagerNames()} for each
1612 pool is provided.
1613 @item @code{(isValid(String))} -- Returns true if the specified
1614 manager is still valid i.e. it is still in use by the virtual machine.
1615 @end itemize
1616
1617 @node gnu.java.lang.management.VMGarbageCollectorMXBeanImpl,,gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management
1618 @subsection @code{gnu.java.lang.management.VMGarbageCollectorMXBeanImpl}
1619
1620 The @code{gnu.java.lang.management.GarbageCollectorMXBeanImpl} provides an
1621 implementation of the optional @code{java.lang.management.GarbageCollectorMXBean}
1622 interface, and is supported by VM functionality in the form of
1623 @code{gnu.java.lang.management.VMGarbageCollectorMXBeanImpl}.  Providing
1624 this interface requires implementing two methods (each takes the name
1625 of the garbage collector as the first argument):
1626
1627 @itemize @bullet
1628 @item @code{(getCollectionCount(String))} -- Returns the number of
1629 times the specified garbage collector has run.
1630 @item @code{(getCollectionTime(String))} -- Returns the accumulated
1631 number of milliseconds for which the garbage collector has run.
1632 @end itemize
1633
1634 Note that each garbage collector is also a memory manager, and so an
1635 implementation of the @code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}
1636 methods for its name should also be provided.
1637
1638 @node java.lang.management, Classpath Callbacks, gnu.java.lang.management, Classpath Hooks
1639 @section @code{java.lang.management}
1640
1641 @code{gnu.java.lang.management} provides the VM interfaces for the GNU
1642 implementations of the management beans.  
1643
1644 @menu
1645 * java.lang.management.VMManagementFactory::
1646 @end menu
1647
1648 @node java.lang.management.VMManagementFactory,,,java.lang.management
1649 @subsection @code{java.lang.management.VMManagementFactory}
1650
1651 This VM interface provides the names of the memory pools, memory managers
1652 and garbage collectors for use by the @code{java.lang.management.ManagementFactory}
1653 in creating lists of appropriate beans for these types of managed object.
1654
1655 The methods are as follows:
1656
1657 @itemize @bullet
1658 @item @code{(getMemoryPoolNames())} -- Returns a list of the names
1659 of the current memory pools in use by the virtual machine.
1660 @item @code{(getMemoryManagerNames())} -- Returns a list of the names
1661 of the current memory managers in use by the virtual machine.  This
1662 should not include those that are also garbage collectors.
1663 @item @code{(getGarbageCollectorNames())} -- Returns a list of the names
1664 of the current garbage collectors in use by the virtual machine.
1665 @end itemize
1666
1667 @node Classpath Callbacks, , java.lang.management, Classpath Hooks
1668 Some of the classes you implement for the VM will need to call back to
1669 package-private methods in Classpath:
1670
1671 @itemize @bullet
1672 @item @code{java.lang.ThreadGroup.addThread(Thread)}
1673 Call this method from @code{Thread} when a new @code{Thread} is created, to add it to
1674 the group.
1675
1676 @item @code{java.lang.ThreadGroup.removeThread(Thread)}
1677 Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.
1678
1679 @item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireThresholdExceededNotification(String, long, long, long, long)}
1680 If the monitoring of memory usage thresholds is supported, this method
1681 should be called when the normal usage of a memory pool crosses the
1682 threshold, in order to emit a notification.  Another notification
1683 should not be emitted until there is an intermittent period where the
1684 usage is again below the threshold.  The parameters are the memory
1685 pool name, the usage levels (init, used, committed and max) and the
1686 number of times the threshold has been crossed.
1687
1688 @item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireCollectionThresholdExceededNotification(String, long, long, long, long)}
1689 If the monitoring of memory usage thresholds is supported, this method
1690 should be called when the usage of a memory pool after a garbage
1691 collection cycle crosses the threshold, in order to emit a
1692 notification.  Another notification should not be emitted until there
1693 is an intermittent period where the usage is again below the
1694 threshold.  The parameters are the memory pool name, the usage levels
1695 (init, used, committed and max) and the number of times the threshold
1696 has been crossed.
1697
1698 @end itemize
1699
1700 @node VM Hooks, JNI Implementation, Classpath Hooks, Top
1701 @comment node-name, next, previous, up
1702 @chapter VM Hooks
1703
1704 VMs need to do some dirty work; there are some things in the VM that
1705 unfortunately are dependent on the internal structure of various
1706 classes.  This is a guide to all of the things the VM itself needs to
1707 know about classes.
1708
1709 Some of the core classes, while being implemented by GNU Classpath,
1710 provide space for state (in the form of a @code{vmdata} object) to be
1711 stored by the VM, and can not be constructed normally.
1712
1713 @itemize @bullet
1714 @item java.lang.Class
1715 @item java.lang.ClassLoader
1716 @end itemize
1717
1718 The default implementations of some VM classes also follow this methodology,
1719 when it is intended that most VMs will keep the default.
1720
1721 @itemize @bullet
1722 @item java.lang.VMThread
1723 @item java.lang.VMThrowable
1724 @end itemize
1725
1726 Several core classes must be completely implemented by the VM for Classpath to
1727 work, although reference implementations are provided.  These classes are:
1728
1729 @itemize @bullet
1730 @item java.lang.reflect.Constructor
1731 @item java.lang.reflect.Method
1732 @item java.lang.reflect.Field
1733 @end itemize
1734
1735 The following issues are of note;
1736
1737 @itemize @bullet
1738 @item @code{java.lang.Class} @*
1739 The GNU Classpath implementation of @code{java.lang.Class} provides an
1740 object for storing the internal state of the class maintained by the VM.
1741 This is the only known place where this matters.  The class is
1742 constructed with this data by the VM.  Some VMs do not create the
1743 @code{Class} object at the point where the class is defined; instead,
1744 they wait until a @code{Class} object is actually used.
1745
1746 @item Array Classes @*
1747 When you are creating an array class, you should set the
1748 @code{ClassLoader} of the array class to the @code{ClassLoader} of its
1749 component type.  Whenever you add a class to a @code{ClassLoader}, you
1750 need to notify the @code{ClassLoader} and add the new @code{Class} to
1751 its internal cache of classes.  To do this, call
1752 @code{ClassLoader.addVMCreatedClass(Class)}.  @emph{Note: this is
1753 written in anticipation of 1.2 support and does not apply just yet.}
1754
1755 @item Primordial Class Loader @*
1756 When the primordial class loader loads a class, it needs to tell
1757 Classpath what it has done in order for security stuff to work right.
1758 To do this, call the static method
1759 @code{ClassLoader.newPrimordialClass(Class)}.
1760
1761 Even the first few core classes need to do this; in order to do it,
1762 simply call this method @emph{after} the initial class loading has been
1763 done.  No harm will come, as long as you follow the guidelines in the
1764 @pxref{Initialization} section.
1765
1766 @emph{Note: this is written in anticipation of 1.2 support and does not
1767 apply just yet.}
1768
1769 @item Top-level Exception Handler @*
1770 Exceptions take care of themselves in Classpath; all you need to do in
1771 the top-level exception handler is call @code{Throwable.printStackTrace()}.
1772
1773 @item Security and Traces @*
1774 There will eventually be a feature in the 1.2 security that keeps the
1775 @code{AccessController} from having to evaluate @emph{all} of the
1776 @code{ProtectionDomain}s every time a security check is made.  I think a common
1777 case is a single method doing a lot of things that require security
1778 checks.  However, I don't want to bog down the method stack too much, so
1779 this feature of the VM will have the @code{AccessController} for a thread
1780 calling out to the VM to tell it how high it was on the stack when it
1781 made the last security request.  Every time the stack goes lower than
1782 that number, the VM will decrement the number.  The @code{AccessController}
1783 will remember what the accumulated protection status was at every stack
1784 level (an @code{AccessControlContext}) and use that aggregated information to
1785 do the check.  I am not sure, however, whether the savings are
1786 substantial enough to outweigh the integer check and set after every
1787 method call.  I will investigate.
1788
1789 @item Threading @*
1790 I figured I'd put this here because a VM guy might be wondering about it.
1791 We implement @code{ThreadGroup}, but that class is almost entirely
1792 VM-independent.  The root @code{ThreadGroup}, a static field called
1793 @code{ThreadGroup.root}, should be initialized by Classpath, but if you wish to
1794 reinitialize it yourself, there should be no harm.
1795
1796 @end itemize
1797
1798 @node JNI Implementation, JVMTI Implementation, VM Hooks, Top
1799 @comment  node-name,  next,  previous,  up
1800 @chapter JNI Implementation
1801
1802 Classpath comes with its own implementation of @file{jni.h}.  This
1803 file can be customized by the VM in a few ways, by defining macros
1804 that affect the interpretation of the file.  These macros are all
1805 intended for use by a VM which uses GNU Classpath and which wants to
1806 use a single copy of @file{jni.h} for both internal and external use.
1807
1808 @itemize @bullet
1809 @item _CLASSPATH_VM_JNI_TYPES_DEFINED
1810 Some VMs like to define JNI ``object'' types in a special way.  If
1811 this macro is defined, the Classpath @file{jni.h} will avoid defining
1812 these types.  By default, these types are defined in @file{jni.h}.
1813 The full list of types and macros treated this way is: @samp{jobject},
1814 @samp{jclass}, @samp{jstring}, @samp{jthrowable}, @samp{jweak},
1815 @samp{jarray}, @samp{jobjectArray}, @samp{jbyteArray},
1816 @samp{jshortArray}, @samp{jintArray}, @samp{jlongArray},
1817 @samp{jbooleanArray}, @samp{jcharArray}, @samp{jfloatArray},
1818 @samp{jdoubleArray}, @samp{JNIEnv}, @samp{JavaVM}, @samp{JNI_TRUE}
1819 (macro), @samp{JNI_FALSE} (macro).
1820
1821 @item _CLASSPATH_VM_INTERNAL_TYPES_DEFINED
1822 If the VM has its own definitions for @samp{jfieldID} and
1823 @samp{jmethodID}, then it should define this macro.  Otherwise,
1824 @file{jni.h} will provide definitions for these types.
1825
1826 @item _CLASSPATH_JNIIMPEXP
1827 Three functions -- @samp{JNI_GetDefaultJavaVMInitArgs},
1828 @samp{JNI_CreateJavaVM}, and @samp{JNI_GetCreatedJavaVMs} -- must be
1829 marked as @samp{JNIIMPORT} when seen by user code, but most likely
1830 should be marked as @samp{JNIEXPORT} when defined in the VM
1831 implementation.  This macro can be defined to one or the other by the
1832 VM as appropriate.  If this macro is not defined, it defaults to
1833 @samp{JNIIMPORT}.
1834
1835 @item _CLASSPATH_JNIENV_CONTENTS
1836 A VM can add fields to the @samp{JNIEnv} structure by defining this to
1837 be a sequence of field declarations.
1838
1839 @end itemize
1840
1841 @node JVMTI Implementation, Miscellaneous VM Requirements, JNI Implementation, Top
1842 @comment node-name, next, previous, up
1843 @chapter JVMTI Implementation
1844
1845 Classpath comes with its own implementation of @file{jvmti.h}.  This
1846 file can be customized by the VM in a few ways by defining macros that
1847 affect the interpretation of the file.  These macros are all intended
1848 for use for use by a VM which uses GNU Classpath and which wants to
1849 use a single copy of @file{jvmti.h} for both internal and external use.
1850
1851 @itemize @bullet
1852 @item _CLASSPATH_VM_JVMTI_TYPES_DEFINED
1853 Some VMs like to define JVMTI ``object'' types in a special way.  If
1854 this macro is defined, the Classpath @file{jvmti.h} will avoid defining
1855 these types.  By default these types are defined in @file{jvmti.h}.  
1856 The full list of types and macros treated this way is: @samp{jthread},
1857 @samp{jthreadGroup}, @samp{jlocation}, and @samp{jrawMonitorID}.  By
1858 default @samp{jrawMonitorID} is defined as an opaque pointer which
1859 must be defined by the VM.
1860
1861 @item _CLASSPATH_JVMTIENV_CONTENTS
1862 A VM can add fields to the @samp{jvmtiEnv} structure by defining this
1863 to be a sequence of field declarations.
1864
1865 @end itemize
1866
1867 @node Miscellaneous VM Requirements,  , JVMTI Implementation, Top
1868 @comment  node-name,  next,  previous,  up
1869 @chapter Miscellaneous VM Requirements
1870
1871 Classpath places a few requirements on the VM that uses it.
1872
1873 @menu
1874 * JNI Version::                 
1875 * VM Threading Model::          
1876 * Boot Library Path Property::
1877 @end menu
1878
1879 @node JNI Version, VM Threading Model, Miscellaneous VM Requirements, Miscellaneous VM Requirements
1880 @comment  node-name,  next,  previous,  up
1881 @section JNI Version
1882
1883 Classpath currently uses only JNI 1.1, except for one JNI 1.2 function
1884 in the JNI Invocation API: GetEnv().  And GetEnv() is only used in the
1885 now deprecated ``portable native sync'' code.
1886
1887 A future direction will probably be to require that all VMs provide
1888 JNI 1.2.  If this poses problems, please raise them on the classpath
1889 mailing list. 
1890
1891 @node VM Threading Model, Boot Library Path Property, JNI Version, Miscellaneous VM Requirements
1892 @comment  node-name,  next,  previous,  up
1893 @section VM Threading Model
1894
1895 VM authors can implement a number of different threading models. When
1896 native code is also threaded there is the potential for one threading
1897 model to deadlock the other. The
1898 @uref{http://java.sun.com/docs/books/jni/html/other.html#29406,Java
1899 Native Interface Programmer's Guide and Specification} suggests
1900 consulting VM documentation in such situations. Classpath uses
1901 existing libraries, for example the AWT peers can use the GTK+
1902 graphics library. As these libraries assume a different threading
1903 model, there is the potential for the native code to deadlock a VM.
1904
1905 The different threading models available to a VM author are:
1906 @enumerate
1907 @item
1908 @i{Native threads}: Map a Java thread to an underlying operating system
1909 thread (normally a POSIX compatible pthread). This approach reduces
1910 the potential for deadlock as there is only one thread scheduling
1911 mechanism.
1912 @item
1913 @i{Green threads 1}: Green threads are threads scheduled by the VM,
1914 typically by switching swapping registers. In early VMs green threads
1915 were seen as advantageous as they didn't require the operating system
1916 to resechedule, save and swap all of a threads registers. The green
1917 thread 1 model switches thread on an externally created event, such as
1918 a timer interrupt. An example of a VM using this approach is Kaffe
1919 configured with its jthreads model.
1920 @item
1921 @i{Green threads 2}: The essential difference with this model is to
1922 not switch threads on an event, but at fixed points in the code being
1923 executed by the VM. Points chosen could be backward branches (loops)
1924 or method calls. This approach can be advantageous to nonconservative
1925 garbage collectors, as non-running threads would be at known points
1926 and can have fixed register maps. It can also reduce the number of
1927 registers it is necessary to swap when switching threads.
1928 @item
1929 @i{M:N threading}: a flaw to green threading is that it is unable to
1930 use multiple processors. @i{M}:@i{N} threading fixes this problem by
1931 running groups of green threads on multiple underlying native
1932 threads. An example of a VM using this approach is the Jikes RVM,
1933 which uses @i{M}:@i{N} threading combined with the green thread 2
1934 model.
1935 @end enumerate
1936
1937 An example of the problem of mixing threading models is:
1938 @itemize @bullet
1939 @item
1940 A Java thread calls a native method. The native method aquires a lock.
1941 @item
1942 The native method calls back into the VM.
1943 @item
1944 An event triggers the VM to reschedule the currently running thread.
1945 @item
1946 A new VM thread, executing on the same underlying native thread, calls
1947 a native method.
1948 @item
1949 The native method tries to aquire the lock already aquired earlier. As
1950 the lock is busy the thread waits and allows the operating system to
1951 reschedule native threads.
1952 @item
1953 The operating system reschedules the VM thread again, but the lock is
1954 still busy and in some threading models will remain busy forever
1955 (the VM is deadlocked).
1956 @end itemize
1957
1958 VMs that don't use the underlying operating system thread scheduling
1959 mechanism need to avoid deadlock. One now deprecated approach was to
1960 build Classpath and VMs on top of a wrapper thread library (aka
1961 portable native sync). The wrapper thread library used was GLIB's
1962 @dfn{gthreads}. This approach has been deprecated because:
1963 @enumerate
1964 @item
1965 The wrapper library is only in use by some native libraries. For
1966 example, GTK+ uses the gthread library but QT does not.
1967 @item
1968 The wrapper library can't be in use prior to the VM starting as the VM
1969 must replace the wrapper libraries functions with its own. This
1970 prevents the VM from running as a plugin in an application that
1971 already uses the wrapper library.
1972 @end enumerate
1973
1974 An alternative approach is for the VM to detect deadlocked native code
1975 and swap Java threads off of that native thread. The VM can't,
1976 however, swap two blocked native threads that are potentially
1977 deadlocking each other on a lock. The lock will be associated with the
1978 native thread. To prevent this from happening the VM must hijack
1979 functions that operate on locks. This is done by redifining the lock
1980 functions inside the VM and configuring the linker so that it uses the
1981 VMs symbol in preference to that of the external thread support
1982 library. The VM's lock function can then reschedule Java threads if it
1983 must wait for the lock.
1984
1985 @node Boot Library Path Property,  , VM Threading Model, Miscellaneous VM Requirements
1986 @comment  node-name,  next,  previous,  up
1987 @section Boot Library Path Property
1988
1989 As of GNU Classpath 0.15 a system property named @code{gnu.classpath.boot.library.path}
1990 can be set by the VM to specify the directories which contain GNU Classpath's native
1991 libraries. Usually this value is given at configuration time and is then hardcoded
1992 in the VM. However for development purposes it is handy to switch to another installation
1993 by overriding the properties' value on the command line.
1994
1995 A VM that does not support this feature can simply ignore the property.
1996
1997 For compatibility reasons we suggest to set the default value of @code{java.library.path}
1998 to the value of the @code{LD_LIBRARY_PATH} environment if it exists on your platform.
1999
2000 @bye
2001
2002
2003