New in 3.7:
Note: Information in this section is applicable to Excelsior JET Professional Edition only.
Excelsior JET VM comes with multiple implementations of the runtime system, optimized for different hardware configurations and application types. It enables your application to effectively utilize the computing power of systems that support parallel execution /Examples are multi-processor servers, multi-core CPUs and CPUs that support Hyper-Threading Technology/ , thereby improving performance.
This section describes the available runtime systems and helps you select the proper runtime for your applications and target system configurations.
The Desktop Runtime is suitable for applications that typically run on conventional desktop and notebook computers. It is optimized for single-CPU systems, including those based on Hyper-Threading-enabled processors and dual-core desktop chips. Zero runtime fee makes it the best choice for rich clients and other desktop applications.
The Workstation Runtime is a scaled up version of the Desktop Runtime targeting technical client applications that require high computing power. Examples are visualization and engineering design tools, which often run on high-end graphic workstations. The Workstation Runtime can operate effectively on both single-CPU and dual-CPU boxes.
You may freely use the Workstation Runtime for development, but production and redistribution uses require payment of a runtime fee.
The Server Runtime fits best for highly concurrent server applications. It provides out-of-the-box performance and scalability and takes full advantage of multi-processor hardware. Development use is free, but deployment in a production environment is subject to runtime fee.
The Classic Runtime is technically a restricted version of the Desktop Runtime. Its use makes sense only if your application does not run several heap-intensive threads in parallel. In that case it may save a few percent of CPU and memory resources. No runtime fee applies.
The Classic runtime was the only option in Excelsior JET VM prior to version 3.7, hence its name. It is the only option in the Standard Edition.
Basically, you select an Excelsior JET Runtime depending on the type of your application and hardware configurations of systems to which it will be deployed. To make the right choice, follow the recommendations below.
If your server application will be deployed to high-end multi-processor machines, opt for the Server Runtime. Other Runtimes are not optimized for N-way systems so choosing them would significantly degrade the throughput of the server. Read more about licensing terms for the Server Runtime at
http://www.excelsior-usa.com/jetfees.html.
For low-end uniprocessor servers, the royalty-free Desktop Runtime fits best.
In most cases, the Desktop Runtime is the optimal choice. Nevertheless, you may prefer other options in the following cases:
The Workstation Runtime is more suitable than Desktop if your application is designed to work faster on powerful dual-CPU workstations. Read more about licensing terms for the Workstation Runtime at
http://www.excelsior-usa.com/jetfees.html.
The Classic Runtime’s overheads on memory allocation and garbage collection are lower than those of the Desktop Runtime so its use may slightly improve application performance and reduce its memory footprint as compared to the Desktop Runtime, but only if your application never runs several heap-intensive threads in parallel. If you are not completely sure whether it is the case, use the Desktop Runtime.
You may experiment with each runtime flavor as described in the next section.
You select the runtime when compiling your application. The JET Control Panel shows the available RT options on the Target page. If you use the command-line interface to the JET compiler, specify the JETRT equation in the project file:
-JETRT=WORKSTATION
Finally, if you run your application via the xjava launcher, use the -Xrt option to select the desired runtime (see Options):
xjava -Xrt=server -jar MyServer.jar
You may also select the runtime at application launch time specifying the jet.rt property in the JETVMPROP environment variable (see JET runtime properties):
SET JETVMPROP=-Djet.rt:classic
MyApp.exe
Note, however, that the jet.rt property can only force lower-end runtimes /In the sense of this order: Classic < Desktop < Workstation < Server/ than the runtime selected at compile-time. For instance, if you chose the Desktop Runtime when compiling your application, you may force the Classic Runtime during its launch, but not the other runtimes. If you wish to test your application against all runtimes, select the Server Runtime in the project and then select other runtimes using the jet.rt property as desired.
If you used any optimizing compilers before, you must have experienced a situation when a particular combination of the many available optimization control options results in incorrect code being generated by the compiler for your program, or when the program only works properly when compiled with debug information generation enabled. The reason is that a compiler with dozens of optimization control options is extremely difficult and expensive to test, as the compiler manufacturer has to check all possible combinations of options, so no vendor does that.
Fortunately, this is not the case with JET. Unlike many other compilers, JET always optimizes code to the maximum extent possible. Even enabling generation of debug information to ease field engineering does not affect the output code. The only two optimizations that may be disabled or adjusted are stack allocation of objects and inline expansion of methods, because they can negatively affect scalability (see Number of threads) and code size of the resulting program.
To get the maximum performance, do the following:
+GENSTACKALLOC
+INLINE -INLINELIMIT = 200 % default is 100 -INLINETOLIMIT = 2000 % default is 1000
Inline expansion should be used with care. It allows the compiler to substitute a method in-line, if that method is declared as final or if compile time analysis confirmed safety of such substitution. As a rule, enabling inline expansion results in faster but bigger code. However, the effect of this optimization depends on the programming style (sizes of methods, etc). You may control inlining aggressiveness using equations INLINELIMIT and INLINETOLIMIT in the project file, or by selecting one of the presets in the Inline expansion list in the Control Panel.
If you are using Excelsior JET, Professional Edition, consider compiling your application using JetPerfect Global Optimizer, which greatly improves code quality through global optimizations.
Finally, turning run-time checks off (options CHECKARRSTORE, CHECKINDEX, and CHECKNULL) reduces code size and improves performance, but can make your application work incorrectly or affect its portability. The JET optimizer is capable of removing redundant checks, so a typical program runs only a few percent faster with run-time checks turned off explicitly.
JET is fully SMP-aware, so your compiled applications will scale to multiple processors automatically. However, you should select the Workstation or Server RT to enable the most effective utilization of several CPUs (see Runtime Selection). You may wish to fine tune the garbage collector as described in Garbage collection on n-way systems.
Excelsior JET runtime maps Java threads directly onto native operating system threads. Windows reserves the same amount of address space for the stack of each thread of a particular process, which is retrieved from the size of stack reserve field of its EXE header.
The default size of stack reserve is about one megabyte, which basically means that if your program attempts to run 1,000 threads simultaneously (which is not unusual for server-side applications), their stacks will claim one gigabyte of the process’ virtual address space, of the total of four gigabytes. Given that some part of the virtual address space is reserved by the operating system (Windows reserves half of it, i.e. 2GB), one process cannot run more than a few thousand threads simultaneously with that default setting.
An attempt to run too many threads simultaneously in a Java application results in OutOfMemoryError. Waste of address space for thread stack reserves also effectively limits the amount of memory that the memory manager may allocate from the OS and thus may also cause OutOfMemoryError.
To reduce the default stack size and thus improve the scalability of your application with respect to the number of threads:
-STACKLIMIT=65536
This is equivalent to setting the -Xss option of the standard Java launcher.
Another thing to consider is that enabling stack allocation of objects increases the compiled programs’s stack size requirements, negatively affecting its scalability. Therefore, you may wish to disable this optimization by unchecking the Allocate objects on the stack box on the Options page (see Optimizations) or turning the GENSTACKALLOC option off in the project file. This would enable you to further reduce the thread stack size as described above, thus letting your application run more threads simultaneously at the cost of minor performance loss.
A Java launcher allows you to set a system property using the -D command-line switch, for instance:
java -Dp1name -Dp2name=p2value MyApp arg1 arg2
A JET-compiled application is a conventional executable file that is run by itself:
MyApp arg1 arg2
so there is no place to set a property on the application’s command line.
JET provides three ways to set system properties for your compiled application:
-JETVMPROP=-Dp1name -Dp2name:p2value
SET JETVMPROP=-Dp1name -Dp2name:p2value
MyApp arg1 arg2
Warning: The JETVMPROP environment variable is intended to be used during development and field engineering. Normally, you should hardwire the necessary system properties into the executable at compile time or install time as described above. If you need to override the hardwired properties at launch time, use a batch file for launching your application. Never set the JETVMPROP environment variable globally (i.e. in the Windows registry or AUTOEXEC.BAT) on enduser systems as it may cause other JET-compiled applications to misbehave.
Notes:
The JET runtime recognizes the following properties:
Sets the maximum heap size to the given amount of bytes (kilobytes or megabytes respectively if either of the suffixes k or m is present), overriding the compile-time heap size setting. Setting size to zero enables adaptive heap size. See Application memory usage tuning for more information.
Setting this property forces heap defragmentation after each garbage collector invocation. See Heap defragmentation for more information.
Specifies the maximum proportion of CPU time to be allocated to the garbage collector at runtime, in 1/1000ths. See Heap optimization for details.
Select a specific JET run-time. Valid values of flavor-name are classic, desktop, workstation, and server.
See Runtime Selection for details.
Sets the maximum number of concurrent threads that may be used for garbage collection. By default, N equals the number of processors on the system. See Garbage collection on n-way systems for more information.
Enables JIT compilation. See Using the mixed model for more information.
Enables caching of JIT compilation results. See Using the mixed model for more information.
Designates path as the JIT compiler cache directory. See Using the mixed model for more information.
Logs names of DLLs loaded by the application at run time into a file.
Enables stack backtracing facility. See Stack trace for more information.
Forces usage of JRE native methods. Use to fix incorrect application behavior caused by a bug in Excelsior’s implemenation of native methods. See JRE-less operation for more information.
Forces the optimizing JIT compiler. See JIT compiler selection for more information.
Forces the fast JIT compiler. See JIT compiler selection for more information.
By default, the JET runtime automatically determines, depending on system load, how much memory your application may allocate from the operating system without invoking the garbage collector. You may also explicitly specify the maximum amount of heap memory available to your application at run time /The respective command line parameter of the standard Java launcher is -Xmx/ :
-HEAPLIMIT=10485760 % maximum heap size is 10MB
You may use the jet.gc.heaplimit property to override the compile-time heap size setting:
SET JETVMPROP=-Djet.gc.heaplimit:10m
MyApp.exe
The garbage collector is called implicitly by the memory allocation function in the following cases:
If a memory block of requested size still could not be allocated after garbage collection, the memory manager attempts to defragment the heap (see Heap defragmentation). If defragmentation could not help either, the exception OutOfMemoryError is thrown.
The memory manager performs heap defragmentation only if memory block allocation is still impossible after garbage collection. However, many applications require less memory for proper operation if defragmentation is done after each garbage collection. You may force this behavior by setting the jet.gc.defragment property:
SET JETVMPROP=-Djet.gc.defragment
MyApp.exe
In most cases, forcing defragmentation will increase GC pauses and thus slow down your application. However, under certain circumstances, e.g. on systems with low RAM capacity, it may actually improve overall performance. Also, the changes in memory consumption and performance are application-specific, so it is up to you to experiment and then decide whether frequent heap defragmentation is benefical to your application.
Defragmentation will also occur if the method System.gc() was called by the application and excessive heap fragmentation was detected during the garbage collection cycle.
Professional Edition only:
In order to optimize heap layout and reduce memory usage, the JET runtime periodically invokes the garbage collector and the heap defragmenter. This typically occurs when your application is standing idle, but the garbage collector is also allowed to consume some portion of CPU time even if your application is actively using the CPU. By default, the garbage collector may utilize up to 1.1% of total CPU time /Of course, if your application allocates objects very intensively, and heap size is not adaptive or the amount of available physical memory is low, more CPU time will be spent in the garbage collector regardless of this setting./ .
You may fine tune heap optimization using the jet.gc.ratio property. Its value is the amount of 1/1000ths of total CPU time that may be spent in the garbage collector, so the default setting of 1.1% is specified as follows:
SET JETVMPROP=-Djet.gc.ratio:11
MyApp.exe
The maximum ratio is 40%:
SET JETVMPROP=-Djet.gc.ratio:400
MyApp.exe
Finally, you may specify the ratio of 0 to entirely disable periodic garbage collection, effectively returning to JET 2.5 memory management scheme:
SET JETVMPROP=-Djet.gc.ratio:0
MyApp.exe
Note: The behavior of the memory manager and the garbage collector in particular is application-specific. So increasing the GC ratio does not necessarily result in lower memory consumption, and decreasing it does not always improve application performance. You have to experiment with your particular application to find the best ratio for it.
See System properties for more information on setting system properties.
Professional Edition only:
On n-way systems, the JET garbage collector uses auxiliary threads to reduce overall collection time. By default, the total number of concurrently working GC threads equals the number of CPUs reported by the operating system. However, you may wish to reduce this number for optimum system performance, e.g. if you want one or more CPUs to be available to some native threads or processes running at the same time.
Use the jet.gc.threads property to specify the maximum number of GC threads. For instance, to make the garbage collector use two threads at the most, run your application as follows:
SET JETVMPROP=-Djet.gc.threads:2
MyApp.exe
See System properties for more information on setting system properties.
By default, Throwable.printStackTrace() methods do nothing in a JET-compiled application, because stack tracing is disabled in the JET runtime. Some third-party APIs may rely on stack trace printing. One example is the Log4J API that provides logging services.
The JET VM supports two modes of stack trace printing: minimal and full. In the minimal mode, line numbers and names of some methods are omitted in call stack entries, but class names are exact. In some cases, it is enough for the stack trace-dependent API to work, e.g. Log4J works ok in this mode.
Note: Enabling stack trace may negatively impact performance, if exceptions are thrown and caught repeatedly.
In the full mode, the stack trace info includes all line numbers and method names. However, enabling the full stack trace has a side effect of substantial growth of the resulting executable size (approx. by 30%).
In the JET Control Panel, you enable stack trace on the Target page (see Executable file settings).
You may also select the stack trace mode via compiler options and run-time properties. To enable the minimal stack trace, set the jet.stack.trace property:
SET JETVMPROP=-Djet.stack.trace
MyApp.exe
See System properties for more information on setting system properties.
To enable the full mode, in addition to setting the property, toggle the GENSTACKTRACE option ON in your project file
+GENSTACKTRACE
and re-compile your application.
For security reasons, you may wish to completely disable stack trace output in the end-user version of your application, by setting the option DISABLESTACKTRACE ON in your project file:
+DISABLESTACKTRACE
By default, JET does not produce code for assertion statements, first introduced in J2SE 1.4.0, because generation of that code has negative impact on application performance and footprint. To enable assertions in the resulting executable:
+GENASSERTS
Assertions are disabled by default on the JVM as well, but may be enabled for the entire application or for particular classes at launch time using the java command’s switches -ea, -da, -esa, and -dsa. With JET, if you enable assertions generation as described above, you may also pre-activate them using the same switches in the JETVMPROP equation in your project file:
-JETVMPROP=-ea:com.MyCompany.MyPackage
or control them at launch time using the JETVMPROP environment variable:
SET JETVMPROP=-ea:com.MyCompany.MyPackage
MyApp.exe
JET also supports enabling and disabling assertions programmaticaly at run time.
Note: In the current version of Excelsior JET, system classes are precompiled with assertions disabled, so the -esa switch has no effect.
JET is unable to recognize if your application uses any particular resource files, such as images or audio clips. If your application classes are packed together with resources into one or more jar files, JET may bind jars that contain resource files to the resulting EXE or DLL, almost like that is done for native Windows applications. The JET runtime system will load resource files from those bound jars at runtime as if they were separate files. No changes have to be made to your application’s code for this to work.
Using the JET Control Panel, you may enable/disable resource binding for particular jars as described in Step 4: Resources. In the project file, you may enable resource binding for all jars at once or completely disable it by setting the option BINDRESOURCES ON or OFF respectively.
By default, JET removes class files from jars as they are bound to the executable, assuming that those classes were precompiled. However, in the Mixed Compilation Model you may wish some classes to be loaded dynamically. Also, there are APIs (e.g. Java Crypto Extension) that require class files to be available at run time. To bind the entire jars (both resources and classes) to the resulting executable, use the JET Control Panel as described in Step 4: Resources or set the option BINDCLASSES ON in your project file.
Example:
% MyApp.prj . . . -bindresources+ % Bind resources only, -bindclasses- % do not bind classes . . . !module MyApp.jar
If the resource files required for your application to work are not packaged into jar files, or you cannot use resource binding for some reason, set the CLASSPATH environment variable to point to the respective directories and jars, so as to enable the JET runtime to find those resources. You might prefer to use a batch file for that:
REM RunMyApp.bat
SET CLASSPATH=MyAppRes.jar;.\res
MyApp.exe
Alternatively, you may use the standard system property java.class.path:
SET JETVMPROP=-Djava.class.path:MyAppRes.jar;.\res
See System properties for more information on setting system properties.
When creating a profile, JET precompiles the Java 2 classes that are needed for input and output of characters in national encodings into a set of DLLs. The idea is to place support for rarely used encodings and encodings that require large conversion tables (such as Chinese) into separate DLLs, so as to reduce the disk footprint of compiled applications that do not use some or all of those encodings.
If your application may need to use national encodings, make sure to include the respective locales into the installation package as described in Step 5: Selecting Optional JET Runtime Components.
Professional Edition only:
When using JetPerfect Global Optimizer, you have to include the respective locales at compile time instead. See Forced usage file format for details.
Professional Edition only:
The runtime library of Excelsior JET, Professional Edition includes Excelsior’s own, Windows-optimized implementation of native methods for all Java 2 platform classes except for AWT and Swing. Therefore, any Java application not using AWT or Swing (batch, server-side, using third-party GUI library like IBM SWT, etc.) compiled with the Professional Edition does not require the Java Runtime Environment (JRE) to be installed on the target system.
Nevertheless, you have an option to force usage of JRE native methods by setting the property jet.usejre:
SET JETVMPROP=-Djet.usejre
MyApp arg1 arg2
You may wish to do this if your compiled application behaves incorrectly when using native methods from JET runtime library,
See System properties for more information on setting system properties.
Optimized native code produced by JET is about as hard to reverse engineer as code produced by leading C++ compilers. This will not save you from crackers (as you know, they are used to crack C++ programs), so you may need to employ a third party solution to prevent illegal use of your application. But the understanding of your code will become a much more sophisticated and time-consuming task, so steailng your algorithms and know-how will be more difficult and expensive.
In that regard, the only major difference between executables created by JET and C/C++ executables is that the former contain Java reflection information for all classes, methods and fields. If your application does not use reflection, you may run your classes and jars through an obfuscator that would assign meaningless names to classes, methods and fields before compiling your application with JET.
Note: When using an obfuscator with JET, please make sure to force it to leave the bytecode instructions intact. Obfuscation of bytecodes has serious negative impact on performance of the native code produced by JET from those bytecodes.
The reflection information is also used for stack trace output and usage list generation. You may wish to disable these features in the end-user version of your application, using the options DISABLESTACKTRACE and DISABLEUSAGELIST respectively.
On a virtual machine, if a certain class is imported but never used during program execution, i.e. it is never instantiated, none of its static methods are called, and none of its static fields are accessed, then no attempt to load that class would occur and therefore the program would execute normally even if the respective class file is not present on the system or cannot be reached by the VM.
Similarly, if a class does not contain a particular method or field that is referenced in another class, execution on a virtual machine would fail only when and if control reaches the code referencing that absent field or method.
Being an ahead-of-time compiler, Excelsior JET analyzes the entire compilation set and thus is able to detect such inconsistencies. By default, they result in compilation errors. However, when an inconsistency is detected in bytecode that is not under your control, such as a third-party class library, you usually do not have a chance to remedy it quickly. If you encounter such problem, contact the vendor who supplied the inconsistent bytecode, and toggle the respecitve JET options to make the compiler treat bytecode inconsistencies as warnings:
+IGNORECLASSDUPLICATION
-CLASSABSENCE=IGNORE
The compiler will report warnings and will insert the code throwing java.lang.NoClassDefFoundError for all locations where absent classes are used, i.e. where instatiation, static method call, or static field access takes place.
If class XXX becomes available at run time,
-CLASSABSENCE=HANDLE
+IGNOREMEMBERABSENCE
The compiler will report warnings and will insert the code throwing java.lang.NoSuchMethodError or java.lang.NoSuchFieldError for all locations where absent members are used.
Note: In some applications, imported classes unavailable at compile time become available at run time. JET may handle this situation properly if you enable the reflective shield facility of the Mixed Compilation Model.
In some cases, the main JET compiler may fail to compile a particular method due to lack of memory or inability to restore the method’s hihg-level structure required for optimizing compilation, which may be caused by bytecode obfuscation. To cope with it, the main compiler invokes the so called baseline compiler for such methods. The baseline compiler implements only a few simple optimizations, and thus is able to compile any verifiable bytecode.
If the baseline compiler was invoked at least once during compilation of your project, the main compiler issues a message about the number of methods processed by the baseline compiler. Additionally, it logs the information about the methods compiled with a lower optimization level. The log file, having the executable’s name and the ".vaz" extension, is created in the current directory.
If baseline compilation occurs during compilation of your project, we would appreciate if you could e-mail us the resulting ".vaz" log file along with the .class files listed in it. It would help us improve the quality of our product.