Command-Line Options
Sun Java Real-Time System 2.1
  

This document presents information about the -XX command-line options (parameters) that are specific to Sun Java™ Real-Time System (Java RTS) 2.1 virtual machine. For a list of the -XX options for the Java HotSpot™ Virtual Machine, see Java HotSpot VM Options.

Readme File: links to all Java RTS technical documents


Introduction

The -XX:+<flag> syntax sets a boolean flag to true, and -XX:-<flag> sets it to false. For parameters that take values, the syntax is -XX:<param>=<value>.

These parameters are intended either for a production environment or a development environment, as indicated in the "Env" column. Development parameters are available only to the debug version of the virtual machine (that is, java_g). Note that certain development parameters might produce I/O that can change the temporal behavior of the VM.

Caution: Options that are specified with "-XX" are not stable and are not recommended for casual use. These options are not part of the official Java API and are subject to change without notice from one Java RTS release to the other.

The Java RTS command-line options are grouped into the following categories:


Memory-Related Parameters

Parameter

Default

Env

Description

ImmortalSize

32M

prod

The amount of immortal memory to allocate.

ScopedSize

16M

prod

The total amount of memory for all scoped memory allocations.

RTSJTraceScopeStacks

false

dev

Enable tracing of scope stacks. Stacks are printed on changes.

RTSJEnableImmortalAllocationProbe

true

dev

Enable the immortal-alloc probe of the jrts DTrace probe provider. This probe fires when immortal memory is allocated. See the Java RTS DTrace Provider document.

RTSJShowHeapLayout

false

dev

Show the memory layout.

Back to top


Thread-Related Parameters

Parameter

Default

Env

Description

RTSJTraceThreading

false

dev

Trace (print) real-time thread scheduling events, such as thread start and death, priority modification or boost, blocking on lock, waiting.

RTSJTraceThreadBinding

false

prod

Trace the binding of threads to processors.

RTSJBindNHRTToProcessorSet

(Solaris OS only)

N/A

prod

Bind NHRTs to the processor set whose ID is specified by the value of the parameter.

RTSJBindRTTToProcessorSet

(Solaris OS only)

N/A

prod

Bind RTTs to the processor set whose ID is specified by the value of the parameter.

RTSJBindNHRTToProcessors

(Linux only)

N/A

prod

Bind NHRTs to the specified comma-separated list of processors or to the specified cpuset.

RTSJBindRTTToProcessors

(Linux only)

N/A

prod

Bind RTTs to the specified comma-separated list of processors or to the specified cpuset.

RTSJForceCyclic

(Used only with non-real-time applications.)

(Solaris OS only)

Use driver if available; otherwise, fall back to built-in support.

prod

Force or prevent usage of the cyclic device driver when running non-real-time applications.

  • Default (no value specified): Use driver if available; otherwise, fall back to built-in support.

  • Value = true: Use driver if available; otherwise, exit.

  • Value = false: Do not use driver. Use built-in support instead.

VMStackTraceAtRTSJException

false

dev

Print stack trace information for an RTSJ-specific exception.

Back to top


Access-Related and Assignment Check-Related Parameters

Parameter

Default

Env

Description

RTSJTraceAccessChecks

false

dev

Enable tracing of access checks. Illegal accesses are reported. (Used only in interpreted mode.)

RTSJTraceAssignmentChecks

false

dev

Enable tracing of assignment checks. Illegal assignments are reported. (Used only in interpreted mode.)

RTSJIgnoreThrowBoundaryError

false

dev

Let an exception escape its scope instead of replacing it. This allows the developer to dump the stack trace. (See Caution note below.)

Caution: If you activate the RTSJIgnoreThrowBoundaryError flag, do so only temporarily to obtain information that is hidden because of the replacement of an exception by a ThrowBoundaryError. Activation of this flag might lead to core dumps or other undefined behavior since the concerned object might be deleted while it is still in use. Always disable this option before making a bug report.

Back to top


Asynchrony-Related Parameters

Parameter

Default

Env

Description

RTSJSignalThreadPriority

RTSJMaxPriority

prod

Priority of the thread handling POSIX signals.

See the section "Handlers Released by System Threads" in the Java RTS Technical Information document.

RTSJForceHighResTimer

(Solaris OS only)

Use high-resolution timers if available; otherwise, fall back to regular, low-resolution timers.

prod

Force usage of the high-resolution timers.

  • Default (no value specified): Use high-res timers if available; otherwise, fall back to low-res timers.

  • Value = true: Use high-res timers if user has privileges; otherwise, exit.

  • Value = false: Do not use high-res timers. Use low-res timers instead.

RTSJHighResTimerThreadPriority

RTSJMaxPriority

prod

Priority of the thread releasing handlers associated with timers.

See the section "Handlers Released by System Threads" in the Java RTS Technical Information document.

RTSJDeadlineMonitoringThreadPriority

