Exit Print View

Troubleshooting Guide for HotSpot VM

Print View

Document Information


1.  Diagnostic Tools and Options

2.  Detailed Tool Descriptions

3.  Troubleshooting Memory Leaks

4.  Troubleshooting System Crashes

5.  Troubleshooting Hanging or Looping Processes

6.  Integrating Signal and Exception Handling

6.1 Signal Handling on Solaris OS and Linux

6.1.1 Reducing Signal Usage

6.1.2 Alternative Signals

6.1.3 Signal Chaining

6.2 Exception Handling on Windows

6.2.1 Signal Handling in the HotSpot Virtual Machine

6.2.2 Console Handlers

7.  Submitting Bug Reports

A.  Environment Variables and System Properties

B.  Command-Line Options

C.  Fatal Error Log

D.  Summary of Tools in This Release

Chapter 6

Integrating Signal and Exception Handling

Sometimes developers have to integrate Java applications with code that uses signal or exception handlers. This chapter provides information on how signals are handled in the HotSpot Virtual Machine. It also describes the signal chaining facility that facilitates writing applications that need to install their own signal handlers. The signal chaining facility is available on Solaris OS and Linux.

6.1 Signal Handling on Solaris OS and Linux

The HotSpot Virtual Machine installs signal handlers to implement various features and to handle fatal error conditions. For example, in an optimization to avoid explicit null checks in cases where java.lang.NullPointerException will be thrown rarely, the SIGSEGV signal is caught and handled, and the NullPointerException is thrown.

In general there are two categories of situations where signal/traps arise.

The following table lists the signals that are currently used on Solaris OS and Linux. The mention “optional” means that the signal is not necessary when the -Xrs option is specified, as explained in 6.1.1 Reducing Signal Usage. The mention “configurable” means that alternative signals may be specified, as explained in 6.1.2 Alternative Signals. See 6.1.3 Signal Chaining for detailed information about signal chaining.

Used in the implementation for implicit null check, and so forth.
Thread dump support: To dump Java stack traces at the standard error stream. (Optional.)
Used to support the shutdown hook mechanism (java.lang.Runtime.addShutdownHook) when the VM is terminated abnormally. (Optional.)
Used in the implementation of the java.lang.Thread.interrupt method. (Configurable.) Not used starting with Solaris 10 OS. Reserved on Linux.
Used internally. (Configurable.) Not used starting with Solaris 10 OS.
The HotSpot VM does not handle this signal. Instead it calls the abort function after fatal error handling. If an application uses this signal then it should terminate the process to preserve the expected semantics.

6.1.1 Reducing Signal Usage

The -Xrs option instructs the HotSpot VM to reduce its signal usage. With this option fewer signals are used, although the VM installs its own signal handler for essential signals such as SIGSEGV. In the above table the signals tagged as optional are not used when the -Xrs option is specified. Specifying this option means that the shutdown hook mechanism will not execute if the process receives a SIGQUIT, SIGTERM, SIGINT, or SIGHUP. Shutdown hooks will execute, as expected, if the VM terminates normally (last non-daemon thread completes or the System.exit method is used).

6.1.2 Alternative Signals

On Solaris 8 and 9 OS, the -XX:+UseAltSigs option can be used to instruct the HotSpot VM to use alternative signals to SIGUSR1 and SIGUSR2. Starting with Solaris 10 OS, this option is ignored, as the operating system reserves two additional signals (called SIGJVM1 and SIGJVM2).

On Linux, the handler for SIGUSR1 cannot be overridden. SIGUSR2 is used to implement suspend and resume. However it is possible to specify an alternative signal to be used instead of SIGUSR2. This is done by specifying the _JAVA_SR_SIGNUM environment variable. If this environment variable is set, it must be set to a value larger than the maximum of SIGSEGV and SIGBUS.

6.1.3 Signal Chaining

If an application with native code requires its own signal handlers, then it might need to be used with the signal chaining facility. The signal chaining facility offers the following features:

Note that SIGUSR1 cannot be chained. If an application attempts to chain this signal on Solaris OS, then the HotSpot VM terminates with the following fatal error:

Signal chaining detected for VM interrupt signal, try -XX:+UseAltSigs

In addition, the SIGQUIT, SIGTERM, SIGINT, and SIGHUP signals cannot be chained. If the application needs to handle these signals, consider using the -Xrs option.

