                            Release Notes
               Compaq Fast Virtual Machine (Fast VM) 1.1.8-2
                           for Tru64(TM) UNIX(R)

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

Contents

   * Introduction
   * New Features
        o Features of the Fast VM 1.1.8-2
        o Features of the Fast VM 1.1.8-1
   * Fixed Problems
        o Problems Fixed in 1.1.8-2
        o Problems Fixed in 1.1.8-1
   * Installing the Fast VM Kit
        o Kit for Use with the JDK
        o Kit for Use with the JRE
   * Using the Compaq Fast VM with the JDK
        o The java -fast Command
             + Command Options Supported by the Fast VM
        o The JAVA_FAST_VM Environment Variable
        o Comparing the Fast VM and the JDK Java Commands
        o Using the Fast VM with a Large Number of Threads
        o Controlling Heap Size
        o Creating a Fast VM in C/C++ Programs Using the Invocation API
   * Bundling and Redistributing the Fast VM
        o Invoking the Fast VM with the jre Command
        o Including the Fast VM with the Redistributed JRE
   * Problem Reporting

Introduction

Thank you for downloading the Compaq Fast Virtual Machine (Fast 
VM) 1.1.8-2 for Compaq(R) Tru64(TM) UNIX(R) (formerly DIGITAL 
UNIX). These release notes contain known issues, new features, 
and other information specific to the Fast VM for Tru64 UNIX.

The Fast VM is new Just-In-Time (JIT) compiler technology 
designed to provide the best Java(TM) run-time performance on 
Tru64 UNIX systems, offering significant performance advantages 
over the standard JIT provided with the Compaq Java(TM) 
Development Kit (JDK) version 1.1.8.

For more information about the Fast VM, see Comparing the Fast VM 
and the JDK Java Commands. Additionally, an HTML version of these 
release notes is placed in the following directory on the system 
where the Fast VM kit was installed:

/usr/opt/java118/docs/java-fast

The Fast VM Version 1.1.8-2 is provided with two different kits, 
one for use with JDK V1.1.8 and one for use with the Java(TM) 
Runtime Environment (also known as the Java Runtime or JRE) 
version 1.1.8. These release notes are distributed with both 
kits.

IMPORTANT: Please make sure you understand the Copyright 
(copyright.txt, installed file), the license for JDK version 
1.1.8 (license.txt, installed file), and the license for JRE 
version 1.1.8 (jre_license.txt, installed file) before using this 
release.

New Features

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

Features of the Fast VM 1.1.8-2 Release

The Fast VM 1.1.8-2 release includes the following new features 
from Compaq:

   * The Compaq Fast VM now supports the Java Native Interface 
     Invocation API, which allows you to invoke the Fast VM from a 
     C or C++ main program. This results in fast execution of your 
     Java code in C/C++ applications which formerly could not embed 
     the Fast VM. For additional information, refer to the section 
     Creating a Fast VM in C/C++ Programs Using the Invocation API 
     that appears later in these release notes.

   * The Fast VM now supports the Java Runtime Environment (JRE) 
     -cp command option. The -cp option allows you to prepend 
     directories to the base class path and is recommended when 
     using the Fast VM with the JRE. For more information about 
     Fast VM options, see Command Options Supported by the Fast VM.

Features of the Fast VM 1.1.8-1 Release

The Fast VM 1.1.8-1 release includes the following new features from
Compaq:

   * This release provides better packing of class fields on 
     Tru64 UNIX systems. The allocation of non-static class fields 
     has been changed in this release to improve the memory usage 
     of the virtual machine at runtime. This change does not have 
     any affect on class files. The improved memory usage is 
     limited to the in-memory classes once they have been loaded 
     into the virtual machine. This change in field allocation will 
     be transparent to most users. However, please see the JDK 
     V1.1.8 Release Notes Compatibility section when your 
     application uses native methods.

   * The Fast VM now supports the -verbosegc option. This option 
     allows you to monitor your application's heap activity. For 
     information about Fast VM options, see Command Options 
     Supported by the Fast VM. For additional information about 
     controlling heap size and memory usage, see Comparing the Fast 
     VM and the JDK Java Commands.

Fixed Problems

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

Problems Fixed in 1.1.8-2

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

   * Occasionally the JNI routines Method and CallNonvirtual 
     Method would call an incorrect Java method. This problem has 
     been fixed.

   * The Fast VM has been fixed to allow C/C++ routines to catch 
     Java exceptions (thrown by Java code) using the JNI routines, 
     ExceptionOccurred and ExceptionDescribe.

   * The Fast VM was incorrectly handling global references to 
     class objects. This problem has been fixed.

   * The Fast VM was producing incorrect results for integer 
     divide by 2 of large numbers (long type). This problem has 
     been fixed.

