                                             Release Notes
                             Compaq Fast Virtual Machine (Fast VM) 1.2.2-4
[COMPAQ]                               for the Java 2 Platform
                                           on Tru64 UNIX

  ------------------------------------------------------------------------

Contents

   * Introduction
   * New Features
        o Features of the Fast VM 1.2.2-4
        o Features of the Fast VM 1.2.2-2
   * Fixed Problems
        o Problems Fixed in the Fast VM 1.2.2-4
        o Problems Fixed in the Fast VM 1.2.2-2
   * Installing the Compaq Fast VM
        o Kit for Use with the Java 2 SDK
        o Kit for Use with the JRE
   * Using the Compaq Fast VM
        o Using the java Command to Invoke the Fast VM
        o Standard Options
        o Non-Standard Options
        o The JAVA_FAST_VM Environment Variable
        o Using the Fast VM for Applications Requiring a Large Virtual
          Address Space
        o Using the Fast VM with Java 2 Development Tools
        o Dynamic Heap Settings
        o Using the Fast VM with a Large Number of Threads
        o Memory Usage
        o Creating a Fast VM in C/C++ Programs Using the Invocation API
        o Restrictions
   * Including the Fast VM with the Redistributed JRE
        o Bundling and Redistributing the Fast VM
        o Invoking the Fast VM with the JRE
   * Problem Reporting

Introduction

Thank you for downloading the Compaq Fast Virtual Machine (Fast VM) 1.2.2-4
kit for the Java 2 Platform on Compaq Tru64 UNIX.

The Compaq Fast VM for Java 2 is new Just-In-Time (JIT) compiler technology
designed to provide optimal Java run-time performance on Tru64 UNIX
systems. The Fast VM for Java 2 offers significant performance advantages
over the Classic JIT provided with the Compaq Java 2 SDK (J2SDK).

An HTML version of these release notes is placed in the following directory
on the system where the Fast VM kit is installed:

/usr/opt/java122/docs/java-fast

The Fast VM 1.2.2 is provided with two different kits, one for use with
J2SDK v 1.2.2 and one for use with the Java 2 Runtime Environment,
Standard Edition (also known as the Java 2 Runtime or JRE) v 1.2.2. These
release notes are distributed with both kits.

IMPORTANT: Please make sure you understand the copyright (copyright.txt,
installed file), the license for J2SDK v 1.2.2 (license.txt, installed
file), and the license for JRE v 1.2.2 (jre_license.txt, installed file)
before using this release.

New Features

This kit installs the Fast VM, Version 1.2.2-4. The following sections
provide important information about new features in current and previous
releases of the Compaq Fast VM Version 1.2.2.

Features of the Fast VM 1.2.2-4

The Fast VM 1.2.2-4 includes the following new features from Compaq:

   * Garbage collection performance has been improved, particularly for
     large SMP (symmetrical multiprocessing) systems. Less time spent in
     garbage collection translates to higher performance for
     memory-intensive programs.

   * To increase performance for 32-bit applications that require a larger
     pool of memory, the Fast VM maximum heap size that can be set with the
     java -fast -Xmx option has been increased from 1 gigabyte to 3
     gigabytes.

   * The Compaq Fast VM garbage collection report output has been improved
     to generate a detailed set of statistics. Following is an example of
     the new report output when using the -verbose:gc option:

     <GC: Garbage Collection #10 with 64.00 MB Heap>
     <GC:   Time since last collection     :      10.12 seconds>
     <GC:   Time spent collecting          :       0.05 seconds>
     <GC:   Data live before collection:   :      45.92 MB>
     <GC:   Data live after collection     :      22.23 MB>
     <GC:   Data pinned during collection  :       0.12 MB>

     Following is an example of the report output that occurs at program
     termination:

     <GC: Garbage Collection Totals>
     <GC:   Number of collections          : 31>
     <GC:   Time spent collecting          : 1.09 seconds>
     <GC:   Total # of bytes allocated     : 907.50 MB>
     <GC:   Maximum heap size              : 64.00 MB>

Features of the Fast VM 1.2.2-2

