hacking.texinfo

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

feel like you have to do it perfect right away or that contributions
aren't welcome if they aren't ``perfect''.  We all learn by doing and
interacting with each other.


@node Programming Goals, API Compatibility, Hacking Code, Top
@comment node-name, next, previous, up
@chapter Programming Goals

When you write code for Classpath, write with three things in mind, and
in the following order: portability, robustness, and efficiency.

If efficiency breaks portability or robustness, then don't do it the
efficient way.  If robustness breaks portability, then bye-bye robust
code.  Of course, as a programmer you would probably like to find sneaky
ways to get around the issue so that your code can be all three ... the
following chapters will give some hints on how to do this.

@menu
* Portability::                 Writing Portable Software                
* Utility Classes::             Reusing Software
* Robustness::                  Writing Robust Software               
* Java Efficiency::             Writing Efficient Java            
* Native Efficiency::           Writing Efficient JNI          
* Security::                    Writing Secure Software
@end menu

@node Portability, Utility Classes, Programming Goals, Programming Goals
@comment node-name, next, previous, up
@section Portability

The portability goal for Classpath is the following:

@enumerate
@item
native functions for each platform that work across all VMs on that
platform
@item
a single classfile set that work across all VMs on all platforms that
support the native functions.
@end enumerate

For almost all of Classpath, this is a very feasible goal, using a
combination of JNI and native interfaces.  This is what you should shoot
for.  For those few places that require knowledge of the Virtual Machine
beyond that provided by the Java standards, the VM Interface was designed.
Read the Virtual Machine Integration Guide for more information.

Right now the only supported platform is Linux.  This will change as that
version stabilizes and we begin the effort to port to many other
platforms.  Jikes RVM runs Classpath on AIX, and generally the Jikes
RVM team fixes Classpath to work on that platform. 

@node Utility Classes, Robustness, Portability, Programming Goals
@comment  node-name,  next,  previous,  up
@section Utility Classes

At the moment, we are not very good at reuse of the JNI code.  There
have been some attempts, called @dfn{libclasspath}, to
create generally useful utility classes.  The utility classes are in
the directory @file{native/jni/classpath} and they are mostly declared
in @file{native/jni/classpath/jcl.h}.  These utility classes are
currently only discussed in @ref{Robustness} and in @ref{Native
Efficiency}.

There are more utility classes available that could be factored out if
a volunteer wants something nice to hack on.  The error reporting and
exception throwing functions and macros in
@file{native/jni/gtk-peer/gthread-jni.c} might be good
candidates for reuse.  There are also some generally useful utility
functions in @file{gnu_java_awt_peer_gtk_GtkMainThread.c} that could
be split out and put into libclasspath.

@node Robustness, Java Efficiency, Utility Classes, Programming Goals
@comment node-name, next, previous, up
@section Robustness

Native code is very easy to make non-robust.  (That's one reason Java is
so much better!)  Here are a few hints to make your native code more
robust.

Always check return values for standard functions.  It's sometimes easy
to forget to check that malloc() return for an error.  Don't make that
mistake.  (In fact, use JCL_malloc() in the jcl library instead--it will
check the return value and throw an exception if necessary.)

Always check the return values of JNI functions, or call
@code{ExceptionOccurred} to check whether an error occurred.  You must
do this after @emph{every} JNI call.  JNI does not work well when an
exception has been raised, and can have unpredictable behavior.

Throw exceptions using @code{JCL_ThrowException}.  This guarantees that if
something is seriously wrong, the exception text will at least get out
somewhere (even if it is stderr).

Check for null values of @code{jclass}es before you send them to JNI functions.
JNI does not behave nicely when you pass a null class to it: it
terminates Java with a "JNI Panic."

In general, try to use functions in @file{native/jni/classpath/jcl.h}.  They
check exceptions and return values and throw appropriate exceptions.

@node Java Efficiency, Native Efficiency, Robustness, Programming Goals
@comment node-name, next, previous, up
@section Java Efficiency

For methods which explicitly throw a @code{NullPointerException} when an
argument is passed which is null, per a Sun specification, do not write
code like:

@example
int 
strlen (String foo) throws NullPointerException
@{
  if (foo == null)
    throw new NullPointerException ("foo is null");
  return foo.length ();
@}
@end example

Instead, the code should be written as:

@example
int
strlen (String foo) throws NullPointerException
@{
  return foo.length ();
@}
@end example

Explicitly comparing foo to null is unnecessary, as the virtual machine
will throw a NullPointerException when length() is invoked.  Classpath
is designed to be as fast as possible -- every optimization, no matter
how small, is important.

@node Native Efficiency, Security, Java Efficiency, Programming Goals
@comment node-name, next, previous, up
@section Native Efficiency

You might think that using native methods all over the place would give
our implementation of Java speed, speed, blinding speed.  You'd be
thinking wrong.  Would you believe me if I told you that an empty
@emph{interpreted} Java method is typically about three and a half times
@emph{faster} than the equivalent native method?

Bottom line: JNI is overhead incarnate.  In Sun's implementation, even
the JNI functions you use once you get into Java are slow.

A final problem is efficiency of native code when it comes to things
like method calls, fields, finding classes, etc.  Generally you should
cache things like that in static C variables if you're going to use them
over and over again.  GetMethodID(), GetFieldID(), and FindClass() are
@emph{slow}.  Classpath provides utility libraries for caching methodIDs
and fieldIDs in @file{native/jni/classpath/jnilink.h}.  Other native data can
be cached between method calls using functions found in
@file{native/jni/classpath/native_state.h}.

Here are a few tips on writing native code efficiently:

Make as few native method calls as possible.  Note that this is not the
same thing as doing less in native method calls; it just means that, if
given the choice between calling two native methods and writing a single
native method that does the job of both, it will usually be better to
write the single native method.  You can even call the other two native
methods directly from your native code and not incur the overhead of a
method call from Java to C.

Cache @code{jmethodID}s and @code{jfieldID}s wherever you can.  String
lookups are 
expensive.  The best way to do this is to use the 
@file{native/jni/classpath/jnilink.h}
library.  It will ensure that @code{jmethodID}s are always valid, even if the
class is unloaded at some point.  In 1.1, jnilink simply caches a
@code{NewGlobalRef()} to the method's underlying class; however, when 1.2 comes
along, it will use a weak reference to allow the class to be unloaded
and then re-resolve the @code{jmethodID} the next time it is used.

Cache classes that you need to access often.  jnilink will help with
this as well.  The issue here is the same as the methodID and fieldID
issue--how to make certain the class reference remains valid.

If you need to associate native C data with your class, use Paul
Fisher's native_state library (NSA).  It will allow you to get and set
state fairly efficiently.  Japhar now supports this library, making
native state get and set calls as fast as accessing a C variable
directly.

If you are using native libraries defined outside of Classpath, then
these should be wrapped by a Classpath function instead and defined
within a library of their own.  This makes porting Classpath's native
libraries to new platforms easier in the long run.  It would be nice
to be able to use Mozilla's NSPR or Apache's APR, as these libraries
are already ported to numerous systems and provide all the necessary
system functions as well.

@node Security,  , Native Efficiency, Programming Goals
@comment  node-name,  next,  previous,  up
@section Security

Security is such a huge topic it probably deserves its own chapter.
Most of the current code needs to be audited for security to ensure
all of the proper security checks are in place within the Java
platform, but also to verify that native code is reasonably secure and
avoids common pitfalls, buffer overflows, etc.  A good source for
information on secure programming is the excellent HOWTO by David
Wheeler,
@uref{http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html,Secure
Programming for Linux and Unix HOWTO}.

@node API Compatibility, Specification Sources, Programming Goals, Top
@comment  node-name,  next,  previous,  up
@chapter API Compatibility

@menu
* Serialization::               Serialization
* Deprecated Methods::          Deprecated methods
@end menu

@node Serialization, Deprecated Methods, API Compatibility, API Compatibility
@comment  node-name,  next,  previous,  up
@section Serialization