Problems Fixed in 1.1.8-1

The 1.1.8-1 kit includes the following improvements over the Fast 
VM 1.1.7B-2 release:

   * Several bugs have been fixed related to searching thread 
     stacks for live references to objects in the Java heap during 
     garbage collection. In some cases, a reference would not be 
     detected, resulting in incorrect collection of an object. 
     There were also cases where the Fast VM might either hang or 
     die with a segmentation fault during this stack search. These 
     problems have been fixed.

   * The Fast VM was incorrectly invoking a virtual method 
     defined with default access in another package. This could 
     result in the wrong member function being called. This problem 
     has been fixed.

   * The Fast VM was not using virtual method call semantics when 
     invoking a function using reflection. This could result in the 
     wrong member function being called. This problem has been 
     fixed.

   * The Fast VM was prematurely releasing some resources during 
     normal rundown that one or more daemon threads may still be 
     trying to access. Although this rarely would cause a problem, 
     it could result in various internal errors. This problem has 
     been fixed.

   * The Fast VM was not using the correct element size when 
     using reflection to access arrays of primitive types smaller 
     than "int". The could give incorrect results and also might 
     corrupt objects in the heap. This problem has been fixed.

Installing the Fast VM Kit

The Fast VM for version 1.1.8 is packaged and installed 
separately from the JDK V1.1.8 and the JRE V1.1.8 for Tru64 UNIX 
systems. Two Fast VM kits are available; one for use with the JDK 
and one for use with the JRE. Installation instructions for both 
kits follow.

Kit for Use with the JDK

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

  1. JDK V1.1.8-2 (13-Sep-99) or a more recent JDK V1.1.8 Update

  2. DIGITAL UNIX V4.0D, V4.0E, or Tru64 UNIX Version 4.0F and 
     higher

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

  1. Determine whether a previous version of the Fast VM 1.1.8 
     (for example, a beta version) 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.1.8 is installed:

          setld -i | grep JAVAFVM118 | grep installed

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

          setld -d JAVAFVM118

  2. Download the Fast VM kit that is intended for use with the 
     JDK and untar the following binary file into a scratch 
     directory:

     javafvm118-2.tar

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

     cd /tmp/java
     tar xf /tmp/java/javafvm118-2.tar

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

     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

Because Fast VM depends on the prior installation of JDK 
V1.1.8-2, any attempt to deinstall the JDK V1.1.8 mandatory 
subset after installing the Fast VM results in the following 
setld warning:

   The following subsets need "Java 1.1.8-n Environment " 
   (OSFJAVAnnn) to operate correctly:

       Java Fast VM 1.1.8-2 for use with the JDK 1.1.8 (JAVAFVM118)

   Are you sure you wish to delete "Java 1.1.8-n Environment "
   (OSFJAVAnnn)? (y/n)

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.1.8-2 (14-Sep-1999) 
     or a more recent JRE 1.1.8 Update

  2. DIGITAL UNIX V4.0D, V4.0E, or Tru64 UNIX Version 4.0F and higher

This Fast VM kit is provided for developers who want to 
redistribute the Fast VM and the JRE with their application. This 
kit installs the Fast VM executables which are placed in the JRE 
1.1.8 directory tree, subsequently making it easier to 
redistribute with your applications. For additional information 
about redistributing the the Fast VM with the JRE, 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.1.8 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.1.8 is installed:

          setld -i | grep JAVAJREFVM118 | grep installed

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

          setld -d JAVAJREFVM118

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

     javajrefvm118-2.tar

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

     cd /tmp/jre
     tar xf /tmp/jre/javajrefvm118-2.tar

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

     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 with the JDK

If JDK version 1.1.8 is installed but is not your current 
version, you need to place the directory /usr/opt/java118/bin 
first in your PATH. This is the directory that contains the JDK 
V1.1.8 executables. For example, using csh(1):

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

For additional information about defining your PATH and using 
multiple Java kit versions, please refer to the Compaq JDK V1.1.8 
Release Notes.

To make JDK version 1.1.8 your default Java, see Making JDK 
V1.1.8 the Default Java in the Compaq JDK V1.1.8 Release Notes.

After downloading and installing the Fast VM kit and setting up 
JDK V1.1.8 as your current version of Java, the java -fast 
-version command displays the following:

% java -fast -version
Fast VM version "1.1.8-2"

The java -fast Command

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.

Command Options Supported by the Fast VM