The Fast VM 1.2.2-2 includes the following features from Compaq:

   * The Fast VM often provides application performance many times faster
     than the Classic JIT. The Fast VM generates efficient native Alpha
     code as methods are invoked and includes a Java execution environment
     highly tuned for the Alpha platform. The Fast VM provides improved
     memory management by means of a copying garbage collector. This
     garbage collection technique has proven to be faster than the more
     common "mark and sweep" style collector employed by the J2SDK v 1.2.2.
     Optimized thread synchronization, efficient object format and object
     allocation, and runtime optimizations also contribute to increased
     performance.

   * The Fast VM for Java 2 is compliant with the Java Compatibility Kit
     (JCK).

   * The Fast VM now supports a single integrated Java command. You invoke
     the Fast VM by typing, "java -fast".

Fixed Problems

This kit installs the Fast VM 1.2.2-4. The following sections provide
important information about problems fixed in current and previous releases
of the Compaq Fast VM Version 1.2.2.

Problems Fixed in the Fast VM 1.2.2-4

This Fast VM 1.2.2-4 kit includes the following improvements over the Fast
VM 1.2.2-2 release:

   * The Fast VM now calls a user specified printStackTrace method instead
     of the default java printStackTrace method.

   * The invocation API routine AttachCurrentThread now correctly updates
     the JNI environment pointer.

   * A problem with getting a "dataflow init failed" error message has been
     fixed.

   * Fast VM now properly handles fields that have an offset greater than
     32767 within an object instance or a classs static variable list.

   * A problem with getting a "cfg_find_block: offset out of range of a
     method" message has been fixed.

   * A problem with getting a segmentation violation during class loading
     has been fixed.

Problems Fixed in the Fast VM 1.2.2-2

The Fast VM 1.2.2-2 kit includes the following improvements over the Fast
VM 1.2.2-1 release:

   * The use of the Fast VM 1.2.2-1 with J2SDK v 1.2.2-6 resulted in a
     loader error due to two unresolved symbols. This problem has been
     fixed.

Installing the Compaq Fast VM

The Fast VM 1.2.2 is packaged and installed separately from the J2SDK v
1.2.2 and the Java 2 Runtime Environment, Standard Edition (also known as
the Java 2 Runtime or JRE) v 1.2.2 for Tru64 UNIX systems. Two Fast VM kits
are available; one for use with the Java 2 SDK and one for use with the JRE
v 1.2.2.

Installation instructions and usage information for both Fast VM 1.2.2 kits
are described in the sections that follow.

Kit for Use with the Java 2 SDK

This Fast VM kit requires the following be installed on your system:

  1. Java 2 SDK Version 1.2.2-6 or higher.
  2. DIGITAL UNIX V4.0D, V4.0E, or Tru64 UNIX V4.0F, V4.0G, or V5.0 and
     higher.

To install the Compaq Fast VM, perform the following steps as superuser:

  1. If you installed a previous version of the Fast VM (for example, a
     beta kit), use the setld command to delete that version:

       a. Use the setld -i command to determine if a previous version of
          Fast VM is installed:

           setld -i | grep JAVAFVM122 | grep installed

       b. To delete the old subset, enter the setld -d command. For
          example:

           setld -d JAVAFVM122

  2. Download and untar the following binary kit into a scratch directory:

     javafvm122-4.tar

     The following example assumes you downloaded a Fast VM kit to scratch
     directory /tmp/java:

     cd /tmp/java
     tar xf /tmp/java/javafvm122-4.tar

     The scratch directory now contains the kit and the following files:

     release_notes.txt - these release notes
     copyright.txt
     license.txt

  3. Use the setld command to install the kit from that directory:

     setld -l /tmp/java

Kit for Use with the JRE

This Fast VM kit requires the following to be installed on your system:

  1. Java Runtime Environment (JRE) Version 1.2.2-6 or higher.
  2. DIGITAL UNIX V4.0D, V4.0E, or Tru64 UNIX V4.0F, V4.0G, or V5.0 and
     higher.

