Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kDebugAlloc.h
Go to the documentation of this file.
1 /**
2 * @file kDebugAlloc.h
3 * @brief Declares the kDebugAlloc class.
4 *
5 * @internal
6 * Copyright (C) 2012-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_DEBUG_ALLOC_H
11 #define K_API_DEBUG_ALLOC_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @struct kDebugAllocation
19 * @extends kValue
20 * @ingroup kApi-Utils
21 * @brief Allocation record used by kDebugAlloc
22 */
23 typedef struct kDebugAllocation
24 {
25 kByte* data; ///< User data pointer.
26 kSize size; ///< Size of memory allocation.
27 k64u index; ///< Incremented with each allocation.
28 kArrayList trace; ///< Backtrace at point of allocation -- kArrayList<kString>.
29 } kDebugAllocation;
30
31 /**
32 * @class kDebugAlloc
33 * @extends kAlloc
34 * @ingroup kApi-Utils
35 * @brief Debug memory allocator; tracks allocations and can report leaks.
36 */
37 //typedef kAlloc kDebugAlloc; --forward-declared in kApiDef.x.h
38
39 /**
40 * Constructs a new kDebugAlloc allocator.
41 *
42 * @public @memberof kDebugAlloc
43 * @param object Receives the constructed kDebugAlloc object.
44 * @param name Descriptive name for this memory allocator.
45 * @param allocator Memory allocator to use for internal allocations (or kNULL for default).
46 * @return Operation status.
47 */
48 kFx(kStatus) kDebugAlloc_Construct(kDebugAlloc* object, const kChar* name, kAlloc allocator);
49
50 /**
51 * Clears all outstanding allocations (resets allocator).
52 *
53 * @public @memberof kDebugAlloc
54 * @param object Memory allocator.
55 * @return Operation status.
56 */
57 kFx(kStatus) kDebugAlloc_Clear(kDebugAlloc object);
58
59 /**
60 * Returns the total amount of memory that has been allocated and not yet freed.
61 *
62 * @public @memberof kDebugAlloc
63 * @param object Memory allocator.
64 * @return Amount of allocated memory.
65 */
66 kFx(kSize) kDebugAlloc_Allocated(kDebugAlloc object);
67
68 /**
69 * Returns a memory checkpoint value, used in conjunction with allocation logging functions.
70 *
71 * @public @memberof kDebugAlloc
72 * @param object Memory allocator.
73 * @return Memory checkpoint value.
74 * @see kDebugAlloc_Allocations, kDebugAlloc_LogAllocations
75 */
76 kFx(k64u) kDebugAlloc_Checkpoint(kDebugAlloc object);
77
78 /**
79 * Gets a list of all outstanding memory allocations performed after the given checkpoint.
80 *
81 * @public @memberof kDebugAlloc
82 * @param object Memory allocator.
83 * @param since Memory checkpoint (or zero for beginning).
84 * @param history Receives list of outstanding allocations.
85 * @param alloc Allocator for history list (or kNULL for default).
86 * @return Operation status.
87 * @see kDebugAlloc_Checkpoint
88 */
89 kFx(kStatus) kDebugAlloc_Allocations(kDebugAlloc object, k64u since, kArrayList* history, kAlloc alloc);
90
91 /**
92 * Logs all outstanding memory allocations performed after the given checkpoint (using kLogf).
93 *
94 * @public @memberof kDebugAlloc
95 * @param object Memory allocator.
96 * @param since Memory checkpoint (or zero for beginning).
97 * @return Operation status.
98 * @see kDebugAlloc_Checkpoint
99 */
100 kFx(kStatus) kDebugAlloc_LogAllocations(kDebugAlloc object, k64u since);
101
102 /**
103 * Makes note of outstanding allocations that appear to be objects from any currently-loaded assembly.
104 *
105 * This function records information about outstanding allocations that appear to be objects, for later use
106 * when logging leak information.
107 *
108 * @public @memberof kDebugAlloc
109 * @param object Memory allocator.
110 * @param since Memory checkpoint (or zero for beginning).
111 * @return Operation status.
112 * @see kDebugAlloc_LogAllocations, kDebugAlloc_DetectLeakedAssemblyObjects
113 */
114 kFx(kStatus) kDebugAlloc_DetectLeakedObjects(kDebugAlloc object, k64u since);
115
116 /**
117 * Makes note of outstanding allocations that appear to be objects associated with the specified assembly.
118 *
119 * This function records information about outstanding allocations that appear to be objects, for later use
120 * when logging leak information.
121 *
122 * @public @memberof kDebugAlloc
123 * @param object Memory allocator.
124 * @param since Memory checkpoint (or zero for beginning).
125 * @param assembly Assembly associated with objects.
126 * @return Operation status.
127 * @see kDebugAlloc_LogAllocations, kDebugAlloc_DetectLeakedObjects
128 */
129 kFx(kStatus) kDebugAlloc_DetectLeakedAssemblyObjects(kDebugAlloc object, k64u since, kAssembly assembly);
130
131 /**
132 * Registers a user-defined function that is called whenever a memory allocation occurs.
133 *
134 * The args parameter of the callback will receive a pointer to a kDebugAllocation structure
135 * representing the memory allocation.
136 *
137 * @public @memberof kDebugAlloc
138 * @param object Memory allocator.
139 * @param function Callback function.
140 * @param receiver Callback receiver.
141 * @return Operation status.
142 */
143 kFx(kStatus) kDebugAlloc_SetAllocListener(kDebugAlloc object, kCallbackFx function, kPointer receiver);
144
145 kEndHeader()
146
147 #include <kApi/Utils/kDebugAlloc.x.h>
148
149 #endif
kDebugAlloc::kDebugAlloc_LogAllocations
kStatus kDebugAlloc_LogAllocations(kDebugAlloc object, k64u since)
Logs all outstanding memory allocations performed after the given checkpoint (using kLogf)...
kDebugAlloc::kDebugAlloc_DetectLeakedObjects
kStatus kDebugAlloc_DetectLeakedObjects(kDebugAlloc object, k64u since)
Makes note of outstanding allocations that appear to be objects from any currently-loaded assembly...
k64u
Represents a 64-bit unsigned integer.
kDebugAllocation::size
kSize size
Size of memory allocation.
Definition: kDebugAlloc.h:26
kCallbackFx
kStatus(kCall * kCallbackFx)(kPointer receiver, kPointer sender, void *args)
Callback signature for a generic event handler.
Definition: kApiDef.h:1030
kAssembly
Represents a library of types.
kPointer
Represents a void pointer.
kDebugAllocation::index
k64u index
Incremented with each allocation.
Definition: kDebugAlloc.h:27
kDebugAlloc::kDebugAlloc_Allocations
kStatus kDebugAlloc_Allocations(kDebugAlloc object, k64u since, kArrayList *history, kAlloc alloc)
Gets a list of all outstanding memory allocations performed after the given checkpoint.
kDebugAlloc
Debug memory allocator; tracks allocations and can report leaks.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kDebugAllocation::data
kByte * data
User data pointer.
Definition: kDebugAlloc.h:25
kDebugAllocation::trace
kArrayList trace
Backtrace at point of allocation – kArrayList.
Definition: kDebugAlloc.h:28
kChar
Represents a single unit (byte) in a UTF-8 character.
kByte
Represents a byte on the current platform.
kDebugAlloc::kDebugAlloc_Clear
kStatus kDebugAlloc_Clear(kDebugAlloc object)
Clears all outstanding allocations (resets allocator).
kDebugAlloc::kDebugAlloc_DetectLeakedAssemblyObjects
kStatus kDebugAlloc_DetectLeakedAssemblyObjects(kDebugAlloc object, k64u since, kAssembly assembly)
Makes note of outstanding allocations that appear to be objects associated with the specified assembl...
kDebugAlloc::kDebugAlloc_Checkpoint
k64u kDebugAlloc_Checkpoint(kDebugAlloc object)
Returns a memory checkpoint value, used in conjunction with allocation logging functions.
kApiDef.h
Essential API declarations.
kDebugAlloc::kDebugAlloc_Allocated
kSize kDebugAlloc_Allocated(kDebugAlloc object)
Returns the total amount of memory that has been allocated and not yet freed.
kArrayList
Represents a list implemented with a dynamic array.
kDebugAlloc::kDebugAlloc_Construct
kStatus kDebugAlloc_Construct(kDebugAlloc *object, const kChar *name, kAlloc allocator)
Constructs a new kDebugAlloc allocator.
kDebugAllocation
Allocation record used by kDebugAlloc.
Definition: kDebugAlloc.h:23
kStatus
Represents an enumeration of error codes.
kDebugAlloc::kDebugAlloc_SetAllocListener
kStatus kDebugAlloc_SetAllocListener(kDebugAlloc object, kCallbackFx function, kPointer receiver)
Registers a user-defined function that is called whenever a memory allocation occurs.