The java -fast command supports most of the same options as the 
java command as noted in the following table:

             Option                         Function

 -classpath <directories         list directories in which to
 separated by colons>            look for classes

 -cp <directories separated by   prepend directories to base
 colons>                         class path

 -D<name>=<value>                set a system property

 -fullversion                    print out detailed version
                                 information

 -help                           print out this message

 -ms<number>                     set the initial Java heap
                                 size; default is 16mb

 -mx<number>                     set the maximum Java heap
                                 size; default is 128mb

 -noverify                       do not verify any class

 -ss<number>                     set the maximum native stack
                                 size for any thread

 -taso                           load executable in 31-bit
                                 addressable address range

 -v -verbose                     turn on verbose mode

 -verbosegc                      print a message when garbage
                                 collection occurs

 -verify                         verify all classes when read
                                 in

 -verifyremote                   verify classes read in over
                                 the network [default]

 -version                        print out the build version

 -XO                             suppress stack trace
                                 information

The -cp option is the same as the JRE -cp option. The other 
options are the same as the corresponding JDK java options except 
that the default values for the Java heap size options (-ms and 
-mx) are different. See Comparing the Fast VM and the JDK Java 
Commands for additional information.

The following java command options are accepted by the java -fast 
command for compatibility with the JDK java command, but have no 
effect:

       Option                       Function

 -cs, -checksource  check if source is newer when loading
                    classes

 -debug             enable remote JAVA debugging

 -jit               use the just-in-time compiler

 -noasyncgc         do not allow asynchronous garbage
                    collection

 -noclassgc         disable class garbage collection

 -nojit             use the interpreter

 -oss<number>       set the maximum Java stack size for
                    any thread

 -prof[:<file>]     output profiling data to ./java.prof
                    or ./<file>

The Fast VM can also be used with the JDK tools that are written 
in Java (for example, javac, javadoc, javap, jar, appletviewer, 
and so on) by using the -J-fast option with the tool. For 
example, the following command uses the Fast VM when running the 
appletviewer:

appletviewer -J-fast runtest.html

Alternatively, this can also be accomplished with the following command:

java -fast sun.applet.AppletViewer runtest.html

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

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 JDK tools always use the Fast VM.

If the Fast VM is not installed, the environment variable 
JAVA_FAST_VM has no effect.

Comparing the Fast VM and the JDK Java Commands

The Fast VM incorporates new JIT technology to provide 
significant performance advantages over the JDK java command. The 
Fast VM is an Alpha-specific, enhanced Just-In-Time compiler that 
uses the JDK version 1.1.8 class files and native methods. The 
Fast VM is compliant with the Java Compatibility Kit (JCK).

The most significant difference between the Fast VM and the JDK 
java command is performance. The Fast VM and the associated JIT 
technology were developed to provide superior Java performance on 
Alpha systems running Tru64 UNIX. In addition, 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 JDK V1.1.8. A variety of advanced techniques have 
been used in the development of this garbage collector to 
minimize "pause time" due to garbage collection.

In addition to being fully Java compatible, the Fast VM is 
designed to mimic the behavior of the JDK java command to assure 
that programs behave the same regardless of which virtual machine 
is used to run them. However, there are a small number of 
implementation differences between the two that could affect some 
applications:

   * Both the JDK java command and the Fast VM memory allocator use mmap()
     system calls to obtain memory for the Java heap. Once the initial heap
     has been mapped, both expect subsequent calls to mmap() to return a
     region that is contiguous with the prior allocation. For both, it is
     essential that native methods that use mmap() do not map in the same
     region used for the Java heap. The JDK and the Fast VM map memory at
     different addresses. The Fast VM begins mapping at 0x40000000 and
     grows upward from that address. See the JDK V1.1.8 release notes for
     information on how the JDK java ommand maps memory. Refer to the
     manpages for additional information about how mmap() functions.

   * The Fast VM uses larger default values for the -ms and -mx 
     options:


                 -ms   -mx

      Compaq
      JDK        4m   16m

      Fast VM    16m  128m

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 
system (that is, kernel) parameter vm-vpagemax. A recommended 
setting is the number of 8kb pages used in the program's virtual 
address space. For example, for a 1Gbyte virtual address space, 
vm-vpagemax should be set to 128000.

This parameter is described in the Tru64 UNIX System 
Configuration and Tuning manual. Refer to the section on Tuning 
Virtual Memory Limits. Relevant tools are briefly described by 
man sysconfig and man sysconfigdb. To change the vm-vpagemax 
parameter, use the /sbin/sysconfigdb command to update a section 
of /etc/sysconfigtab. For example, to modify vm-vpagemax to be 
128000, the input file to the /sbin/sysconfigdb command 
(specified using the -f option) would contain the following:

vm:
vm-pagemax = 128000

