folly/experimental/exception_tracer/StackTrace.h

   1 /*
   2  * Copyright 2013 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef FOLLY_EXPERIMENTAL_EXCEPTION_TRACER_STACKTRACE_H_
  19 #define FOLLY_EXPERIMENTAL_EXCEPTION_TRACER_STACKTRACE_H_
  20
  21 #include <stddef.h>
  22 #include <stdint.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 typedef struct StackTrace {
  29   uintptr_t* frameIPs;  /* allocated with malloc() */
  30   size_t frameCount;
  31 } StackTrace;
  32
  33 /**
  34  * Get the current stack trace, allocating trace->frameIPs using malloc().
  35  * Skip the topmost "skip" frames.
  36  * Return 0 on success, a negative value on error.
  37  * On error, trace->frameIPs is NULL.
  38  */
  39 int getCurrentStackTrace(size_t skip, StackTrace* trace);
  40
  41 /**
  42  * Free data allocated in a StackTrace object.
  43  */
  44 void destroyStackTrace(StackTrace* trace);
  45
  46 /**
  47  * A stack of stack traces.
  48  */
  49 typedef struct StackTraceStack {
  50   StackTrace trace;
  51   struct StackTraceStack* next;
  52 } StackTraceStack;
  53
  54 /**
  55  * Push the current stack trace onto the stack.
  56  * Return 0 on success, a negative value on error.
  57  * On error, the stack is unchanged.
  58  */
  59 int pushCurrentStackTrace(size_t skip, StackTraceStack** head);
  60
  61 /**
  62  * Pop (and destroy) the top stack trace from the stack.
  63  */
  64 void popStackTrace(StackTraceStack** head);
  65
  66 /**
  67  * Completely empty the stack, destroying everything.
  68  */
  69 void clearStack(StackTraceStack** head);
  70
  71 /**
  72  * Move the top stack trace from one stack to another.
  73  * Return 0 on success, a negative value on error (if the source stack is
  74  * empty)
  75  */
  76 int moveTop(StackTraceStack** from, StackTraceStack** to);
  77
  78 /**
  79  * Initialize the stack tracing code.
  80  */
  81 void initStackTrace();
  82
  83 #ifdef __cplusplus
  84 }  /* extern "C" */
  85 #endif
  86
  87 #endif /* FOLLY_EXPERIMENTAL_EXCEPTION_TRACER_STACKTRACE_H_ */
  88