On Solaris OS, the SIGUSR2 signal can be chained, but only for non-Java and non-VM threads; that is, it can only be used for native threads created by the application that do not attach to the VM.

6.2 Exception Handling on Windows

On Windows, an exception is an event that occurs during the execution of a program. There are two kinds of exceptions: hardware exceptions and software exceptions. Hardware exceptions are comparable to signals such as SIGSEGV and SIGKILL on Solaris OS and Linux. Software exceptions are initiated explicitly by applications or the operating system using the RaiseException() API.

On Windows, the mechanism for handling both hardware and software exceptions is called structured exception handling (SEH). This is stack frame-based exception handling similar to the C++ and Java exception handling mechanism. In C++ the __try and __except keywords are used to guard a section of code that might result in an exception, as in the following example:

__try {
     // guarded body of code
 } __except (filter-expression) {
     // exception-handler block

The __except block is filtered by a filter expression that uses an exception code (integer code returned by the GetExceptionCode() API), or exception information (GetExceptionInformation() API), or both.

The filter expression should evaluate to one of the following values:

The __try and __finally keywords are used to construct a termination handler as shown below.

__try { 
    // guarded body of code  
} __finally { 
    // __finally block  

When control leaves the __try block (after exception or without exception), the __finally block is executed. Inside the __finally block, the AbnormalTermination() API can be called to test whether control continued after the exception or not.

Windows programs can also install a top-level unhandled exception filter function to catch exceptions that are not handled in a __try/__except block. This function is installed on a process-wide basis using the SetUnhandledExceptionFilter() API. If there is no handler for an exception, then UnhandledExceptionFilter() is called, and this will call the top-level unhandled exception filter function, if any, to catch that exception. This function also shows a message box to notify the user about the unhandled exception.

Windows exceptions are comparable to Unix synchronous signals that are attributable to the current execution stream. In Windows, asynchronous events such as console events (for example, the user pressing Ctrl-C at the console) are handled by the console control handler registered using the SetConsoleCtlHandler() API.

If an application uses the signal() API on Windows, then the C runtime library (CRT) maps both Windows exceptions and console events to appropriate signals or C runtime errors. For example, CRT maps Ctrl-C to SIGINT and all other console events to SIGBREAK. Similarly, if you register the SIGSEGV handler, the C runtime library translates the corresponding exception to a signal. The CRT library startup code implements a __try/__except block around the main() function. The CRT's exception filter function (named _XcptFilter) maps the Win32 exceptions to signals and dispatches signals to their appropriate handlers. If a signal's handler is set to SIG_DFL (default handling), then _XcptFilter calls UnhandledExceptionFilter.

With Windows XP or Windows 2003, the vectored exception handling mechanism can also be used. Vectored handlers are not frame-based handlers. A program can register zero or more vectored exception handlers using the AddVectoredExceptionHandler API. Vectored handlers are invoked before structured exception handlers, if any, are invoked, regardless of where the exception occurred.

Vectored exception handler returns one of the following values:

Refer to the Microsoft web site at http://www.microsoft.com for further information on Windows exception handling.

6.2.1 Signal Handling in the HotSpot Virtual Machine

The HotSpot VM installs a top-level exception handler using the SetUnhandledExceptionFilter API (or the AddVectoredExceptionHandler API for 64-bit) during VM initialization.

It also installs win32 SEH using a __try /__except block in C++ around the thread (internal) start function call for each thread created.

Finally, it installs an exception handler around JNI functions.

If an application must handle structured exceptions in JNI code, it can use __try /__except statements in C++. However, if it must use the vectored exception handler in JNI code then the handler must return EXCEPTION_CONTINUE_SEARCH to continue to the VMs exception handler.

In general, there are two categories of situations in which exceptions arise:

6.2.2 Console Handlers

The HotSpot Virtual Machine registers console events as shown in the following table.

Console Event
Terminate process. (optional)
Used by the shutdown hook mechanism when the VM is terminated abnormally. (optional)
Thread dump support. To dump Java stack traces at the standard error stream. (optional)

If an application must register its own console handler, then the -Xrs option can be used. With this option, shutdown hooks are not run on SIGTERM (with above mapping of events) and thread dump support is not available on SIGBREAK (with above mapping Ctrl-Break event).