The default value for vm-vpagemax is 16384. Use the following 
command to determine the value of vm-vpagemax on a running 
system:

% > sysconfig -q vm vm-vpagemax
vm:
vm-vpagemax = 16384

Controlling Heap Size

The Fast VM has been tuned for large memory systems. 
Specifically, the Fast VM will tend to rapidly grow the heap to 
the -mx value (default is 128M). The correct -mx value depends 
heavily on your application's memory needs, your process quotas, 
and the physical memory available on the target machine. You 
should use the -verbosegc command line option 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. However, if your application is 
page faulting excessively you should do the following:

   * Lower the -mx value

   * 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 the Available 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

A new feature included with this release of the Compaq Fast VM is 
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 at: 
http://java.sun.com/products/jdk/1.1/docs/guide/jni/spec/invocati
on.doc.html.

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. To create the Java-enabled executable, invokejvm, you 
must first link to the following two shared object libraries:

   * /usr/opt/java118/lib/alpha/native_threads/libjava-fast.so
   * /usr/opt/java118/lib/alpha/native_threads/libjava.so

Please note that to invoke the Fast VM, the shared object file 
libjava-fast.so must be listed before libjava.so in the C++ 
command line.

Following is an example of a C++ command line that compiles and 
links a C++ program that invokes the Fast VM:

cxx -o invokejvm -pthread -I/usr/opt/java118/include -I/usr/opt/java118/include/alpha \
   /usr/opt/java118/lib/alpha/native_threads/libjava-fast.so \
   /usr/opt/java118/lib/alpha/native_threads/libjava.so      invokejvm.cxx

Before invoking the resulting invokejvm image, you must define 
LD_LIBRARY_PATH to be /usr/opt/java118/lib/alpha/native_threads 
by specifying the following:

setenv LD_LIBRARY_PATH /usr/opt/java118/lib/alpha/native_threads

To support this feature, the Compaq Fast VM 1.1.8 kit now 
contains two new shared object library files:

   * libjava-fast.so
   * libjava-fast_g.so

Bundling and Redistributing the Fast VM

The Java Runtime Environment (JRE) can be downloaded by end-users 
but primarily is used by application developers who want to 
redistribute the JRE with their software. This allows developers 
to distribute Java software without requiring end-users to 
download and install the JDK or JRE. In addition, it ensures 
execution using the same version that was tested by the 
developer. (See the JRE 1.1.8 Readme for additional information 
about the JRE.)

Similarly, the Fast VM for use with the JRE is intended for 
developers who want to redistribute the JRE 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. You can do this by
     visiting our download page and selecting the Fast VM 1.1.8. This page
     allows you to download the kit for use with JDK or the kit for use
     with the JRE. Download the kit for use with the JRE.

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

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

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

Invoking the Fast VM with the jre Command

After installing the Fast VM kit for use with the JRE, you invoke 
the Fast VM with the jre -fast command as follows:

/usr/opt/jre118/bin/jre -fast
Usage: /usr/opt/jre118/bin/jre -fast [-options] classname [args]

This command supports the same options as java -fast. See Command 
Options Supported by the Fast VM. Any arguments that appear after 
classname on the command line are passed to the main method of 
the class.

Including the Fast VM with the Redistributed JRE

The Fast VM depends on the JRE 1.1.8, and you need to 
redistribute all required JRE files and any optional JRE files 
that your application needs along with the Fast VM. For 
instructions on installing, bundling, and redistributing the JRE, 
see the JRE 1.1.8 Readme.

When the Fast VM for use with the JRE is installed, the files are 
placed in the JRE 1.1.8 directory tree (/usr/opt/jre118). Thus, 
if you include the entire JRE 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 1.1.8 mandatory subset.

   * Install the JRE 1.1.8 optional subset if any of the optional 
     files are needed.

   * Delete any optional files in the /usr/opt/jre118 directory 
     tree that are not needed.

   * Install the Fast VM 1.1.8 kit for use with the JRE.

   * Create a /jre subdirectory in your application directory 
     tree and copy the entire /bin and /lib subdirectories from 
     /usr/opt/jre118 to this area.

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

/myapp/myjre/bin/jre -fast

See Invoking the Fast VM with the jre Command.

Problem Reporting

Compaq delivers the JDK and 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 the kit or on our web site at 
http://www.digital.com/java/contact/bugreport.txt, 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 Extreme Java Technology web site. Select 'Java 
for Compaq Alpha Systems'.

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

Copyright 2000 Compaq Computer Corporation. All rights reserved.

Java and all Java-based marks are trademarks or registered 
trademarks of Sun Microsystems, Inc. in the U.S. and other 
countries.