path: root/doc/vmintegration.texinfo

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

@c %**start of header
@setfilename vmintegration.info
@settitle GNU Classpath VM Integration Guide
@c %**end of header

@setchapternewpage none

@ifinfo
This file contains important information you will need to know if you
are going to write an interface between GNU Classpath and a Virtual
Machine.

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

@ifnotplaintext
@dircategory GNU Libraries
@direntry
* VM Integration: (vmintegration).   GNU Classpath VM Integration Guide
@end direntry
@end ifnotplaintext
@end ifinfo

@titlepage
@title GNU Classpath VM Integration Guide
@author John Keiser
@author C. Brian Jones
@author Mark Wielaard

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2002 Free Software Foundation, Inc.
@sp 2
Permission is granted to make and distribute verbatim copies of
this document provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
document under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.

@end titlepage

@ifinfo
@node Top, Introduction, (dir), (dir)
@top GNU Classpath Hacker's Guide

This file contains important information you will need to know if you
are going to write an interface between GNU Classpath and a Virtual
Machine.

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

@end ifinfo

@menu
* Introduction::                An introduction to the Classpath project
* Initialization::              Initializing the classes
* Classpath Hooks::             Hooks from Classpath to the VM
* VM Hooks::                    Hooks from the underlying VM to Classpath
* JNI Implementation::		Hooking the VM to jni.h
* Miscellaneous VM Requirements::  
@end menu

@node Introduction, Initialization, Top, Top
@comment node-name, next, previous, up
@chapter Introduction

The Classpath Project's ambition to be a 100% clean room implementation
of the standard Java class libraries cannot be fulfilled without some
level of integration with the Virtual Machine, the underlying machinery
that actually runs Java.

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

@itemize @bullet
@item @uref{http://www.hungry.com/old-hungry/products/japhar/,Japhar}
Japhar was the first VM to use GNU Classpath.  Today you can see that
sort of relationship in the source tree which denotes several Japhar
specific files as a reference implementation of those pieces.  This VM
has been primarily tested against Linux and lacks garbage collections, a
JIT, and suffers recently from slow development.

@item @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}
Intel surprised us not long ago with the release of this rather advanced
VM that uses GNU Classpath for a set of class libraries and works on
Linux and Windows 2000.  As of June, 2004, it does not appear that ORP
is under active development.

