diff options
Diffstat (limited to 'third_party/abseil_cpp/absl/debugging/stacktrace.h')
| -rw-r--r-- | third_party/abseil_cpp/absl/debugging/stacktrace.h | 231 |
1 files changed, 0 insertions, 231 deletions
diff --git a/third_party/abseil_cpp/absl/debugging/stacktrace.h b/third_party/abseil_cpp/absl/debugging/stacktrace.h deleted file mode 100644 index 0ec0ffdabd42..000000000000 --- a/third_party/abseil_cpp/absl/debugging/stacktrace.h +++ /dev/null @@ -1,231 +0,0 @@ -// Copyright 2018 The Abseil Authors. -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// https://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// -// ----------------------------------------------------------------------------- -// File: stacktrace.h -// ----------------------------------------------------------------------------- -// -// This file contains routines to extract the current stack trace and associated -// stack frames. These functions are thread-safe and async-signal-safe. -// -// Note that stack trace functionality is platform dependent and requires -// additional support from the compiler/build system in most cases. (That is, -// this functionality generally only works on platforms/builds that have been -// specifically configured to support it.) -// -// Note: stack traces in Abseil that do not utilize a symbolizer will result in -// frames consisting of function addresses rather than human-readable function -// names. (See symbolize.h for information on symbolizing these values.) - -#ifndef ABSL_DEBUGGING_STACKTRACE_H_ -#define ABSL_DEBUGGING_STACKTRACE_H_ - -#include "absl/base/config.h" - -namespace absl { -ABSL_NAMESPACE_BEGIN - -// GetStackFrames() -// -// Records program counter values for up to `max_depth` frames, skipping the -// most recent `skip_count` stack frames, stores their corresponding values -// and sizes in `results` and `sizes` buffers, and returns the number of frames -// stored. (Note that the frame generated for the `absl::GetStackFrames()` -// routine itself is also skipped.) -// -// Example: -// -// main() { foo(); } -// foo() { bar(); } -// bar() { -// void* result[10]; -// int sizes[10]; -// int depth = absl::GetStackFrames(result, sizes, 10, 1); -// } -// -// The current stack frame would consist of three function calls: `bar()`, -// `foo()`, and then `main()`; however, since the `GetStackFrames()` call sets -// `skip_count` to `1`, it will skip the frame for `bar()`, the most recently -// invoked function call. It will therefore return 2 and fill `result` with -// program counters within the following functions: -// -// result[0] foo() -// result[1] main() -// -// (Note: in practice, a few more entries after `main()` may be added to account -// for startup processes.) -// -// Corresponding stack frame sizes will also be recorded: -// -// sizes[0] 16 -// sizes[1] 16 -// -// (Stack frame sizes of `16` above are just for illustration purposes.) -// -// Stack frame sizes of 0 or less indicate that those frame sizes couldn't -// be identified. -// -// This routine may return fewer stack frame entries than are -// available. Also note that `result` and `sizes` must both be non-null. -extern int GetStackFrames(void** result, int* sizes, int max_depth, - int skip_count); - -// GetStackFramesWithContext() -// -// Records program counter values obtained from a signal handler. Records -// program counter values for up to `max_depth` frames, skipping the most recent -// `skip_count` stack frames, stores their corresponding values and sizes in -// `results` and `sizes` buffers, and returns the number of frames stored. (Note -// that the frame generated for the `absl::GetStackFramesWithContext()` routine -// itself is also skipped.) -// -// The `uc` parameter, if non-null, should be a pointer to a `ucontext_t` value -// passed to a signal handler registered via the `sa_sigaction` field of a -// `sigaction` struct. (See -// http://man7.org/linux/man-pages/man2/sigaction.2.html.) The `uc` value may -// help a stack unwinder to provide a better stack trace under certain -// conditions. `uc` may safely be null. -// -// The `min_dropped_frames` output parameter, if non-null, points to the -// location to note any dropped stack frames, if any, due to buffer limitations -// or other reasons. (This value will be set to `0` if no frames were dropped.) -// The number of total stack frames is guaranteed to be >= skip_count + -// max_depth + *min_dropped_frames. -extern int GetStackFramesWithContext(void** result, int* sizes, int max_depth, - int skip_count, const void* uc, - int* min_dropped_frames); - -// GetStackTrace() -// -// Records program counter values for up to `max_depth` frames, skipping the -// most recent `skip_count` stack frames, stores their corresponding values -// in `results`, and returns the number of frames -// stored. Note that this function is similar to `absl::GetStackFrames()` -// except that it returns the stack trace only, and not stack frame sizes. -// -// Example: -// -// main() { foo(); } -// foo() { bar(); } -// bar() { -// void* result[10]; -// int depth = absl::GetStackTrace(result, 10, 1); -// } -// -// This produces: -// -// result[0] foo -// result[1] main -// .... ... -// -// `result` must not be null. -extern int GetStackTrace(void** result, int max_depth, int skip_count); - -// GetStackTraceWithContext() -// -// Records program counter values obtained from a signal handler. Records -// program counter values for up to `max_depth` frames, skipping the most recent -// `skip_count` stack frames, stores their corresponding values in `results`, -// and returns the number of frames stored. (Note that the frame generated for -// the `absl::GetStackFramesWithContext()` routine itself is also skipped.) -// -// The `uc` parameter, if non-null, should be a pointer to a `ucontext_t` value -// passed to a signal handler registered via the `sa_sigaction` field of a -// `sigaction` struct. (See -// http://man7.org/linux/man-pages/man2/sigaction.2.html.) The `uc` value may -// help a stack unwinder to provide a better stack trace under certain -// conditions. `uc` may safely be null. -// -// The `min_dropped_frames` output parameter, if non-null, points to the -// location to note any dropped stack frames, if any, due to buffer limitations -// or other reasons. (This value will be set to `0` if no frames were dropped.) -// The number of total stack frames is guaranteed to be >= skip_count + -// max_depth + *min_dropped_frames. -extern int GetStackTraceWithContext(void** result, int max_depth, - int skip_count, const void* uc, - int* min_dropped_frames); - -// SetStackUnwinder() -// -// Provides a custom function for unwinding stack frames that will be used in -// place of the default stack unwinder when invoking the static -// GetStack{Frames,Trace}{,WithContext}() functions above. -// -// The arguments passed to the unwinder function will match the -// arguments passed to `absl::GetStackFramesWithContext()` except that sizes -// will be non-null iff the caller is interested in frame sizes. -// -// If unwinder is set to null, we revert to the default stack-tracing behavior. -// -// ***************************************************************************** -// WARNING -// ***************************************************************************** -// -// absl::SetStackUnwinder is not suitable for general purpose use. It is -// provided for custom runtimes. -// Some things to watch out for when calling `absl::SetStackUnwinder()`: -// -// (a) The unwinder may be called from within signal handlers and -// therefore must be async-signal-safe. -// -// (b) Even after a custom stack unwinder has been unregistered, other -// threads may still be in the process of using that unwinder. -// Therefore do not clean up any state that may be needed by an old -// unwinder. -// ***************************************************************************** -extern void SetStackUnwinder(int (*unwinder)(void** pcs, int* sizes, - int max_depth, int skip_count, - const void* uc, - int* min_dropped_frames)); - -// DefaultStackUnwinder() -// -// Records program counter values of up to `max_depth` frames, skipping the most -// recent `skip_count` stack frames, and stores their corresponding values in -// `pcs`. (Note that the frame generated for this call itself is also skipped.) -// This function acts as a generic stack-unwinder; prefer usage of the more -// specific `GetStack{Trace,Frames}{,WithContext}()` functions above. -// -// If you have set your own stack unwinder (with the `SetStackUnwinder()` -// function above, you can still get the default stack unwinder by calling -// `DefaultStackUnwinder()`, which will ignore any previously set stack unwinder -// and use the default one instead. -// -// Because this function is generic, only `pcs` is guaranteed to be non-null -// upon return. It is legal for `sizes`, `uc`, and `min_dropped_frames` to all -// be null when called. -// -// The semantics are the same as the corresponding `GetStack*()` function in the -// case where `absl::SetStackUnwinder()` was never called. Equivalents are: -// -// null sizes | non-nullptr sizes -// |==========================================================| -// null uc | GetStackTrace() | GetStackFrames() | -// non-null uc | GetStackTraceWithContext() | GetStackFramesWithContext() | -// |==========================================================| -extern int DefaultStackUnwinder(void** pcs, int* sizes, int max_depth, - int skip_count, const void* uc, - int* min_dropped_frames); - -namespace debugging_internal { -// Returns true for platforms which are expected to have functioning stack trace -// implementations. Intended to be used for tests which want to exclude -// verification of logic known to be broken because stack traces are not -// working. -extern bool StackTraceWorksForTest(); -} // namespace debugging_internal -ABSL_NAMESPACE_END -} // namespace absl - -#endif // ABSL_DEBUGGING_STACKTRACE_H_ |