The information on these pages may be out of date, or may refer to
resources that have moved or have been made read-only.
For more information please refer to the Apache Attic
Apache Harmony Crash and signals handler (CH) is used for a platform-independent handling of runtime errors and exceptions in a program. CH may be used as a portable signal abstraction layer, but its main purpose is to provide a facility for post mortem analysis of managed runtime applications that use just-in-time compilers (JITs) to generate user application executable code. This makes crash handling library of Apache Harmony unique among other facilities because they cannot analyze the native stack of compiled code. An application that does not utilize runtime compilers can use this library as well, such an application would provide no information about compiled methods to crash handler and therefore it would analyze only its native code.
CH – acronym used to identify the component crash and signals handling of Apache Harmony.
Signal – an event delivered by the operating system to an application under certain conditions. Signal is a name traditionally used on UNIX systems. On Windows* OS, such events are called exceptions. In this document, the term signal is used to define both signal and exception depending on the target platform, unless stated otherwise.
Upon its initialization, the crash handler library registers to receive a big number of signals (exceptions on Windows), all of which are usually considered fatal for most applications. CH allows the application to make a decision whether the crash sequence should be started when a signal is delivered to the application. To filter such events, the application can register callbacks for each signal type that it is interested in, so the execution flow follows one of these paths:
CH outputs information about the location of the crash based on the crash information flags that the application set. These flags control the amount of information that CH prints. In addition, the application may specify its own callbacks to dump some application specific information, e.g. its data tables.
The following sequence describes signal handling in detail.
The crash handler API is defined in port_crash_handler.h and port_frame_info.h header files. The API consists of 2 parts, initialization and output management.
Initialization is the main part of the CH library. It is done with a function port_init_crash_handler(). To process signals in a specific way, the application must supply an array of signal handling callbacks (see section 2) and a pointer to the stack iteration function, which performs lookup through compiled methods and returns method names and other relevant information (see section 3.2 for details).
To iterate over compiled methods, CH uses the application defined function. It has quite complicated semantics, for exact specification see port_frame_info.h header file.
When a signal is considered fatal, CH prints the execution stack for the crashed thread. For that, CH identifies methods in the stack via the IP register and finds out whether the crash happened in a compiled method using stack iteration callback in the following algorithm:
CH has a set of flags that control its output in case of a crash. The application may specify its own mode of output using the port_crash_handler_set_flags() function. These flags may be changed at any time to adjust the output of information depending on the crash that happened. For example, for a failed assertion it is probably not necessary to print a register context because it gives no useful information.
Additionally, CH allows the application to dump additional information in case of a crash. The application may add multiple callbacks using the port_crash_handler_add_action() function. Each application component may then dump its internal data separately.
When the application shuts down, it may unregister CH so that all signal handlers are assigned their default values. This option is useful at the late stages of shutdown when the application cannot handle crashes and output any application-specific data (e.g. all tables are already de-allocated). To unregister the crash handler, application may use the port_shutdown_crash_handler() function.
The crash handler has some design decisions that may affect its usage in specific scenarios. This section describes them.
Application callbacks for the signals are called when the OS signal handler has already exited. When CH starts processing the signal, some signal information needed is already lost. Because storing this information for every received signal may reduce the application performance, in case of a crash, CH sets thread-local indicators and continues execution in the original register context to catch the same signal again and perform required crash processing inside the OS signal handler. This technique does not work for the stack overflow exception on Windows, because access to the protected memory region which caused the signal is restored automatically in OS signal delivery. The problem affects creating minidumps on Windows and displaying a message box for calling a debugger. This limitation can disappear together with fixing HARMONY-5617.
In the previous CH implementation, stack iteration was based on the compiled stack. Even if native stack unwinding was not done, stack iteration continued and printed the whole compiled stack even with no native stack information; the whole compiled stack was printed with or without native stack information. In the current CH implementation, native stack unwinding takes a lead in stack iteration. When the current frame cannot be unwound with the application callback and the native stack unwinding algorithm, the iteration stops, even if more compiled frames are present.
Core dump is created on Linux when the default signal handler is called for some signals. When application requests to call the debugger in case of a crash, the application does not actually crash, but continues execution as a debugged application. Therefore, when the debugger is called on Linux, core dump is not generated.
The Harmony Crash Handler is mostly designed as a crash handler for a standalone application. There may be problems using it with libraries linked to another application, which may have its own signal handling routines.
On Windows, CH uses VEH (Vectored Exception Handler) for centralized signals catching. This functionality is unavailable on Windows versions earlier than Windows XP/Windows Server 2003, so CH cannot be used on Windows 2000 and earlier.