@item @uref{http://www.sablevm.org/,SableVM}
SableVM is a robust, extremely portable, efficient, and
specifications-compliant Java Virtual Machine that aims to be easy to
maintain and to extend. It features a state-of-the-art, efficient
interpreter engine. Its source code is very accessible and easy to
understand, and has many robustness features that have been the object
of careful design.

@item @uref{http://www.kaffe.org,Kaffe}
Kaffe is an advanced VM and together with its own class libraries
provides a Java 1.1 compatible environment.

@item @uref{http://www.mozilla.org/projects/ef,Electrical Fire}
The Electrical File VM continues to be listed as a Mozilla project
though development has been somewhat quiet.  A number of concepts from
EF were expected at one point to be rolled into Japhar, but that
development has not occured as of yet.

@item @uref{http://latte.snu.ac.kr/,LaTTe}
This VM project so far supports only Sun UltraSparc processors using the
proprietary Solaris 2.5.1 or higher operating system.  LaTTe was derived
from Kaffe but claims a number of improvements.

@item @uref{http://gcc.gnu.org/java/,GNU Compiler for Java (GCJ)}
This is a portable, optimizing, ahead-of-time compiler for the Java
Programming Language. It can compile Java source code directly to native
machine code, Java source code to Java bytecode (class files), and Java
bytecode to native machine code. Compiled applications are linked with the
GCJ runtime, libgcj which is based on the GNU Classpath code, which provides
the core class libraries, a garbage collector, and a bytecode interpreter.
libgcj can dynamically load and interpret class files, resulting in mixed
compiled/interpreted applications.
GCJ is part of the GNU Compiler Collection (@uref{http://gcc.gnu.org/,GCC}).
On March 6 2000 the libgcj and GNU Classpath projects were officially merged
and there is active work on merging all the classes between the projects.
Licensed under GPL+exception, just as GNU Classpath is.

@item @uref{http://kissme.sourceforge.net/,Kissme}
This is a free Java Virtual Machine that is being developed on GNU/Linux
and can run console Java applications.  Kissme also provides support for
orthogonally persistent Java.
@c I don't know what ``orthogonally persistent Java'' is, and I bet
@c there are other people don't know either. -- Steve Augart, 4 June 2004

@item @uref{http://jamvm.sourceforge.net/,JamVM}
A simple, small bytecode interpreter that works out-of-the-box with
pure GNU Classpath; it is emerging as the preferred platform for
quickly testing a new build of GNU Classpath.  Licensed under the GPL.

@item @uref{http://oss.software.ibm.com/jikesrvm,Jikes RVM}
A free runtime environment for Java, written in Java.  Works
out-of-the-box with pure GNU Classpath.  Features an optimizing JIT.
Runs on the x86 and PowerPC architectures, on the AIX, Linux, and Mac
OS/X operating systems.  Licensed under the CPL (Common Public
License).  Extensively documented.  Actively developed as of June,
2004.

@end itemize

In the past integration efforts were focused mainly on Japhar with an eye
towards getting Electrical Fire to work.  Most information contained in
this document is gleaned from these efforts. Recently more work has been
done on getting gcj, orp and kissme to work out of the box with GNU Classpath
but there is much to do before that becomes a reality.


@node Initialization, Classpath Hooks, Introduction, Top
@comment node-name, next, previous, up
@chapter Initialization

The order of initialization, as far as I can tell, doesn't matter just
yet.  However, when we move to 1.2 support, it probably will matter, so
we'll have a note in here at that time.

The initialization order is currently documented in the
@file{Runtime.java} source file.

@node Classpath Hooks, VM Hooks, Initialization, Top
@comment node-name, next, previous, up
@chapter Classpath Hooks

Several core classes must be implemented by the VM for Classpath to
work.  These classes are:

@itemize @bullet
@item java.lang.Class
@item java.lang.Runtime
@item java.lang.Thread
@item java.lang.reflect.Constructor
@item java.lang.reflect.Method
@item java.lang.reflect.Field
@end itemize

You also need to implement some helper classes in java.lang that classes
from Classpath call out to to get certain VM-specific dirty work done:

@itemize @bullet
@item @code{java.lang.VMObject}
is the bridge between the low level @code{Object} facilities such
as making a clone, getting the class of the object and the wait/notify
semantics.
@item @code{java.lang.VMClassLoader}
provides methods for defining and resolving core and primitive classes.
@item @code{java.lang.VMSystem}
is used to initialize the @code{System} properties, the @code{System.arraycopy}
method and the @code{identityHashCode} of an @code{Object}.
@item @code{java.lang.VMSecurityManager}
provides the class context (stack trace) of the currently
executing thread and a way to get the currently active @code{ClassLoader}.
@item @code{java.lang.VMThrowable}
used to hold the VM state of a throwable, created when a @code{Throwable} is
created or the @code{fillInStacktrace()} method is called, when the actual stack
trace is needed (a lot of exceptions are never actually used), the
@code{getStackTrace()} method is used to create a real @code{StackTraceElement} array
for the exception.
@end itemize

Some of the classes you implement for the VM will need to call back to
package-private methods in Classpath:

@itemize @bullet
@item @code{java.lang.ThreadGroup.addThread(Thread)}
Call this method from @code{Thread} when a new @code{Thread} is created, to add it to
the group.

@item @code{java.lang.ThreadGroup.removeThread(Thread)}
Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.

@end itemize


@node VM Hooks, JNI Implementation, Classpath Hooks, Top
@comment node-name, next, previous, up
@chapter VM Hooks

VMs need to do some dirty work; there are some things in the VM that
unfortunately are dependent on the internal structure of various
classes.  This is a guide to all of the things the VM itself needs to
know about classes.

@itemize @bullet
@item @code{java.lang.Class} @*
You, the VM, get to create this @code{Class}, so you may define the internal
structure any way you wish.  You probably have code somewhere to
translate your internal class structure into a @code{Class} object.  That is
the only known place where this matters.  Some VMs do not create the
@code{Class} object at the point where the class is defined; instead, they wait
until a @code{Class} object is actually used.

@item Array Classes @*
When you are creating an array class, you should set the @code{ClassLoader} of
the array class to the @code{ClassLoader} of its component type.  Whenever you
add a class to a @code{ClassLoader}, you need to notify the @code{ClassLoader} and
add the new @code{Class} to its internal cache of classes.  To do this, call
@code{ClassLoader.addVMCreatedClass(Class)}.  @emph{Note: this is written in
anticipation of 1.2 support and does not apply just yet.}

@item Primordial Class Loader @*
When the primordial class loader loads a class, it needs to tell
Classpath what it has done in order for security stuff to work right.
To do this, call the static method
@code{ClassLoader.newPrimordialClass(Class)}.

Even the first few core classes need to do this; in order to do it,
simply call this method @emph{after} the initial class loading has been
done.  No harm will come, as long as you follow the guidelines in the
@pxref{Initialization} section.

@emph{Note: this is written in anticipation of 1.2 support and does not
apply just yet.}

@item Top-level Exception Handler @*
Exceptions take care of themselves in Classpath; all you need to do in
the top-level exception handler is call @code{Throwable.printStackTrace()}.

@item Security and Traces @*
There will eventually be a feature in the 1.2 security that keeps the
@code{AccessController} from having to evaluate @emph{all} of the
@code{ProtectionDomain}s every time a security check is made.  I think a common
case is a single method doing a lot of things that require security
checks.  However, I don't want to bog down the method stack too much, so
this feature of the VM will have the @code{AccessController} for a thread
calling out to the VM to tell it how high it was on the stack when it
made the last security request.  Every time the stack goes lower than
that number, the VM will decrement the number.  The @code{AccessController}
will remember what the accumulated protection status was at every stack
level (an @code{AccessControlContext}) and use that aggregated information to
do the check.  I am not sure, however, whether the savings are
substantial enough to outweigh the integer check and set after every
method call.  I will investigate.

@item Threading @*
I figured I'd put this here because a VM guy might be wondering about it.
We implement @code{ThreadGroup}, but that class is almost entirely
VM-independent.  The root @code{ThreadGroup}, a static field called
@code{ThreadGroup.root}, should be initialized by Classpath, but if you wish to
reinitialize it yourself, there should be no harm.

@end itemize

@node JNI Implementation, Miscellaneous VM Requirements, VM Hooks, Top
@comment  node-name,  next,  previous,  up
@chapter JNI Implementation

Classpath comes with its own implementation of @file{jni.h}.  This
file can be customized by the VM in a few ways, by defining macros
that affect the interpretation of the file.  These macros are all
intended for use by a VM which uses GNU Classpath and which wants to
use a single copy of @file{jni.h} for both internal and external use.

@itemize @bullet
@item _CLASSPATH_VM_JNI_TYPES_DEFINED
Some VMs like to define JNI ``object'' types in a special way.  If
this macro is defined, the Classpath @file{jni.h} will avoid defining
these types.  By default, these types are defined in @file{jni.h}.
The full list of types and macros treated this way is: @samp{jobject},
@samp{jclass}, @samp{jstring}, @samp{jthrowable}, @samp{jweak},
@samp{jarray}, @samp{jobjectArray}, @samp{jbyteArray},
@samp{jshortArray}, @samp{jintArray}, @samp{jlongArray},
@samp{jbooleanArray}, @samp{jcharArray}, @samp{jfloatArray},
@samp{jdoubleArray}, @samp{JNIEnv}, @samp{JavaVM}, @samp{JNI_TRUE}
(macro), @samp{JNI_FALSE} (macro).

@item _CLASSPATH_VM_INTERNAL_TYPES_DEFINED
If the VM has its own definitions for @samp{jfieldID} and
@samp{jmethodID}, then it should define this macro.  Otherwise,
@file{jni.h} will provide definitions for these types.

@item _CLASSPATH_JNIIMPEXP
Three functions -- @samp{JNI_GetDefaultJavaVMInitArgs},
@samp{JNI_CreateJavaVM}, and @samp{JNI_GetCreatedJavaVMs} -- must be
marked as @samp{JNIIMPORT} when seen by user code, but most likely
should be marked as @samp{JNIEXPORT} when defined in the VM
implementation.  This macro can be defined to one or the other by the
VM as appropriate.  If this macro is not defined, it defaults to
@samp{JNIIMPORT}.

@item _CLASSPATH_JNIENV_CONTENTS
A VM can add fields to the @samp{JNIEnv} structure by defining this to
be a sequence of field declarations.

@end itemize


@node Miscellaneous VM Requirements,  , JNI Implementation, Top
@comment  node-name,  next,  previous,  up
@chapter Miscellaneous VM Requirements

Classpath places a few requirements on the VM that uses it.

@menu
* JNI Version::                 
* VM Threading Model::          
* Boot Library Path Property::
@end menu

@node JNI Version, VM Threading Model, Miscellaneous VM Requirements, Miscellaneous VM Requirements
@comment  node-name,  next,  previous,  up
@section JNI Version

Classpath currently uses only JNI 1.1, except for one JNI 1.2 function
in the JNI Invocation API: GetEnv().  And GetEnv() is only used in the
``portable native sync'' code, so it's only actually used by Jikes RVM
and Kaffe.  

A future direction will probably be to require that all VMs provide
JNI 1.2.  If this poses problems, please raise them on the classpath
mailing list. 

@node VM Threading Model, Boot Library Path Property, JNI Version, Miscellaneous VM Requirements
@comment  node-name,  next,  previous,  up
@section VM Threading Model

Classpath's AWT peers use GTK+.  GTK+ uses GLIB.  Normally, Classpath
will initialize GLIB's @dfn{gthreads} to use
the platform's native threading model@footnote{The native threading
model is pthreads on Linux and AIX, the two platforms Classpath
currently runs on.}

If the Java runtime doesn't use the native threading model, then you
will want Classpath to tell GLIB to use the Java threading primitives
instead.  Otherwise, GLIB would use the native threading model to
perform operations such as creating thread-local data, and that just
doesn't work on systems (such as Kaffe in some configurations, and
such as Jikes RVM) that use @i{m}:@i{n} threading.

Historically, enabling the Java threading primitives had been done at
build time, by configuring classpath with the
@option{--portable-native-sync} option.  This had bad consequences,
though -- it meant that the prebuild GNU Classpath package distributed
with Debian GNU/Linux would not be usable with VMs that could
otherwise have used it.  Instead, we encourage
the use of the Java system property
@code{gnu.classpath.awt.gtk.portable.native.sync}.  A VM that wants
GLIB to use the Java threading primitives should modify
@code{VMRuntime.insertSystemProperties()} to include code like the
following:

@example
static void insertSystemProperties(Properties @var{p}) 
@end example
...
@example
@var{p}.put("gnu.classpath.awt.gtk.portable.native.sync", "true");
@end example

So, the configure option
@option{--portable-native-sync} is deprecated, and should go away in a
subsequent release of GNU Classpath.

@node Boot Library Path Property,  , VM Threading Model, Miscellaneous VM Requirements
@comment  node-name,  next,  previous,  up
@section Boot Library Path Property

As of GNU Classpath 0.15 a system property named @code{gnu.classpath.boot.library.path}
can be set by the VM to specify the directories which contain GNU Classpath's native
libraries. Usually this value is given at configuration time and is then hardcoded
in the VM. However for development purposes it is handy to switch to another installation
by overriding the properties' value on the command line.

A VM that does not support this feature can simply ignore the property.

For compatibility reasons we suggest to set the default value of @code{java.library.path}
to the value of the @code{LD_LIBRARY_PATH} environment if it exists on your platform.

@bye