This Fast VM kit is provided for developers who want to redistribute the
Fast VM and the JRE v 1.2.2 with their application. This kit installs the
Fast VM executables which are placed in the JRE v 1.2.2 directory tree,
subsequently making it easier to redistribute with your applications. For
additional information about redistributing the the Fast VM with the JRE v
1.2.2, see Bundling and Redistributing the Fast VM. To install the Fast VM
kit, perform the following steps as superuser:

  1. Determine whether a previous version of the Fast VM 1.2.2 is installed
     and use the setld command to delete it. For example:

       a. Use the setld -i command to determine if a previous version of
          the Fast VM 1.2.2 is installed:

          setld -i | grep JAVAJREFVM122 | grep installed

       b. To delete all of the old Fast VM subsets found, enter the setld
          -d command. For example:

          setld -d JAVAJREFVM122

  2. Download the Fast VM kit that is intended for use with the JRE v 1.2.2
     and untar the following binary file into a scratch directory. The
     scratch directory cannot be the same directory that contains the kit
     for use with the Java 2 SDK:

     javajrefvm122-4.tar

     The following example assumes you downloaded a Fast VM kit to scratch
     directory /tmp/jre:

     cd /tmp/jre
     tar xf /tmp/jre/javajrefvm122-4.tar

     The scratch directory now contains the kit and the following files:

     release_notes.txt - these release notes
     copyright.txt
     license.txt

  3. Use the setld command to install the kit from that directory:

     setld -l /tmp/jre

Using the Compaq Fast VM

Before using the Fast VM, you need to insure that J2SDK v 1.2.2 is
installed and is your current version of Java. To verify your current
version of Java, use the java -version command option. If J2SDK v 1.2.2 is
your current version, you will see the following message:

% java -version
java version "1.2.2-n"

where n identifies the specific J2SDK v 1.2.2 that is installed. If J2SDK v
1.2.2 is installed but is not your current version, you need to place the
directory /usr/opt/java122/bin first in your PATH. This is the directory
that contains the J2SDK v 1.2.2 executables. For example, using csh(1):

setenv PATH /usr/opt/java122/bin:$PATH

For additional information about defining your PATH and using multiple Java
kit versions, please refer to the Compaq J2SDK v 1.2.2 Release Notes. To
make J2SDK v 1.2.2 your default Java, see Making J2SDK v 1.2.2 the Default
Java in the Compaq J2SDK v 1.2.2 Release Notes. After downloading and
installing the Fast VM kit and setting up J2SDK v 1.2.2-6 (or higher) as
your current version of Java, the java -fast -version command displays the
following:

% java -fast -version
java version "1.2.2-4"
Fast VM...

Using the java Command to Invoke the Fast VM

You invoke the Fast VM with the java -fast command as follows:

java -fast
Usage: java -fast [-options] classname [args]

Any arguments that appear after classname on the command line are passed to
the main method of the class.

Standard Options

The java -fast command supports the following standard options:

                        Standard Options

     Option                         Function

                  Specify a list of directories, JAR archives,
                  and ZIP archives to search for user class
                  files. Class path entries are separated by
 -classpath       colons (:). Specifying -classpath or -cp
 classpath        overrides any setting of the CLASSPATH
 -cp classpath    environment variable.
                  If -classpath and -cp are not used and
                  CLASSPATH is not set, the user class path
                  consists of the current directory (.).

 -Dproperty=value Set a system property value.

 -help            Display usage information and exit.

                  Execute a program encapsulated in a JAR
                  file. The first argument is the name of a
                  JAR file instead of a startup class name. In
                  order for this option to work, the manifest
                  of the JAR file must contain a line of the
                  form Main-Class: classname.

 -jar             Here, classname identifies the class having
                  the public static void main(String[] args)
                  method that serves as your application's
                  starting point.

                  When you use this option, the JAR file is
                  the source of all user classes, and other
                  user class path settings are ignored.

 -verbose
 -verbose:class   Display information about each class loaded.

 -verbose:gc      Report on each garbage collection event.

                  Report information about use of native
 -verbose:jni     methods and other Java Native Interface
                  activity (JNI). (This option can be
                  specified but it has no effect.)

 -version         Display version information and exit.

 -X               Display usage information for non-standard
                  options and exit.