Sun has produced documentation concerning much of the information
needed to make Classpath serializable compatible with Sun
implementations.  Part of doing this is to make sure that every class
that is Serializable actually defines a field named serialVersionUID
with a value that matches the output of serialver on Sun's
implementation.  The reason for doing this is below.

If a class has a field (of any accessibility) named serialVersionUID
of type long, that is what serialver uses. Otherwise it computes a
value using some sort of hash function on the names of all method
signatures in the .class file.  The fact that different compilers
create different synthetic method signatures, such as access$0() if an
inner class needs access to a private member of an enclosing class,
make it impossible for two distinct compilers to reliably generate the
same serial #, because their .class files differ. However, once you
have a .class file, its serial # is unique, and the computation will
give the same result no matter what platform you execute on.

Serialization compatibility can be tested using tools provided with
@uref{http://www.kaffe.org/~stuart/japi/,Japitools}.  These
tools can test binary serialization compatibility and also provide
information about unknown serialized formats by writing these in XML
instead.  Japitools is also the primary means of checking API
compatibility for GNU Classpath with Sun's Java Platform.

@node Deprecated Methods,  , Serialization, API Compatibility
@comment  node-name,  next,  previous,  up
@section Deprecated Methods

Sun has a practice of creating ``alias'' methods, where a public or
protected method is deprecated in favor of a new one that has the same
function but a different name.  Sun's reasons for doing this vary; as
an example, the original name may contain a spelling error or it may
not follow Java naming conventions.

Unfortunately, this practice complicates class library code that calls
these aliased methods.  Library code must still call the deprecated
method so that old client code that overrides it continues to work.
But library code must also call the new version, because new code is
expected to override the new method.

The correct way to handle this (and the way Sun does it) may seem
counterintuitive because it means that new code is less efficient than
old code: the new method must call the deprecated method, and throughout
the library code calls to the old method must be replaced with calls to
the new one.

Take the example of a newly-written container laying out a component and
wanting to know its preferred size.  The Component class has a
deprecated preferredSize method and a new method, getPreferredSize. 
Assume that the container is laying out an old component that overrides
preferredSize and a new component that overrides getPreferredSize.  If
the container calls getPreferredSize and the default implementation of
getPreferredSize calls preferredSize, then the old component will have
its preferredSize method called and new code will have its
getPreferredSize method called.

Even using this calling scheme, an old component may still be laid out
improperly if it implements a method, getPreferredSize, that has the
same signature as the new Component.getPreferredSize.  But that is a
general problem -- adding new public or protected methods to a
widely-used class that calls those methods internally is risky, because
existing client code may have already declared methods with the same
signature.

The solution may still seem counterintuitive -- why not have the
deprecated method call the new method, then have the library always call
the old method?  One problem with that, using the preferred size example
again, is that new containers, which will use the non-deprecated
getPreferredSize, will not get the preferred size of old components.

@node Specification Sources, Naming Conventions, API Compatibility, Top
@comment node-name, next, previous, up
@chapter Specification Sources

There are a number of specification sources to use when working on
Classpath.  In general, the only place you'll find your classes
specified is in the JavaDoc documentation or possibly in the
corresponding white paper.  In the case of java.lang, java.io and
java.util, you should look at the Java Language Specification.

Here, however, is a list of specs, in order of canonicality:

@enumerate
@item
@uref{http://java.sun.com/docs/books/jls/clarify.html,Clarifications and Amendments to the JLS - 1.1}
@item
@uref{http://java.sun.com/docs/books/jls/html/1.1Update.html,JLS Updates
- 1.1}
@item
@uref{http://java.sun.com/docs/books/jls/html/index.html,The 1.0 JLS}
@item
@uref{http://java.sun.com/docs/books/vmspec/index.html,JVM spec - 1.1}
@item
@uref{http://java.sun.com/products/jdk/1.1/docs/guide/jni/spec/jniTOC.doc.html,JNI spec - 1.1}
@item
@uref{http://java.sun.com/products/jdk/1.1/docs/api/packages.html,Sun's javadoc - 1.1}
(since Sun's is the reference implementation, the javadoc is