- be60293bacf8d17861853a73c751b4a74534b049 Update header file for failure_signal_handler.h by Tom Manshreck <shreck@google.com>

  - 83dbeb97cb3874932a4159f2f287c5b2cca7089b Fix for MSVC warning C4244 about "conversion from 'int' t... by Abseil Team <absl-team@google.com>

GitOrigin-RevId: be60293bacf8d17861853a73c751b4a74534b049
Change-Id: If8a91fa3edca47f349662cb214fde380c65802bb

1 files changed, 62 insertions, 48 deletions

diff --git a/absl/debugging/failure_signal_handler.h b/absl/debugging/failure_signal_handler.h
index 17522f00b13f..c57954e5875c 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 {