Non-Standard Options

This version of the Compaq Fast VM for the Java 2 Platform also includes
support for the following java -fast non-standard options.

                    Non-Standard Options

           Option                       Function

 -taso                       Load the executable in 31-bit
                             addressable address range.

                             Specify a colon-separated
                             list of directories, JAR
                             archives, and ZIP archives to
 -Xbootclass:<bootclasspath> search for boot class files.
                             These are used in place of
                             the boot class files included
                             in the J2SDK v 1.2 software.

                             Specify the initial size of
                             the memory allocation pool.
                             This value must be greater
                             than 1000. To multiply the
 -Xms<size>                  value by 1000, append the
                             letter k. To multiply the
                             value by 1 million, append
                             the letter m. See Dynamic
                             Heap Settings for information
                             about the default value.

                             Specify the maximum size of
                             the memory allocation pool.
                             This value must be greater
                             than 1000. To multiply the
 -Xmx<size>                  value by 1000, append the
                             letter k. To multiply the
                             value by 1 million, append
                             the letter m. See Dynamic
                             Heap Settings for information
                             about the default value.

 -Xss<number>                Set the maximum stack size
                             for any thread.

 -XO                         Do not generate stack trace
                             information for exceptions.

If the Fast VM is not installed, the use of the java -fast command results
in an error message indicating that -fast is an illegal argument.

The JAVA_FAST_VM Environment Variable

Starting with Java 2 SDK v 1.2.2-7, you can also use the Fast VM by
defining the environment variable JAVA_FAST_VM. If this environment
variable is defined, the Fast VM is always used when the java command is
invoked even if -fast is not specified, and the Java 2 SDK tools always use
the Fast VM.

The environment variable JAVA_FAST_VM has no effect if J2SDK v 1.2.2-6 or
earlier is installed or if the Fast VM is not installed.

Using the Fast VM for Applications Requiring a Large Virtual Address Space

By default, the Fast VM uses 32-bits to store pointers in objects, which
limits the amount of virtual memory available to Java applications. With
the default, the memory allocation pool (Java heap) is limited to about 3
gigabytes. The Fast VM provides an option to use 64-bits for pointers,
which significantly increases the amount of memory available to Java
applications. To use the 64-bit option, specify java -fast64 rather than
java -fast.

Using the Fast VM with Java 2 Development Tools

The Fast VM can also be used with the J2SDK v 1.2.2 development tools (for
example, javac, javadoc, javap, jar, appletviewer, and so on.) by
specifying the -fast option when you invoke the tool. For example, the
following command uses the Fast VM when running the appletviewer:

appletviewer -fast runtest.html

(For applications requiring Java heap sizes larger than 3 GB, consider
using the -fast64 option.)

Dynamic Heap Settings

Rather than use fixed values for the default settings for the memory
allocation pool (Java heap), the Compaq Fast VM determines the defaults for
the initial heap size (-Xms) and the maximum heap size (-Xmx) dynamically
based on the environment in which it is executing as shown below:

max_memory = min ( physical memory on machine, total memory available to the
process)

default initial heap size = 10% of max_memory

default maximum heap size = 60% of max_memory

By setting heap size defaults automatically, the Fast VM adjusts the heap
size based on the amount of memory that is available. This generally
produces better results than specifying fixed -Xmx and -Xms values,
especially for an application that is executed on different systems with
varying amounts of memory. It is sometimes possible to obtain better
results by specifying -Xmx and -Xms rather than letting the Fast VM pick
the defaults. To determine what values to use you should use the -verbosegc
command line option to monitor your application's heap activity. If you
notice that a large number of garbage collections are occurring, increase
the heap size as much as possible without causing excessive page faults.
Also see Memory Usage for additional information.

Using the Fast VM with a Large Number of Threads

If you experience a "java.lang.OutOfMemoryError" when attempting to create
a large number of threads, consider increasing the proc subsystem
attribute, max_threads_per_user. This attribute allows you to increase the
maximum number of threads that can be allocated at any one time to each
user, except superuser.