RTSJMaxPriority

prod

Priority of the system thread responsible for deadline monitoring.

See the section "Handlers Released by System Threads" in the Java RTS Technical Information document.

Back to top


Interpreter-Related Parameters

Parameter

Default

Env

Description

RTSJTraceNHRTInterpreted

false

prod

Trace bytecodes executed by an NHRT.

RTSJTraceInterpreterEntry

false

prod

Restrict bytecode tracing to print only the name of methods called (to be used in conjunction with RTSJTraceNHRTInterpreted or TraceBytecodes).

Back to top


Compiler-Related Parameters

The table below summarizes the command-line parameters that are used to control the compilation options for the various thread types.

See the Java RTS Compilation Guide for a detailed description of how to use these options.

Parameter

Default

Env

Description

ITCJLT

false

prod

When true, the ITC policy applies to all java.lang.Thread instances:

  • Methods in the precompile list are compiled at class initialization.
  • All other methods are JIT compiled.

When false, all java.lang.Thread instances execute code compiled in JIT mode.

ITCRT

true

prod

When true, the ITC policy applies to all javax.realtime.RealtimeThread instances:

  • Methods in the precompile list are compiled at class initialization.
  • All other methods are JIT compiled if the JITRT flag is on, or interpreted if the JITRT flag is off.

When false, all RealtimeThread instances execute code compiled in JIT mode if the JITRT flag is on, or interpreted code if the JITRT flag is off.

JITRT

true

prod

When true, RealtimeThread instances execute code compiled in JIT mode, except for methods in the precompile list.

When false, RealtimeThread instances execute interpreted code, except for methods in the precompile list.

BackgroundCompilation

true

prod

When true, enable background (asynchronous) JIT compilation.

When false, disable background (asynchronous) JIT compilation. This option enables synchronous compilation. This mode is not recommended when the RTGC is used.

CompilePreLoaded

false

prod

When true, for ITC mode, all the methods in the classes that are referenced in either the precompile list or the preload list are compiled at initialization.

  • The precompile list is a list of methods in specified classes; if the CompilePreLoaded flag is set, then all the methods in those specified classes are compiled at initialization.
  • The preload list is a list of classes; if the CompilePreLoaded flag is set, then all the methods in those classes are compiled at initialization.

When false, for ITC mode, only marked methods in the precompile list are compiled at initialization. This is the normal ITC behavior.

RTSJBuildCompilationList

false

prod

Instruct the VM to generate a file containing all the methods that were executed (compiled or interpreted) by a thread whose execution policy is ITC.

CompilationList

nhrt.precompile

prod

Name of the file containing the results from the RTSJBuildCompilationList option.

RTSJBuildPreloadList

false

prod

Instruct the VM to generate a file containing all the classes that are referenced during the compilation of methods at initialization.

PreLoadList

itc.preload

prod

Name of the file containing the results from the RTSJBuildPreloadList option.

RTSJBuildClassInitializationList

false

prod

Instruct the VM to generate a file containing the same list of classes as with the RTSJBuildPreloadList option, but in the order in which classes were initialized during the test run.

PreInitList

itc.preinit

prod

Name of the file containing the results from the RTSJBuildClassInitializationList option.

PrintCompilation

false

prod

Log JIT-compilation of methods.

Back to top


Optimization Parameters

The Java RTS virtual machine can be configured to run with or without the Real-Time Garbage Collector (RTGC). If the RTGC is not used, then the default HotSpot serial collector is used, along with a safepoint mechanism for both standard java.lang.Threads (JLTs) and RealtimeThreads (RTTs). (The RTGC is enabled by default but can be disabled with the command-line parameter -XX:-UseRTGC.)

Java RTS provides the following command-line options to control the use of a set of optimizations that impact the trade-off between performance and determinism.

Parameter

Default

Env

Description

UseInlineCaches

true with Serial GC

false with RTGC

prod

Use HotSpot's original implementation of inline caches.

RTSJUseInlineCaches

false with Serial GC

true with RTGC

prod

Use a variant of the above that does not attempt to reclaim IC stubs so as to avoid the use of safepoint.

UseCHA

true with Serial GC

false with RTGC

prod

Use HotSpot's original implementation of virtual method inlining. If an inlining is invalidated because of dynamic class loading, the code is de-optimized.

RTSJUseGuardedCHA

false with Serial GC

true with RTGC

prod

Use virtual method inlining that does not require de-optimization.

The following table summarizes the thread types for which a particular optimization can be enabled or not, depending on whether or not RTGC is used. In the table, "Y" means that the optimization can be enabled for that thread type, and "N" indicates that it cannot.

"(Y)" means that the optimization can be enabled but it does not provide any benefit compared to another optimization that can be enabled in the same situation. For example, using RTSJUseGuardedCHA for JLT or RTT (with Serial GC) does not provide any additional benefit because UseCHA can be used for these thread types when not using RTGC.

