                             Release Notes
              Compaq Fast Virtual Machine (Fast VM) 1.1.7B-4
                         for Tru64(TM) UNIX(R)

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

Contents

   * Introduction
   * New Features
        o Features of the Fast VM 1.1.7B-4
        o Features of the Fast VM 1.1.7B-3
   * Fixed Problems
        o Problems Fixed in 1.1.7B-4
        o Problems Fixed in 1.1.7B-3
   * The Fast VM Kit
   * Installing the Kit
   * 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
   * Problem Reporting

Introduction

Thank you for downloading the Fast Virtual Machine (Fast VM) 
1.1.7B-4 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 JIT 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 JDK 1.1.7B.

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/share/doclib/java/java-fast

IMPORTANT: Please make sure you understand the Copyright 
(copyright.txt installed file) and License (license.txt installed 
file) information before using this release.

New Features

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

Features of the Fast VM 1.1.7B-4 Release

The Fast VM 1.1.7B-4 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.

Features of the Fast VM 1.1.7B-3 Release

The Fast VM 1.1.7B-3 release includes the following new features 
from Compaq:

   * The java -fast command now supports the -verbosegc option. 
     This option allows you to monitor your application's heap 
     activity. For information about Fast VM options, see Using the 
     Compaq Fast VM with the JDK. 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.7B-4.The following 
sections provide important information about problems fixed in 
current and previous releases of the Compaq Fast VM Version 
1.1.7B.

Problems Fixed in 1.1.7B-4

The 1.1.7B-4 kit includes the following improvements over the 
Fast VM 1.1.7B-3 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.7B-3

The 1.1.7B-3 kit includes the following improvements over the 
original Fast VM 1.1.7B 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.

The Fast VM Kit

The Fast VM for 1.1.7B is packaged and installed separately from 
the JDK 1.1.7B for Tru64 UNIX systems, but requires the prior 
installation of JDK 1.1.7B. The Fast VM can be installed and used 
on a system along with the Compaq JDK 1.1.7B. The kit installs 
the Fast VM and modifies the JDK java command to support the new 
java -fast option.

This Fast VM kit is intended for use with JDK 1.1.7B only, and 
requires DIGITAL UNIX V4.0D and V4.0E, and Tru64 UNIX Version 
4.0F and higher. The Compaq Fast VM 1.1.8 kit works with either 
the JDK 1.1.8 or JRE 1.1.8.

Installing the Kit

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

  1. If you installed a prior version of the Fast VM, use the 
     setld command to delete it.

       a. Use the setld -i command to determine if prior versions 
          of the Fast VM are installed:

          setld -i | grep JAVAJIT116 | grep installed
          setld -i | grep JAVAFVM117B | grep installed

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

          setld -d JAVAJIT116 JAVAFVM117B

  2. Untar one of the following binary kits into a scratch 
     directory:

     javafvm117B-4_v40d.tar  (V4.0D)
     javafvm117B-4_v40e.tar  (V4.0E)
     javafvm117B-4_v40f.tar  (V4.0F)
     javafvm117B-4_v50.tar   (V5.0)

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

     cd /tmp/java
     tar xf /tmp/java/javafvm117B-4_v40d.tar

     The scratch directory now contains the kit plus 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

After downloading and installing the Fast VM kit, the java -fast 
-version command displays the following:

% java -fast -version
Fast VM version "1.1.7B-4"

The installation of the Fast VM modifies the java command to 
support the -fast option and the JAVA_FAST_VM environment 
variable. This has the following consequences:

   * If you try to deinstall the 1.1.7B mandatory subset after 
     installing the Fast VM, setld gives the following warning:

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

         Fast VM 1.1.7B-4 (JAVAFVM117B)

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

     If you reply yes, you will no longer be able to use the java -fast
     command to invoke the Fast VM.

   * If you deinstall any of the 1.1.7B subsets and then later 
     reinstall them, you also need to deinstall the Fast VM and 
     then reinstall it using the directions above. The 
     reinstallation is needed to modify the JDK java command to 
     support the -fast option.

Using the Compaq Fast VM with the JDK

The following sections describe how to use the Compaq Fast VM.

The java -fast Command

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

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

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

 -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

These 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 1.1.7B JDK 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 running Tru64 UNIX. In addition, the Fast VM provides 
improved memory management by means of a copying garbage 
collector. This garbage collection technique has been shown to be 
faster than the more common "mark and sweep" style collector 
employed by the 1.1.7B JDK. 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 was 
designed to mimic the behavior of the JDK java command to assure 
that programs behave the same regardless of which VM 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 continguous 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 a 
     different addresses. The Fast VM begins mapping at 0x40000000 
     and grows upward from that address. See the JDK 1.1.7B release 
     notes for information on how the JDK java command 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. 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/shlib/libjava-fast.so
   * /usr/shlib/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/include/java -I/usr/include/java/alpha \
   /usr/shlib/libjava-fast.so \
   /usr/shlib/libjava.so      invokejvm.cxx

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

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

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 JDK.

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.
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. 