Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kBackTrace.h
Go to the documentation of this file.
1 /**
2 * @file kBackTrace.h
3 * @brief Declares the kBackTrace class.
4 *
5 * @internal
6 * Copyright (C) 2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_BACK_TRACE_H
11 #define K_API_BACK_TRACE_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kBackTrace
19 * @extends kObject
20 * @ingroup kApi-Utils
21 * @brief Represents a snapshot of the active functions on a call stack.
22 */
23 //typedef kObject kBackTrace; --forward-declared in kApiDef.x.h
24
25 /**
26 * Constructs a kBackTrace object.
27 *
28 * The constructed back trace object will be initially empty; use the Capture method to acquire
29 * trace information.
30 *
31 * @public @memberof kBackTrace
32 * @param trace Receives constructed back trace object.
33 * @param allocator Memory allocator (or kNULL for default).
34 * @return Operation status.
35 */
36 kFx(kStatus) kBackTrace_Construct(kBackTrace* trace, kAlloc allocator);
37
38 /**
39 * Captures back trace information.
40 *
41 * If supported by the underlying platform, the set of active functions on the call stack
42 * will be captured. For platforms that do not support back trace, the capture operation will
43 * succeed but the resulting trace will be empty.
44 *
45 * @public @memberof kBackTrace
46 * @param trace Back trace object.
47 * @param skip Count of recent functions to omit from trace.
48 * @return Operation status.
49 */
50 kFx(kStatus) kBackTrace_Capture(kBackTrace trace, kSize skip);
51
52 /**
53 * Count of function calls in the captured trace.
54 *
55 * @public @memberof kBackTrace
56 * @param trace Back trace object.
57 * @return Count of function calls in trace.
58 */
59 kFx(kSize) kBackTrace_Depth(kBackTrace trace);
60
61 /**
62 * Creates a list of descriptive strings, one for each line in the trace.
63 *
64 * @public @memberof kBackTrace
65 * @param trace Back trace object.
66 * @param lines Receives list of descriptive strings.
67 * @param allocator Memory allocator (or kNULL for default).
68 * @return Operation status.
69 */
70 kFx(kStatus) kBackTrace_Describe(kBackTrace trace, kArrayList* lines, kAlloc allocator);
71
72 kEndHeader()
73
74 #include <kApi/Utils/kBackTrace.x.h>
75
76 #endif
kBackTrace::kBackTrace_Describe
kStatus kBackTrace_Describe(kBackTrace trace, kArrayList *lines, kAlloc allocator)
Creates a list of descriptive strings, one for each line in the trace.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kBackTrace::kBackTrace_Capture
kStatus kBackTrace_Capture(kBackTrace trace, kSize skip)
Captures back trace information.
kApiDef.h
Essential API declarations.
kBackTrace::kBackTrace_Depth
kSize kBackTrace_Depth(kBackTrace trace)
Count of function calls in the captured trace.
kBackTrace
Represents a snapshot of the active functions on a call stack.
kBackTrace::kBackTrace_Construct
kStatus kBackTrace_Construct(kBackTrace *trace, kAlloc allocator)
Constructs a kBackTrace object.
kArrayList
Represents a list implemented with a dynamic array.
kStatus
Represents an enumeration of error codes.