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: Following is an example of the report output that occurs at program termination: 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 class’s 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: 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 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 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 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.