This guide gets you started quickly with Sun Java Real-Time System (Java RTS).
See also the Sun Java Real-Time System FAQ (Frequently Asked Questions) for a comprehensive, though not exhaustive, list of questions and answers about Java RTS.
The main characteristic of a real-time application is that the system is subject to real-time constraints. Worst-case response times must be deterministic, in other words, predictable within given limits. The Sun Java Real-Time System guarantees determinism by ensuring that time-critical code is executed at the highest priority, even higher than the garbage collector (GC) if needed.
The first Java Specification Request (JSR) issued by the Java Community ProcessSM (JCP) was JSR 1: the Real-Time Specification for Java (RTSJ). The Sun Java Real-Time System (Java RTS) is Sun's implementation of that specification, including a Real-Time Garbage Collector (RTGC).
We define non-real-time and real-time requirements for an application as follows:
Real-time does not (necessarily) mean "real fast," and therefore Java RTS is more concerned with determinism than with speed. However, the platform does indeed incorporate many features that improve throughput while still guaranteeing determinism.
Determinism can be expressed in terms of jitter, which is central to measuring the deterministic behavior of a program. Jitter measures the variation in a particular response time for a particular computational scenario of interest within a given executing application. With respect to determinism, an ideal value for jitter would be zero, indicating perfect predictability. More realistically, the aim of real-time processing is to reduce jitter to an acceptable level. Moreover, any jitter that occurs must be bounded, that is, we must guarantee that the jitter remains within known bounds.
Java RTS implements not only the Real-Time Specification for Java (RTSJ), but also the specification for Java Platform, Standard Edition (Java SE). Therefore, a program that runs on the Java SE platform will also run on the Java RTS platform, although without real-time behavior.
The easiest way to get off to a quick start with Java RTS is to convert an existing Java SE application to Java RTS.
Following the steps below can help you improve the determinism of your application.
In addition, an example program is provided at the end of this document.
Step 1. Check Your Java RTS Installation
We assume that you have already installed Java RTS for your platform according to the instructions in the Java RTS Installation Guide. Check your installation as follows:
Note: (Solaris OS) In order to execute the 64-bit Java RTS VM,
Step 2. Identify Real-Time Threads
Real-time threads are those which must execute within certain limits, that is, in a
predictable, deterministic way. Most applications will have a few real-time threads,
while the remaining threads are non-real-time, that is, they do not have rigid temporal
constraints. Non-real-time threads are instances of the class
You also need to make sure that the priorities assigned to threads reflect their importance. In addition to the 10 regular Java priorities, Java RTS features a number of unique real-time priority levels, where this number depends on the host operating system (Solaris OS or Linux). A real-time thread of a lower priority can be preempted in its execution by a real-time thread of a higher priority.
Real-time threads can be non-critical (soft real-time) or critical (hard real-time), and this distinction is determined by the critical priority boundary. Real-time threads whose priority is above the critical boundary are called critical real-time threads, while those below the boundary are called non-critical real-time threads. The default for this boundary is the middle of the real-time range, and is OS-dependent.
To determine the minimum and maximum real-time priorities available, use the methods
In addition to having a higher priority, critical real-time threads benefit from a user-defined amount of memory reserved for their use, as explained in Step "Configure the RTGC for Hard Real-Time."
Define a critical real-time thread if and only if it has a definite time constraint. Otherwise, there could be too much competition among these threads for resources.
For a detailed description of Java RTS thread types and their priorities, see the Java RTS Garbage Collection Guide.
Step 3. Configure the Compilation System
The standard compilation scheme for a Java program can break the determinism of a real-time program, because the following activites can occur during time-critical phases of program execution:
Java RTS provides the Initialization-Time-Compilation (ITC) scheme, which solves the problems described above by allowing you to control the following:
The Java RTS Compilation Guide contains a detailed description of the compilation modes (schemes) for the various thread types and how to configure them.
If you perform no configuration at all, then the run-time compilation can cause jitter that breaks your application's determinism.
However, for purposes of getting started quickly, you can run your application with special Java RTS command-line parameters that specify the automatic creation of files containing the precompile and preinit lists.
The precompile and preinit files are cumulative, that is, each time you run the application, more methods and classes can be added to the files. Therefore, you should run the application as many times as necessary to ensure that all the time-critical real-time code has been executed, which ensures that the precompile and preinit lists are complete. You might want to run the application with various arguments or in various conditions in order to ensure code coverage. Once code coverage is complete, your real-time application should not suffer from jitter caused by symbol resolution, class initialization, or execution-time compilation.
You can use the following command as an example of a minimum level of ITC configuration:
Here is the explanation of what is happening with the example command above:
Step 4. Configure the RTGC for Hard Real-Time
Java RTS includes a Real-Time Garbage Collector (RTGC). This GC can be tuned in various ways to get the best determinism for any given application. However, to get started, only a minimum amount of configuration is necessary.
The RTGC guarantees determinism to critical real-time threads by reserving memory for these threads.
This amount of memory is specified with the command line parameter
You can leave the other parameters at their default values, but if your application does not exhibit the desired determinism, you can try some basic tuning of the RTGC (see the next step).
See the Java RTS Garbage Collection Guide for a detailed description of how the RTGC works.
Step 5. (Optional) Tune the RTGC for Soft Real-Time
The default values for the RTGC parameters should be sufficient for getting started with Java RTS. Optional advanced tuning is described in detail in the Java RTS Garbage Collection Guide.
Java RTS uses a sophisticated auto-tuning mechanism to determine the optimal conditions under which to start the RTGC or boost its priority to a higher level. At the end of each garbage collection cycle, Java RTS calculates a memory threshold based on previously allocated memory and other factors in order to predict how memory might be allocated during the next cycle. It is best to allow this procedure to run with its default values.
The RTGC is fully concurrent, that is, it can recycle memory without stopping your threads. However, it must get enough CPU time to recycle memory faster than the threads consume it. At the same time, you need to find the balance between throughput and predictability (determinism). If you have sufficient CPU time available, you can try changing the number of parallel RTGC worker threads.
Step 6. Run Your Program
Run your program with, for example, the following command. See the next section for an explanation of
java \ -XX:+RTSJBuildCompilationList \ -XX:+RTSJBuildClassInitializationList \ -XX:CompilationList=<precompile-file-name> \ -XX:PreInitList=<preinit-file-name> \ -XX:RTGCCriticalReservedBytes=<amount> \ -XX:+PrintGC \ -XX:+LogJitterProneEvents \ <application> <arguments>
Step 7. Verify the System Configuration
Use one or more of the following suggestions to check whether your system was correctly configured for your application to be determinstic:
The Example Program
Note that this example program allocates very little memory, unlike a typical application, and therefore we have no need to configure the Real-Time Garbage Collector.
We show in this section how to compile and run this program. The source code of the HelloWorldRT program is provided together with this Quick Start Guide.
We suppose in the scenarios below that the source code file
Compile the HelloWorldRT example
Change directory to
Produce stabilized ITC compilation lists
Now run three times the following command to generate ITC compilation system data to be used in further runs:
java \ -XX:+RTSJBuildCompilationList \ -XX:+RTSJBuildClassInitializationList \ -XX:CompilationList=nhrt.precompile \ -XX:PreInitList=itc.preinit \ HelloWorldRT
After the second run the generated
Run the HelloWorldRT program with finalized compilation lists
You can now run the program without generating ITC compilation files to avoid any impact on the deterministic behavior due to the ITC compilation system:
java \ -XX:CompilationList=nhrt.precompile \ -XX:PreInitList=itc.preinit \ HelloWorldRT
Below is a sample output of a run of the HelloWorldRT program:
Hello Real-Time World ! ---------------------------------- Number of iterations = 10000 Period value = 2 milliseconds (ms) ---------------------------------- Real-time thread execution finished. Noticeable latencies (values >= 100 microseconds) in order of occurrence (if any): Loop 2709: Rescheduling time = (1255594555195 ms, 473904 ns); Noticeable latency = (0 ms, 107078 ns) Highest latency values in increasing order: New highest latency at loop 2 = (0 ms, 5419 ns) New highest latency at loop 3 = (0 ms, 5832 ns) New highest latency at loop 84 = (0 ms, 7508 ns) New highest latency at loop 1336 = (0 ms, 26563 ns) New highest latency at loop 1347 = (0 ms, 31552 ns) New highest latency at loop 2709 = (0 ms, 107078 ns) Bye, Real-Time World ...
Further Reading of Java RTS Documentation
All of the Java RTS technical documents contain information that will help you continue your successful experience. The latest versions of these documents are available on the Java RTS Technical Documentation web page.
Installation Guide - Install the Java RTS virtual machine, the kernel modules, and grant privileges to users.
Release Notes - Check release-specific details.
Compilation Guide - Configure the compilation system for maximum determinism.
Garbage Collection Guide - Configure the Real-Time Garbage Collector for maximum determinism.
Java RTS Command-Line Options - Consult the list of command-line options that are specific to Java RTS.
Technical Information - Learn even more details for improved programming success.
A Practical Introduction to Achieving Determinism - Play with a set of example programs to see how various parameters can affect determinism.
Tools and Troubleshoting
Java RTS DTrace Provider Guide (Solaris OS only) - Use the special DTrace probes provided for use with Java RTS.
Java RTS Tools, Tuning, and Troubleshooting Guide - Get help with troubleshooting.
The Thread Scheduling Visualizer (TSV) tool and accompanying guide. You can download the TSV tool at the same time you download a Java RTS Evaluation. For your convenience, a link to the TSV guide alone is provided on the Java RTS Technical Documentation web page.
For comments and questions, please contact Java RTS Engineering and Marketing.
Copyright © 2009 Sun Microsystems, Inc. All Rights Reserved.