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 look for classes -cp class path -D= set a system property -fullversion print out detailed version information -help print out this message -ms set the initial Java heap size; default is 16mb -mx set the maximum Java heap size; default is 128mb -noverify do not verify any class -ss 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 set the maximum Java stack size for any thread -prof[:] output profiling data to ./java.prof or ./ 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.