The Compaq Tru64 UNIX Best Practice guide recommends the following:

"The default value of the max_threads_per_user attribute is based on the
value of the maxusers attribute, so you can increase the maximum number of
threads by increasing the maxusers attribute. You can also explicitly
increase the maximum number of threads by increasing the
max_threads_per_user attribute.

Use a value that is equal to or greater than the maximum number of threads
that are allocated at one time on the system. For example, you could
increase the value of the max_threads_per_user attribute to 512. On a busy
server with sufficient memory or an Internet server, increase the value of
the max_threads_per_user attribute to 4096. If the value of the
max_threads_per_user attribute is 0 (zero), there is no limit on threads;
this is not recommended."

You must reboot the system to use the new value of max_threads_per_user.

Memory Usage

The Fast VM has been tuned for large memory systems and, in addition, a
number of tradeoffs have been made that favor speed of execution over
memory usage. As a result, the Fast VM uses more physical and virtual
memory for the same application, often as much as 50% more. This can lead
to excessive paging and degraded performance if the system is not tuned
correctly or if there is insufficient physical memory on the system. If you
notice that your application runs more slowly with the Fast VM than the
classic Java 2 SDK JIT, you should do the following:

   * Experiment with explicit -Xmx and -Xms values rather than letting the
     Fast VM pick the defaults. (See Dynamic Heap Settings.)
   * Increase process quotas based on the amount of available physical
     memory
   * Add physical memory

Note that you are better off with a smaller heap that results in more
garbage collections than allowing your application to page fault too often
due to a large heap size. For more information on system tuning and
resource limits, see the following:

   * Tru64 UNIX System Configuration and Tuning, specifically the section,
     Increasing Address Space
   * C shell commands limit and unlimit, specifically addressspace
   * manpages setrlimit(2) and getrlimit(2)

Creating a Fast VM in C/C++ Programs Using the Invocation API

This release of the Compaq Fast VM supports the ability to create and
invoke the Fast VM in C/C++ programs using the Invocation API. The
Invocation API is an integral part of the Java Native Interface (JNI) that
allows you to initialize virtual machine arguments, create and load a
virtual machine into your application, and then unload or destroy the
virtual machine. For additional information about the Invocation API and
how to use it, refer to the Sun JNI specification.

In order to take advantage of the Invocation API functionality, your C/C++
program (new and existing programs) must first create the virtual machine
so that the Java code can be executed. Once the virtual machine is embedded
into the program, the program can then load Java classes and execute Java
methods. Let us assume that you have a C++ program called invokejvm.cxx.
This program creates a virtual machine and then calls a Java method. The
following is an example of a C++ command line that compiles and links a C++
program that invokes the Fast VM:

cxx -pthread \
  -I/usr/opt/java122/include \
  -I/usr/opt/java122/include/alpha \
    invokejvm.cxx \
    /usr/opt/java122/jre/lib/alpha/fast64/libjvm.so \
  -o invokejvm

Before running the resulting invokejvm, you must define LD_LIBRARY_PATH so
that the following shared library directories are searched when loading the
executable:

/usr/opt/java122/jre/lib/alpha/
/usr/opt/java122/jre/lib/alpha/fast64
/usr/opt/java122/jre/lib/alpha/native_threads

For example, you can do this using the following csh commands:

setenv JLIB /usr/opt/java122/jre/lib/alpha
setenv LD_LIBRARY_PATH ${JLIB}:${JLIB}/fast64:${JLIB}/native_threads

If your C or C++ main program is built with the -xtaso or -xtaso_short
option to use 32-bit pointers, you should substitute fast32 for fast64 in
the above cxx command line and LD_LIBRARY_PATH definition.

Restrictions

Native methods used with the Fast VM for Java 2 must conform to the Java
Native Interface (JNI) specification. The Fast VM does not support native
method conventions older than the JNI specification.

Bundling and Redistributing the Fast VM