Parameter With Serial GC With RTGC
  JLT RTT NHRT JLT RTT NHRT
UseInlineCaches Y Y N N N N
RTSJUseInlineCaches (Y) (Y) N Y Y N
UseCHA Y Y N N N N
RTSJUseGuardedCHA (Y) (Y) Y Y Y Y

Back to top


Real-Time Garbage Collector-Related Parameters

The following command-line options can be used to tune the activity of the Real-Time Garbage Collector (RTGC). These options are presented at three levels of user experience and need: basic, advanced, and expert.

See the Java RTS Garbage Collection Guide for a detailed description of how to use these options.

RTGC Basic Options

Parameter

Default

Env

Description

RTGCCriticalReservedBytes

0

prod

Free memory threshold, in bytes, under which only critical threads can allocate memory. To guarantee determinism, configure this parameter. See "Tuning the RTGC" in the Java RTS Garbage Collection Guide.

RTGCCriticalBoundary

OS-dependent

prod

The priority boundary between critical and non-critical threads. Threads with priority above this boundary are considered to be critical threads, while threads with priority at this boundary or below are non-critical threads. The value defaults to the middle of the real-time range, which is greater than the default priority for real-time threads. This default value is OS-dependent, as explained in "Real-Time Priorities" in the Technical Information document.

PrintGC

false

prod

Print information gathered whenever the GC runs.

UseRTGC

true

prod

Use the new real-time garbage collector instead of the non-real-time, serial collector.


RTGC Advanced Options

Parameter

Default

Env

Description

RTGCNormalPriority

11

prod

Normal priority for the RTGC. It defaults to 11 to try to offer soft real-time behavior for all the real-time threads.

RTGCNormalWorkers

0

prod

Initial number of parallel RTGC worker threads. 0 means no limit. 1 is for non-parallel RTGC.

RTGCBoostedWorkers

0

prod

Boosted number of parallel RTGC worker threads. 0 means no limit. 1 is for non-parallel RTGC.


RTGC Expert Options

Parameter

Default

Env

Description

RTGCPrintStatistics

false

prod

Print additional information gathered whenever the GC runs, for advanced tuning or debugging.

RTGCBoostedPriority

RTGCCriticalBoundary

prod

Priority at which the RTGC activity should execute in order to guarantee determinism. When free memory falls below the boosted memory threshold, the RTGC priority is boosted to this level. If this parameter is not specified, then its default value is the value of the RTGCCriticalBoundary parameter.

BoostedMinFreeBytes

0

prod

Minimum (estimated) free heap memory level, in bytes, below which the RTGC should be boosted to priority RTGCBoostedPriority.

BoostedSlideFactor

10

prod

Speed at which allocation bursts are forgotten in boosted mode. An integer from 0 to 100, which will be converted to a percentage.

BoostedSafetyMargin

20

prod

Variation of the allocation rate that is supported without creating jitter in boosted mode. An integer from 0 to 100, which will be converted to a percentage.

NormalMinFreeBytes

0

prod

Minimum (estimated) free heap memory level, in bytes, below which the RTGC should start its next cycle, at priority RTGCNormalPriority.

NormalSlideFactor

20

prod

Speed at which allocation bursts are forgotten in normal mode. An integer from 0 to 100, which will be converted to a percentage.

NormalSafetyMargin

10

prod

Variation of the allocation rate that is supported without creating jitter in normal mode. An integer from 0 to 100, which will be converted to a percentage.

RTGCWaitDuration

10

prod

Number of milliseconds between two consecutive runs of the RTGC, unless memory is exhausted or an explicit GC is requested.

Back to top


Other Parameters

Parameter

Default

Env

Description

RTSJEnableServerThreadNamingProbe

false

dev

Activate the firing of the thread-set-name probe during the binding and unbinding process.

RTSJDisableAtomicThreadDump

true

dev

Disable the suspension of execution. Set to true in prod enviroment. When this parameter is set to false, Java RTS suspends application execution in order to obtain thread stack information (for debugging in dev environment).

RTSJNumRTPrio

OS-dependent

prod

The number of real-time priorities used by Java RTS. See explanation in "Real-Time Priorities" in the Technical Information document.

VMStackTraceAtRTSJException

false

dev

Print a VM stack trace when an RTSJ exception occurs.

RTSJIgnoreThrowBoundaryError

false

dev

Use this parameter only temporarily to obtain information that is hidden because of the replacement of an exception by a ThrowBoundaryError. Caution: Activation of this flag might lead to core dumps or other undefined behavior since the concerned object might be deleted while it is still in use.

LogJitterProneEvents

false

prod

Produce a file named hs_jitter_pid<pid>.log containing several time-stamped events, including class initialization, method interpretation, failed allocation for a critical thread, etc. See "Command-Line Options" section in the Tools, Tuning, and Troubleshooting Guide.

Back to top

Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.