summaryrefslogtreecommitdiff
path: root/absl/debugging
diff options
context:
space:
mode:
Diffstat (limited to 'absl/debugging')
-rw-r--r--absl/debugging/failure_signal_handler.h110
1 files changed, 62 insertions, 48 deletions
diff --git a/absl/debugging/failure_signal_handler.h b/absl/debugging/failure_signal_handler.h
index 17522f00..c57954e5 100644
--- a/absl/debugging/failure_signal_handler.h
+++ b/absl/debugging/failure_signal_handler.h
@@ -1,4 +1,3 @@
-//
// Copyright 2018 The Abseil Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,85 +12,100 @@
// See the License for the specific language governing permissions and
// limitations under the License.
//
-
-// This module allows the programmer to install a signal handler that
-// dumps useful debugging information (like a stacktrace) on program
-// failure. To use this functionality, call
-// absl::InstallFailureSignalHandler() very early in your program,
-// usually in the first few lines of main():
+// -----------------------------------------------------------------------------
+// File: failure_signal_handler.h
+// -----------------------------------------------------------------------------
+//
+// This file configures the Abseil *failure signal handler* to capture and dump
+// useful debugging information (such as a stacktrace) upon program failure.
+//
+// To use the failure signal handler, call `absl::InstallFailureSignalHandler()`
+// very early in your program, usually in the first few lines of main():
//
// int main(int argc, char** argv) {
+// // Initialize the symbolizer to get a human-readable stack trace
// absl::InitializeSymbolizer(argv[0]);
+//
// absl::FailureSignalHandlerOptions options;
// absl::InstallFailureSignalHandler(options);
// DoSomethingInteresting();
// return 0;
// }
+//
+// Any program that raises a fatal signal (such as `SIGSEGV`, `SIGILL`,
+// `SIGFPE`, `SIGABRT`, `SIGTERM`, `SIGBUG`, and `SIGTRAP`) will call the
+// installed failure signal handler and provide debugging information to stderr.
+//
+// Note that you should *not* install the Abseil failure signal handler more
+// than once. You may, of course, have another (non-Abseil) failure signal
+// handler installed (which would be triggered if Abseil's failure signal
+// handler sets `call_previous_handler` to `true`).
#ifndef ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_
#define ABSL_DEBUGGING_FAILURE_SIGNAL_HANDLER_H_
namespace absl {
-// Options struct for absl::InstallFailureSignalHandler().
+// FailureSignalHandlerOptions
+//
+// Struct for holding `absl::InstallFailureSignalHandler()` configuration
+// options.
struct FailureSignalHandlerOptions {
- // If true, try to symbolize the stacktrace emitted on failure.
+ // If true, try to symbolize the stacktrace emitted on failure, provided that
+ // you have initialized a symbolizer for that purpose. (See symbolize.h for
+ // more information.)
bool symbolize_stacktrace = true;
- // If true, try to run signal handlers on an alternate stack (if
- // supported on the given platform). This is useful in the case
- // where the program crashes due to a stack overflow. By running on
- // a alternate stack, the signal handler might be able to run even
- // when the normal stack space has been exausted. The downside of
- // using an alternate stack is that extra memory for the alternate
- // stack needs to be pre-allocated.
+ // If true, try to run signal handlers on an alternate stack (if supported on
+ // the given platform). An alternate stack is useful for program crashes due
+ // to a stack overflow; by running on a alternate stack, the signal handler
+ // may run even when normal stack space has been exausted. The downside of
+ // using an alternate stack is that extra memory for the alternate stack needs
+ // to be pre-allocated.
bool use_alternate_stack = true;
- // If positive, FailureSignalHandler() sets an alarm to be delivered
- // to the program after this many seconds, which will immediately
- // abort the program. This is useful in the potential case where
- // FailureSignalHandler() itself is hung or deadlocked.
+ // If positive, indicates the number of seconds after which the failure signal
+ // handler is invoked to abort the program. Setting such an alarm is useful in
+ // cases where the failure signal handler itself may become hung or
+ // deadlocked.
int alarm_on_failure_secs = 3;
- // If false, after absl::FailureSignalHandler() runs, the signal is
- // raised to the default handler for that signal (which normally
- // terminates the program).
+ // If true, call the previously registered signal handler for the signal that
+ // was received (if one was registered) after the existing signal handler
+ // runs. This mechanism can be used to chain signal handlers together.
//
- // If true, after absl::FailureSignalHandler() runs, it will call
- // the previously registered signal handler for the signal that was
- // received (if one was registered). This can be used to chain
- // signal handlers.
+ // If false, the signal is raised to the default handler for that signal
+ // (which normally terminates the program).
//
- // IMPORTANT: If true, the chained fatal signal handlers must not
- // try to recover from the fatal signal. Instead, they should
- // terminate the program via some mechanism, like raising the
- // default handler for the signal, or by calling _exit().
- // absl::FailureSignalHandler() may put parts of the Abseil
- // library into a state that cannot be recovered from.
+ // IMPORTANT: If true, the chained fatal signal handlers must not try to
+ // recover from the fatal signal. Instead, they should terminate the program
+ // via some mechanism, like raising the default handler for the signal, or by
+ // calling `_exit()`. Note that the failure signal handler may put parts of
+ // the Abseil library into a state from which they cannot recover.
bool call_previous_handler = false;
- // If not null, this function may be called with a std::string argument
- // containing failure data. This function is used as a hook to write
- // the failure data to a secondary location, for instance, to a log
- // file. This function may also be called with a null data
- // argument. This is a hint that this is a good time to flush any
- // buffered data before the program may be terminated. Consider
+ // If non-null, indicates a pointer to a callback function that will be called
+ // upon failure, with a std::string argument containing failure data. This function
+ // may be used as a hook to write failure data to a secondary location, such
+ // as a log file. This function may also be called with null data, as a hint
+ // to flush any buffered data before the program may be terminated. Consider
// flushing any buffered data in all calls to this function.
//
- // Since this function runs in a signal handler, it should be
+ // Since this function runs within a signal handler, it should be
// async-signal-safe if possible.
// See http://man7.org/linux/man-pages/man7/signal-safety.7.html
void (*writerfn)(const char*) = nullptr;
};
-// Installs a signal handler for the common failure signals SIGSEGV,
-// SIGILL, SIGFPE, SIGABRT, SIGTERM, SIGBUG, and SIGTRAP (if they
-// exist on the given platform). The signal handler dumps program
-// failure data in a unspecified format to stderr. The data dumped by
-// the signal handler includes information that may be useful in
-// debugging the failure. This may include the program counter, a
-// stacktrace, and register information on some systems. Do not rely
-// on the exact format of the output; it is subject to change.
+// InstallFailureSignalHandler()
+//
+// Installs a signal handler for the common failure signals `SIGSEGV`, `SIGILL`,
+// `SIGFPE`, `SIGABRT`, `SIGTERM`, `SIGBUG`, and `SIGTRAP` (provided they exist
+// on the given platform). The failure signal handler dumps program failure data
+// useful for debugging in an unspecified format to stderr. This data may
+// include the program counter, a stacktrace, and register information on some
+// systems; do not rely on an exact format for the output, as it is subject to
+// change.
void InstallFailureSignalHandler(const FailureSignalHandlerOptions& options);
namespace debugging_internal {