Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kPoolAlloc.h
Go to the documentation of this file.
1 /**
2 * @file kPoolAlloc.h
3 * @brief Declares the kPoolAlloc class and related types.
4 *
5 * @internal
6 * Copyright (C) 2013-2014 by LMI Technologies Inc. All rights reserved.
7 */
8 #ifndef K_API_POOL_ALLOC_H
9 #define K_API_POOL_ALLOC_H
10
11 #include <kApi/kApiDef.h>
12
13 kBeginHeader()
14
15 /**
16 * @class kPoolAlloc
17 * @ingroup kApi-Utils
18 * @brief Allocates small buffers from larger blocks and/or caches deallocated buffers for later reuse.
19 *
20 * This memory allocator can be used to improve performance in some circumstances. It can reduce the number
21 * of individual requests to an underlying allocator by allocating multiple small memory buffers from larger
22 * blocks. It can also cache deallocated buffers for later reuse, reducing the frequency of allocation requests
23 * made to the underlying allocator.
24 *
25 * For each memory request, a 'rank' is determined by calculating the base-2 logarithm of the requested size and then
26 * rounding up. The rank determines the true size of the buffer that will be allocated (requests are rounded up to
27 * the nearest power of two). Rank-based buffer management provides simple organization and fast reallocation; the
28 * cost is increased memory space.
29 *
30 * Parameters are provided to control which ranks should be allocated from larger blocks, which ranks should
31 * be cached upon deallocation, memory capacities, etc. Memory can be reserved using the kPoolAlloc_Reserve
32 * and kPoolAlloc_ReserveAt functions, and/or dynamically allocated from the underlying allocator as needed.
33 *
34 * The operations provided in this class should be used in the following order:
35 * - Construct a kPoolAlloc instance.
36 * - Perform configuration.
37 * - Use the kPoolAlloc_Start method to prepare the allocator for use.
38 * - Use the kPoolAlloc_Reserve or kPoolAlloc_ReserveAt methods to make pre-emptive allocations.
39 * - Use the kAlloc_Get/kAlloc_Free methods to perform allocations/deallocations.
40 * - Destroy the kPoolAlloc instance when no longer needed.
41 *
42 * All outstanding memory allocations must be freed before destroying the allocator.
43 */
44 //typedef kAlloc kPoolAlloc; --forward-declared in kApiDef.x.h
45
46 /**
47 * Constructs a kPoolAlloc object.
48 *
49 * The 'allocator' argument specifies the underlying memory allocator used by this kPoolAlloc
50 * instance to satisfy memory requests.
51 *
52 * @public @memberof kPoolAlloc
53 * @param object Destination for the constructed object handle.
54 * @param allocator Memory allocator (or kNULL for default).
55 * @return Operation status.
56 */
57 kFx(kStatus) kPoolAlloc_Construct(kPoolAlloc* object, kAlloc allocator);
58
59 /**
60 * Sets the approximate size of large memory blocks used to satisfy small memory requests.
61 *
62 * Blocks are assigned to one rank at a time. Multiple small allocations are typically performed
63 * from each larger block. The number of allocations that can be performed from a single block
64 * depends on the rank.
65 *
66 * A common block size is used for all ranks to allow free blocks to be transferred between ranks
67 * (if reuse is enabled).
68 *
69 * @public @memberof kPoolAlloc
70 * @param object kPoolAlloc object.
71 * @param size Block size, in bytes.
72 * @return Operation status.
73 */
74 kFx(kStatus) kPoolAlloc_SetBlockSize(kPoolAlloc object, kSize size);
75
76 /**
77 * Returns the approximate size of large memory blocks used to satisfy small memory requests.
78 *
79 * @public @memberof kPoolAlloc
80 * @param object kPoolAlloc object.
81 * @return Block size, in bytes.
82 */
83 kFx(kSize) kPoolAlloc_BlockSize(kPoolAlloc object);
84
85 /**
86 * Sets the size limit for memory requests that can be allocated from larger blocks.
87 *
88 * This property must be smaller than the BlockSize property. By default, this property
89 * is zero (block-based allocation is disabled).
90 *
91 * @public @memberof kPoolAlloc
92 * @param object kPoolAlloc object.
93 * @param size Maximum block-based allocation size, in bytes.
94 * @return Operation status.
95 */
96 kFx(kStatus) kPoolAlloc_SetMaxBlockBufferSize(kPoolAlloc object, kSize size);
97
98 /**
99 * Returns the size limit for memory requests that can be allocated from larger blocks.
100 *
101 * @public @memberof kPoolAlloc
102 * @param object kPoolAlloc object.
103 * @return Maximum size for a block-based allocation, in bytes.
104 */
105 kFx(kSize) kPoolAlloc_MaxBlockBufferSize(kPoolAlloc object);
106
107 /**
108 * Sets the maximum total amount of memory that can be used for block-based allocations.
109 *
110 * Blocks are dynamically allocated when needed; this property controls the maximum amount
111 * of memory that can be used for blocks. This property is kSIZE_MAX by default.
112 *
113 * @public @memberof kPoolAlloc
114 * @param object kPoolAlloc object.
115 * @param size Block memory capacity, in bytes.
116 * @return Operation status.
117 */
118 kFx(kStatus) kPoolAlloc_SetBlockCapacity(kPoolAlloc object, kSize size);
119
120 /**
121 * Returns the maximum amount of memory that can be used for block-based allocations.
122 *
123 * @public @memberof kPoolAlloc
124 * @param object kPoolAlloc object.
125 * @return Block memory capacity, in bytes.
126 */
127 kFx(kSize) kPoolAlloc_BlockCapacity(kPoolAlloc object);
128
129 /**
130 * Determines whether blocks can be reused between ranks.
131 *
132 * When a memory request qualifies for block-based allocation, and no free buffers
133 * are available at the required rank, a new block must be provided. If block
134 * reuse is enabled, then free blocks from other ranks can be reassigned as needed.
135 * If block reuse is disabled, then blocks remain at the rank to which they are first
136 * assigned.
137 *
138 * Block reuse can increase allocation time slightly, due to the need to search
139 * through all ranks for a free block. Reuse is enabled by default.
140 *
141 * @public @memberof kPoolAlloc
142 * @param object kPoolAlloc object.
143 * @param enabled kTRUE to enable reuse; kFALSE otherwise.
144 * @return Operation status.
145 */
146 kFx(kStatus) kPoolAlloc_EnableBlockReuse(kPoolAlloc object, kBool enabled);
147
148 /**
149 * Reports whether blocks can be reused between ranks.
150 *
151 * @public @memberof kPoolAlloc
152 * @param object kPoolAlloc object.
153 * @return kTRUE if block reuse is enabled; kFALSE otherwise.
154 */
155 kFx(kBool) kPoolAlloc_BlockReuseEnabled(kPoolAlloc object);
156
157 /**
158 * Sets the size limit for memory requests that can be cached upon deallocation.
159 *
160 * Small allocations are typically configured to be provided by block-based allocation, which
161 * automatically caches deallocated buffers for reuse. But larger (individually allocated)
162 * buffers can also be cached upon deallocation for later use. This property controls the
163 * maximum buffer size than can be cached upon deallocation.
164 *
165 * This property is zero by default (caching of individual allocations is disabled).
166 *
167 * @public @memberof kPoolAlloc
168 * @param object kPoolAlloc object.
169 * @param size Maximum cached allocation size, in bytes.
170 * @return Operation status.
171 */
172 kFx(kStatus) kPoolAlloc_SetMaxCachedBufferSize(kPoolAlloc object, kSize size);
173
174 /**
175 * Returns the size limit for memory requests that can be cached upon deallocation.
176 *
177 * @public @memberof kPoolAlloc
178 * @param object kPoolAlloc object.
179 * @return Maximum cached allocation size, in bytes.
180 */
181 kFx(kSize) kPoolAlloc_MaxCachedBufferSize(kPoolAlloc object);
182
183 /**
184 * Sets the maximum total amount of memory that can be used to cache buffers upon deallocation.
185 *
186 * This property does not affect block-based allocations, which can be limited using the
187 * kPoolAlloc_SetBlockCapacity function.
188 *
189 * This property is kSIZE_MAX by default.
190 *
191 * @public @memberof kPoolAlloc
192 * @param object kPoolAlloc object.
193 * @param size Cached memory capacity, in bytes.
194 * @return Operation status.
195 */
196 kFx(kStatus) kPoolAlloc_SetCacheCapacity(kPoolAlloc object, kSize size);
197
198 /**
199 * Returns the maximum total amount of memory that can be used to cache buffers upon deallocation.
200 *
201 * @public @memberof kPoolAlloc
202 * @param object kPoolAlloc object.
203 * @return Cached memory capacity, in bytes.
204 */
205 kFx(kSize) kPoolAlloc_CacheCapacity(kPoolAlloc object);
206
207 /**
208 * Sets the total amount of memory that can be requested from the underlying allocator.
209 *
210 * This property is kSIZE_MAX by default.
211 *
212 * @public @memberof kPoolAlloc
213 * @param object kPoolAlloc object.
214 * @param size Amount of memory that can be requested from underlying allocator, in bytes.
215 * @return Operation status.
216 */
217 kFx(kStatus) kPoolAlloc_SetTotalCapacity(kPoolAlloc object, kSize size);
218
219 /**
220 * Returns the total amount of memory that can be requested from the underlying allocator.
221 *
222 * @public @memberof kPoolAlloc
223 * @param object kPoolAlloc object.
224 * @return Amount of memory that can be requested from underlying allocator, in bytes.
225 */
226 kFx(kSize) kPoolAlloc_TotalCapacity(kPoolAlloc object);
227
228 /**
229 * Prepares the allocator for first use.
230 *
231 * This function should be called after configuration properties have been provided, and before using
232 * memory reservation or allocation functions.
233 *
234 * Configuration functions cannot be used after calling kPoolAlloc_Start.
235 *
236 * @public @memberof kPoolAlloc
237 * @param object kPoolAlloc object.
238 * @return Operation status.
239 */
240 kFx(kStatus) kPoolAlloc_Start(kPoolAlloc object);
241
242 /**
243 * Specifies the minimum amount of memory that should be set aside for blocks.
244 *
245 * This function can be used to ensure that the specified amount of memory is set aside
246 * for block-based allocations. The amount of memory specified is inclusive of any
247 * existing block memory (e.g., individual rank reservations).
248 *
249 * This function cannot be used before calling kPoolAlloc_Start.
250 *
251 * @public @memberof kPoolAlloc
252 * @param object kPoolAlloc object.
253 * @param size Amount of memory to reserve, in bytes.
254 * @return Operation status.
255 */
256 kFx(kStatus) kPoolAlloc_Reserve(kPoolAlloc object, kSize size);
257
258 /**
259 * Specifies the minimum amount of memory that should be set aside at a particular rank.
260 *
261 * This function can be used to ensure that the specified amount of memory is set aside
262 * for block-based allocations at a specific rank.
263 *
264 * This function can also be used to pre-cache individual buffers at a specific rank.
265 * However, these buffers may later be deallocated if the CacheCapacity limit is reached.
266 *
267 * This function cannot be used before calling kPoolAlloc_Start.
268 *
269 * @public @memberof kPoolAlloc
270 * @param object kPoolAlloc object.
271 * @param rank Memory rank (base-2 logarithm of memory size).
272 * @param size Amount of memory to reserve, in bytes.
273 * @return Operation status.
274 */
275 kFx(kStatus) kPoolAlloc_ReserveAt(kPoolAlloc object, kSize rank, kSize size);
276
277 /**
278 * Returns surplus memory to the underlying allocator.
279 *
280 * For block-based ranks, any unused blocks will be returned to the underlying allocator.
281 * Reservations made using kPoolAlloc_Reserve/kPoolAlloc_ReserveAt are honored; those
282 * blocks will be preserved for later use.
283 *
284 * For ranks configured to cache buffers upon deallocation, any unused buffers will be
285 * returned to the underlying allocator. Reservations made using kPoolAlloc_ReserveAt are
286 * honored; those buffers will be preserved for later use.
287 *
288 * @public @memberof kPoolAlloc
289 * @param object kPoolAlloc object.
290 * @return Operation status.
291 */
292 kFx(kStatus) kPoolAlloc_Clear(kPoolAlloc object);
293
294 /**
295 * Removes any existing memory reservations and returns surplus memory to the underlying allocator.
296 *
297 * @public @memberof kPoolAlloc
298 * @param object kPoolAlloc object.
299 * @return Operation status.
300 */
301 kFx(kStatus) kPoolAlloc_ClearAll(kPoolAlloc object);
302
303 /**
304 * Reports the total number of memory buffers at the given rank.
305 *
306 * This function reports the total number of buffers, including buffers currently in use
307 * (allocated via kAlloc_Get and not yet freed) and buffers cached for later use.
308 *
309 * @public @memberof kPoolAlloc
310 * @param object kPoolAlloc object.
311 * @param rank Memory rank (base-2 logarithm of memory size).
312 * @return Buffer count.
313 */
314 kFx(kSize) kPoolAlloc_BufferCountAt(kPoolAlloc object, kSize rank);
315
316 /**
317 * Reports the current amount of memory drawn from the underlying allocator.
318 *
319 * Total does not include the kPoolAlloc object header; all other memory is included.
320 *
321 * @public @memberof kPoolAlloc
322 * @param object kPoolAlloc object.
323 * @return Total memory, in bytes.
324 */
325 kFx(kSize) kPoolAlloc_TotalSize(kPoolAlloc object);
326
327 kEndHeader()
328
329 #include <kApi/Utils/kPoolAlloc.x.h>
330
331 #endif
kPoolAlloc::kPoolAlloc_BlockReuseEnabled
kBool kPoolAlloc_BlockReuseEnabled(kPoolAlloc object)
Reports whether blocks can be reused between ranks.
kPoolAlloc::kPoolAlloc_ClearAll
kStatus kPoolAlloc_ClearAll(kPoolAlloc object)
Removes any existing memory reservations and returns surplus memory to the underlying allocator...
kPoolAlloc::kPoolAlloc_Construct
kStatus kPoolAlloc_Construct(kPoolAlloc *object, kAlloc allocator)
Constructs a kPoolAlloc object.
kPoolAlloc::kPoolAlloc_Start
kStatus kPoolAlloc_Start(kPoolAlloc object)
Prepares the allocator for first use.
kPoolAlloc::kPoolAlloc_SetMaxBlockBufferSize
kStatus kPoolAlloc_SetMaxBlockBufferSize(kPoolAlloc object, kSize size)
Sets the size limit for memory requests that can be allocated from larger blocks. ...
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kPoolAlloc::kPoolAlloc_TotalCapacity
kSize kPoolAlloc_TotalCapacity(kPoolAlloc object)
Returns the total amount of memory that can be requested from the underlying allocator.
kPoolAlloc::kPoolAlloc_MaxCachedBufferSize
kSize kPoolAlloc_MaxCachedBufferSize(kPoolAlloc object)
Returns the size limit for memory requests that can be cached upon deallocation.
kPoolAlloc::kPoolAlloc_SetTotalCapacity
kStatus kPoolAlloc_SetTotalCapacity(kPoolAlloc object, kSize size)
Sets the total amount of memory that can be requested from the underlying allocator.
kPoolAlloc::kPoolAlloc_TotalSize
kSize kPoolAlloc_TotalSize(kPoolAlloc object)
Reports the current amount of memory drawn from the underlying allocator.
kPoolAlloc::kPoolAlloc_CacheCapacity
kSize kPoolAlloc_CacheCapacity(kPoolAlloc object)
Returns the maximum total amount of memory that can be used to cache buffers upon deallocation...
kPoolAlloc::kPoolAlloc_Reserve
kStatus kPoolAlloc_Reserve(kPoolAlloc object, kSize size)
Specifies the minimum amount of memory that should be set aside for blocks.
kPoolAlloc::kPoolAlloc_BlockCapacity
kSize kPoolAlloc_BlockCapacity(kPoolAlloc object)
Returns the maximum amount of memory that can be used for block-based allocations.
kPoolAlloc::kPoolAlloc_BufferCountAt
kSize kPoolAlloc_BufferCountAt(kPoolAlloc object, kSize rank)
Reports the total number of memory buffers at the given rank.
kApiDef.h
Essential API declarations.
kPoolAlloc::kPoolAlloc_Clear
kStatus kPoolAlloc_Clear(kPoolAlloc object)
Returns surplus memory to the underlying allocator.
kPoolAlloc::kPoolAlloc_EnableBlockReuse
kStatus kPoolAlloc_EnableBlockReuse(kPoolAlloc object, kBool enabled)
Determines whether blocks can be reused between ranks.
kStatus
Represents an enumeration of error codes.
kPoolAlloc::kPoolAlloc_MaxBlockBufferSize
kSize kPoolAlloc_MaxBlockBufferSize(kPoolAlloc object)
Returns the size limit for memory requests that can be allocated from larger blocks.
kPoolAlloc::kPoolAlloc_SetCacheCapacity
kStatus kPoolAlloc_SetCacheCapacity(kPoolAlloc object, kSize size)
Sets the maximum total amount of memory that can be used to cache buffers upon deallocation.
kPoolAlloc
Allocates small buffers from larger blocks and/or caches deallocated buffers for later reuse...
kPoolAlloc::kPoolAlloc_SetMaxCachedBufferSize
kStatus kPoolAlloc_SetMaxCachedBufferSize(kPoolAlloc object, kSize size)
Sets the size limit for memory requests that can be cached upon deallocation.
kPoolAlloc::kPoolAlloc_BlockSize
kSize kPoolAlloc_BlockSize(kPoolAlloc object)
Returns the approximate size of large memory blocks used to satisfy small memory requests.
kPoolAlloc::kPoolAlloc_SetBlockCapacity
kStatus kPoolAlloc_SetBlockCapacity(kPoolAlloc object, kSize size)
Sets the maximum total amount of memory that can be used for block-based allocations.
kBool
Represents a boolean value.
kPoolAlloc::kPoolAlloc_SetBlockSize
kStatus kPoolAlloc_SetBlockSize(kPoolAlloc object, kSize size)
Sets the approximate size of large memory blocks used to satisfy small memory requests.
kPoolAlloc::kPoolAlloc_ReserveAt
kStatus kPoolAlloc_ReserveAt(kPoolAlloc object, kSize rank, kSize size)
Specifies the minimum amount of memory that should be set aside at a particular rank.