The Java Runtime Environment (JRE) Version 1.2.2 can be downloaded by
end-users but primarily is used by application developers who want to
redistribute the JRE v 1.2.2 with their software. This allows developers to
distribute Java software without requiring end-users to download and
install the Java 2 SDK or Java 2 Runtime Environment. In addition, it
ensures execution using the same version that was tested by the developer.
(See the JRE v 1.2.2 Readme for additional information about the JRE v
1.2.2.) Similarly, the Fast VM for use with the JRE v 1.2.2 is intended for
developers who want to redistribute the Java 2 Runtime Environment and also
want to redistribute the Fast VM for higher performance. To redistribute
the Fast VM, you need to take the following steps:

  1. Download the Fast VM kit for use with the JRE v 1.2.2. You can do this
     by visiting our software download page and selecting the Fast VM
     1.2.2. This page allows you to download the kit for use with the Java
     2 SDK or the kit for use with the JRE v 1.2.2. Download the kit for
     use with the JRE v 1.2.2.

  2. Install the Fast VM kit for use with the JRE v 1.2.2. See Kit for Use
     with the JRE.

  3. See Invoking the Fast VM with the JRE for information about command
     options.

  4. Follow the instructions below for including the Fast VM with the
     redistributed JRE v 1.2.2.

Invoking the Fast VM with the JRE

After installing the Fast VM kit for use with the JRE v 1.2.2, you invoke
the Fast VM as follows:

/usr/opt/jre122/bin/java -fast

This command supports the same arguments and options as described in Using
the java Comand To Invoke the Fast VM.

Including the Fast VM with the Redistributed JRE

The Fast VM depends on the JRE v 1.2.2, and you need to redistribute all
required JRE v 1.2.2 files and any optional JRE v 1.2.2 files that your
application needs along with the Fast VM. For instructions on installing,
bundling, and redistributing the JRE v 1.2.2, see the JRE v 1.2.2 Readme.
When the Fast VM for use with the JRE v 1.2.2 is installed, the files are
placed in the JRE v 1.2.2 directory tree (/usr/opt/jre122). Thus, if you
include the entire JRE v 1.2.2 directory tree with your application, you
will have all the files needed to run the Fast VM. The recommended
procedure is as follows:

   * Install the JRE v 1.2.2 mandatory subset.
   * Install the JRE v 1.2.2 optional subset if any of the optional files
     are needed.
   * Delete any optional files in the /usr/opt/jre122 directory tree that
     are not needed.
   * Install the Fast VM 1.2.2 kit for use with the JRE v 1.2.2.
   * Create a /jre subdirectory in your application directory tree and copy
     the entire /bin and /lib subdirectories from /usr/opt/jre122 to this
     area.

Assume that you copy the JRE v 1.2.2 directory tree to the following
directory in your application: /myapp/myjre. You then invoke the Fast VM
using the following command:

/myapp/myjre/bin/java -fast

Problem Reporting

Compaq delivers the JDK and Java 2 SDK as part of the Tru64 UNIX operating
system and for use with it. The Fast VM is licensed to customers and
supported on the same basis. Customers with support contracts should seek
support through local customer support centers for problems encountered in
using the Fast VM.

Customers who do not have support contracts are encouraged to continue to
mail problem reports, using the bugreport.txt problem report template
included in this kit or on our web site to java-bugs@zko.dec.com. These
reports will certainly be used as a source of input for fixing problems for
new releases. However, we will only be able to give these reports
individual attention and take remedial action on a best-effort basis.

If you have questions not addressed by our FAQs, suggestions, or comments,
please send mail to java-info@zko.dec.com.

For updates to the Fast VM as new revisions become available, you can look
at our Compaq Java for Alpha Systems web site.

  ------------------------------------------------------------------------
Copyright 2000 Compaq Computer Corporation.
Compaq Registered in U.S. Patent and Trademark Office.
Java and all Java-based marks are trademarks or registered trademarks of
Sun Microsystems, Inc.
All other product names mentioned herein may be trademarks or registered
trademarks of their respective companies.
Compaq shall not be liable for technical or editorial errors or omissions
contained herein. The information in this document is subject to change
without notice.
