le_mem.h

Go to the documentation of this file.
1 /**
2  * @page c_memory Dynamic Memory Allocation API
3  *
4  *
5  * @subpage le_mem.h "API Reference"
6  *
7  * <HR>
8  *
9  * Dynamic memory allocation (especially deallocation) using the C runtime heap, through
10  * malloc, free, strdup, calloc, realloc, etc. can result in performance degradation and out-of-memory
11  * conditions.
12  *
13  * This is due to fragmentation of the heap. The degraded performance and exhausted memory result from indirect interactions
14  * within the heap between unrelated application code. These issues are non-deterministic,
15  * and can be very difficult to rectify.
16  *
17  * Memory Pools offer a powerful solution. They trade-off a deterministic amount of
18  * memory for
19  * - deterministic behaviour,
20  * - O(1) allocation and release performance, and
21  * - built-in memory allocation tracking.
22  *
23  * And it brings the power of @b destructors to C!
24  *
25  * @todo
26  * Do we need to add a "resettable heap" option to the memory management tool kit?
27  *
28  *
29  * @section mem_overview Overview
30  *
31  * The most basic usage involves:
32  * - Creating a pool (usually done once at process start-up)
33  * - Allocating objects (memory blocks) from a pool
34  * - Releasing objects back to their pool.
35  *
36  * Pools generally can't be deleted. You create them when your process
37  * starts-up, and use them until your process terminates. It's up to the OS to clean-up the memory
38  * pools, along with everything else your process is using, when your process terminates. (Although,
39  * if you find yourself really needing to delete pools, @ref mem_sub_pools could offer you a solution.)
40  *
41  * Pools also support the following advanced features:
42  * - reference counting
43  * - destructors
44  * - statistics
45  * - multi-threading
46  * - sub-pools (pools that can be deleted).
47  *
48  * The following sections describe these, beginning with the most basic usage and working up to more
49  * advanced topics.
50  *
51  *
52  * @section mem_creating Creating a Pool
53  *
54  * Before allocating memory from a pool, the pool must be created using le_mem_CreatePool(), passing
55  * it the name of the pool and the size of the objects to be allocated from that pool. This returns
56  * a reference to the new pool, which has zero free objects in it.
57  *
58  * To populate your new pool with free objects, you call @c le_mem_ExpandPool().
59  * This is separated into two functions (rather than having
60  * one function with three parameters) to make it virtually impossible to accidentally get the parameters
61  * in the wrong order (which would result in nasty bugs that couldn't be caught by the compiler).
62  * The ability to expand pools comes in handy (see @ref mem_pool_sizes).
63  *
64  * This code sample defines a class "Point" and a pool "PointPool" used to
65  * allocate memory for objects of that class:
66  * @code
67  * #define MAX_POINTS 12 // Maximum number of points that can be handled.
68  *
69  * typedef struct
70  * {
71  * int x; // pixel position along x-axis
72  * int y; // pixel position along y-axis
73  * }
74  * Point_t;
75  *
76  * le_mem_PoolRef_t PointPool;
77  *
78  * int xx_pt_ProcessStart(void)
79  * {
80  * PointPool = le_mem_CreatePool("xx.pt.Points", sizeof(Point_t));
81  * le_mem_ExpandPool(PointPool, MAX_POINTS);
82  *
83  * return SUCCESS;
84  * }
85  * @endcode
86  *
87  * To make things easier for power-users, @c le_mem_ExpandPool() returns the same pool
88  * reference that it was given. This allows the xx_pt_ProcessStart() function to be re-implemented
89  * as follows:
90  * @code
91  * int xx_pt_ProcessStart(void)
92  * {
93  * PointPool = le_mem_ExpandPool(le_mem_CreatePool(sizeof(Point_t)), MAX_POINTS);
94  *
95  * return SUCCESS;
96  * }
97  * @endcode
98  *
99  * Although this requires a dozen or so fewer keystrokes of typing and occupies one less line
100  * of code, it's arguably less readable than the previous example.
101  *
102  * For a discussion on how to pick the number of objects to have in your pools, see @ref mem_pool_sizes.
103  *
104  * @section mem_allocating Allocating From a Pool
105  *
106  * Allocating from a pool has multiple options:
107  * - @c le_mem_TryAlloc() - Quietly return NULL if there are no free blocks in the pool.
108  * - @c le_mem_AssertAlloc() - Log an error and take down the process if there are no free blocks in
109  * the pool.
110  * - @c le_mem_ForceAlloc() - If there are no free blocks in the pool, log a warning and automatically
111  * expand the pool (or log an error and terminate the calling process there's
112  * not enough free memory to expand the pool).
113  *
114  * All of these functions take a pool reference and return a pointer to the object
115  * allocated from the pool.
116  *
117  * The first option, using @c le_mem_TryAlloc(), is the
118  * closest to the way good old malloc() works. It requires the caller check the
119  * return code to see if it's NULL. This can be annoying enough that a lot of
120  * people get lazy and don't check the return code (Bad programmer! Bad!). It turns out that
121  * this option isn't really what people usually want (but occasionally they do)
122  *
123  * The second option, using @c le_mem_AssertAlloc(), is only used when the allocation should
124  * never fail, by design; a failure to allocate a block is a fatal error.
125  * This isn't often used, but can save a lot of boilerplate error checking code.
126  *
127  * The third option, @c using le_mem_ForceAlloc(), is the one that gets used most often.
128  * It allows developers to avoid writing error checking code, because the allocation will
129  * essentially never fail because it's handled inside the memory allocator. It also
130  * allows developers to defer fine tuning their pool sizes until after they get things working.
131  * Later, they check the logs for pool size usage, and then modify their pool sizes accordingly.
132  * If a particular pool is continually growing, it's a good indication there's a
133  * memory leak. This permits seeing exactly what objects are being leaked. If certain debug
134  * options are turned on, they can even find out which line in which file allocated the blocks
135  * being leaked.
136  *
137  *
138  * @section mem_releasing Releasing Back Into a Pool
139  *
140  * Releasing memory back to a pool never fails, so there's no need to check a return code.
141  * Also, each object knows which pool it came from, so the code that releases the object doesn't have to care.
142  * All it has to do is call @c le_mem_Release() and pass a pointer to the object to be released.
143  *
144  * The critical thing to remember is that once an object has been released, it
145  * <b> must never be accessed again </b>. Here is a <b> very bad code example</b>:
146  * @code
147  * Point_t* pointPtr = le_mem_ForceAlloc(PointPool);
148  * pointPtr->x = 5;
149  * pointPtr->y = 10;
150  * le_mem_Release(pointPtr);
151  * printf("Point is at position (%d, %d).\n", pointPtr->x, pointPtr->y);
152  * @endcode
153  *
154  *
155  * @section mem_ref_counting Reference Counting
156  *
157  * Reference counting is a powerful feature of our memory pools. Here's how it works:
158  * - Every object allocated from a pool starts with a reference count of 1.
159  * - Whenever someone calls le_mem_AddRef() on an object, its reference count is incremented by 1.
160  * - When it's released, its reference count is decremented by 1.
161  * - When its reference count reaches zero, it's destroyed (i.e., its memory is released back into the pool.)
162  *
163  * This allows one function to:
164  * - create an object.
165  * - work with it.
166  * - increment its reference count and pass a pointer to the object to another function (or thread, data structure, etc.).
167  * - work with it some more.
168  * - release the object without having to worry about when the other function is finished with it.
169  *
170  * The other function also releases the object when it's done with it. So, the object will
171  * exist until both functions are done.
172  *
173  * If there are multiple threads involved, be careful to protect the shared
174  * object from race conditions(see the @ref mem_threading).
175  *
176  * Another great advantage of reference counting is it enables @ref mem_destructors.
177  *
178  * @note le_mem_GetRefCount() can be used to check the current reference count on an object.
179  *
180  * @section mem_destructors Destructors
181  *
182  * Destructors are a powerful feature of C++. Anyone who has any non-trivial experience with C++ has
183  * used them. Because C was created before object-oriented programming was around, there's
184  * no native language support for destructors in C. Object-oriented design is still possible
185  * and highly desireable even when the programming is done in C.
186  *
187  * In Legato, it's possible to call @c le_mem_SetDestructor() to attach a function to a memory pool
188  * to be used as a destructor for objects allocated from that pool. If a pool has a destructor,
189  * whenever the reference count reaches zero for an object allocated from that pool,
190  * the pool's destructor function will pass a pointer to that object. After
191  * the destructor returns, the object will be fully destroyed, and its memory will be released back
192  * into the pool for later reuse by another object.
193  *
194  * Here's a destructor code sample:
195  * @code
196  * static void PointDestructor(void* objPtr)
197  * {
198  * Point_t* pointPtr = objPtr;
199  *
200  * printf("Destroying point (%d, %d)\n", pointPtr->x, pointPtr->y);
201  *
202  * @todo Add more to sample.
203  * }
204  *
205  * int xx_pt_ProcessStart(void)
206  * {
207  * PointPool = le_mem_CreatePool(sizeof(Point_t));
208  * le_mem_ExpandPool(PointPool, MAX_POINTS);
209  * le_mem_SetDestructor(PointPool, PointDestructor);
210  * return SUCCESS;
211  * }
212  *
213  * static void DeletePointList(Point_t** pointList, size_t numPoints)
214  * {
215  * size_t i;
216  * for (i = 0; i < numPoints; i++)
217  * {
218  * le_mem_Release(pointList[i]);
219  * }
220  * }
221  * @endcode
222  *
223  * In this sample, when DeletePointList() is called (with a pointer to an array of pointers
224  * to Point_t objects with reference counts of 1), each of the objects in the pointList is
225  * released. This causes their reference counts to hit 0, which triggers executing
226  * PointDestructor() for each object in the pointList, and the "Destroying point..." message will
227  * be printed for each.
228  *
229  *
230  * @section mem_stats Statistics
231  *
232  * Some statistics are gathered for each memory pool:
233  * - Number of allocations.
234  * - Number of currently free objects.
235  * - Number of overflows (times that le_mem_ForceAlloc() had to expand the pool).
236  *
237  * Statistics (and other pool properties) can be checked using functions:
238  * - @c le_mem_GetStats()
239  * - @c le_mem_GetObjectCount()
240  * - @c le_mem_GetObjectSize()
241  *
242  * Statistics are fetched together atomically using a single function call.
243  * This prevents inconsistencies between them if in a multi-threaded program.
244  *
245  * If you don't have a reference to a specified pool, but you have the name of the pool, you can
246  * get a reference to the pool using @c le_mem_FindPool().
247  *
248  * In addition to programmatically fetching these, they're also available through the
249  * "poolstat" console command (unless your process's main thread is blocked).
250  *
251  * To reset the pool statistics, use @c le_mem_ResetStats().
252  *
253  * @section mem_diagnostics Diagnostics
254  *
255  * The memory system also supports two different forms of diagnostics. Both are enabled by setting
256  * the appropriate KConfig options when building the framework.
257  *
258  * The first of these options is @ref MEM_TRACE. When you enable @ref MEM_TRACE every pool is given
259  * a tracepoint with the name of the pool on creation.
260  *
261  * For instance, the configTree node pool is called, "configTree.nodePool". So to enable a trace of
262  * all config tree node creation and deletion one would use the log tool as follows:
263  *
264  * @code
265  * $ log trace configTree.nodePool
266  * @endcode
267  *
268  * The second diagnostic build flag is @ref MEM_POOLS. When @ref MEM_POOLS is disabled, the pools
269  * are disabled and instead malloc and free are directly used. Thus enabling the use of tools
270  * like Valgrind.
271  *
272  * @section mem_threading Multi-Threading
273  *
274  * All functions in this API are <b> thread-safe, but not async-safe </b>. The objects
275  * allocated from pools are not inherently protected from races between threads.
276  *
277  * Allocating and releasing objects, checking stats, incrementing reference
278  * counts, etc. can all be done from multiple threads (excluding signal handlers) without having
279  * to worry about corrupting the memory pools' hidden internal data structures.
280  *
281  * There's no magical way to prevent different threads from interferring with each other
282  * if they both access the @a contents of the same object at the same time.
283  *
284  * The best way to prevent multi-threaded race conditions is simply don't share data between
285  * threads. If multiple threads must access the same data structure, then mutexes, semaphores,
286  * or similar methods should be used to @a synchronize threads and avoid
287  * data structure corruption or thread misbehaviour.
288  *
289  * Although memory pools are @a thread-safe, they are not @a async-safe. This means that memory pools
290  * @a can be corrupted if they are accessed by a signal handler while they are being accessed
291  * by a normal thread. To be safe, <b> don't call any memory pool functions from within a signal handler. </b>
292  *
293  * One problem using destructor functions in a
294  * multi-threaded environment is that the destructor function modifies a data structure shared
295  * between threads, so it's easy to forget to synchronize calls to @c le_mem_Release() with other code
296  * accessing the data structure. If a mutex is used to coordinate access to
297  * the data structure, then the mutex must be held by the thread that calls le_mem_Release() to
298  * ensure there's no other thread accessing the data structure when the destructor runs.
299  *
300  * @section mem_pool_sizes Managing Pool Sizes
301  *
302  * We know it's possible to have pools automatically expand
303  * when they are exhausted, but we don't really want that to happen normally.
304  * Ideally, the pools should be fully allocated to their maximum sizes at start-up so there aren't
305  * any surprises later when certain feature combinations cause the
306  * system to run out of memory in the field. If we allocate everything we think
307  * is needed up-front, then we are much more likely to uncover any memory shortages during
308  * testing, before it's in the field.
309  *
310  * Choosing the right size for your pools correctly at start-up is easy to do if there is a maximum
311  * number of fixed, external @a things that are being represented by the objects being allocated
312  * from the pool. If the pool holds "call objects" representing phone calls over a T1
313  * carrier that will never carry more than 24 calls at a time, then it's obvious that you need to
314  * size your call object pool at 24.
315  *
316  * Other times, it's not so easy to choose the pool size like
317  * code to be reused in different products or different configurations that have different
318  * needs. In those cases, you still have a few options:
319  *
320  * - At start-up, query the operating environment and base the pool sizes.
321  * - Read a configuration setting from a file or other configuration data source.
322  * - Use a build-time configuration setting.
323  *
324  * The build-time configuration setting is the easiest, and generally requires less
325  * interaction between components at start-up simplifying APIs
326  * and reducing boot times.
327  *
328  * If the pool size must be determined at start-up, use @c le_mem_ExpandPool().
329  * Perhaps there's a service-provider module designed to allocate objects on behalf
330  * of client. It can have multiple clients at the same time, but it doesn't know how many clients
331  * or what their resource needs will be until the clients register with it at start-up. We'd want
332  * those clients to be as decoupled from each other as possible (i.e., we want the clients know as little
333  * as possible about each other); we don't want the clients to get together and add up all
334  * their needs before telling the service-provider. We'd rather have the clients independently
335  * report their own needs to the service-provider. Also, we don't want each client to have to wait
336  * for all the other clients to report their needs before starting to use
337  * the services offered by the service-provider. That would add more complexity to the interactions
338  * between the clients and the service-provider.
339  *
340  * This is what should happen when the service-provider can't wait for all clients
341  * to report their needs before creating the pool:
342  * - When the service-provider starts up, it creates an empty pool.
343  * - Whenever a client registers itself with the service-provider, the client can tell the
344  * service-provider what its specific needs are, and the service-provider can expand its
345  * object pool accordingly.
346  * - Since registrations happen at start-up, pool expansion occurs
347  * at start-up, and testing will likely find any pool sizing before going into the field.
348  *
349  * Where clients dynamically start and stop during runtime in response
350  * to external events (e.g., when someone is using the device's Web UI), we still have
351  * a problem because we can't @a shrink pools or delete pools when clients go away. This is where
352  * @ref mem_sub_pools is useful.
353  *
354  * @section mem_sub_pools Sub-Pools
355  *
356  * Essentially, a Sub-Pool is a memory pool that gets its blocks from another pool (the super-pool).
357  * Sub Pools @a can be deleted, causing its blocks to be released back into the super-pool.
358  *
359  * This is useful when a service-provider module needs to handle clients that
360  * dynamically pop into existence and later disappear again. When a client attaches to the service
361  * and says it will probably need a maximum of X of the service-provider's resources, the
362  * service provider can set aside that many of those resources in a sub-pool for that client.
363  * If that client goes over its limit, the sub-pool will log a warning message.
364  *
365  * The problem of sizing the super-pool correctly at start-up still exists,
366  * so what's the point of having a sub-pool, when all of the resources could just be allocated from
367  * the super-pool?
368  *
369  * The benefit is really gained in troubleshooting. If client A, B, C, D and E are
370  * all behaving nicely, but client F is leaking resources, the sub-pool created
371  * on behalf of client F will start warning about the memory leak; time won't have to be
372  * wasted looking at clients A through E to rule them out.
373  *
374  * A visual side effect of using sub-pools is that their blocks will count as being in use by the
375  * super-pool but they will not count as allocations of the super-pool.
376  *
377  * To create a sub-pool, call @c le_mem_CreateSubPool(). It takes a reference to the super-pool
378  * and the number of objects to move to the sub-pool, and it returns a reference to the new sub-pool.
379  *
380  * To delete a sub-pool, call @c le_mem_DeleteSubPool(). Do not try to use it to delete a pool that
381  * was created using le_mem_CreatePool(). It's only for sub-pools created using le_mem_CreateSubPool().
382  * Also, it's @b not okay to delete a sub-pool while there are still blocks allocated from it, or
383  * if it has any sub-pools. You'll see errors in your logs if you do that.
384  *
385  * Sub-Pools automatically inherit their parent's destructor function.
386  *
387  * @section mem_reduced_pools Reduced-size pools
388  *
389  * One problem that occurs with memory pools is where objects of different sizes need to be
390  * stored. A classic example is strings -- the longest string an application needs to be able
391  * to handle may be much longer than the typical string size. In this case a lot of memory
392  * will be wasted with standard memory pools, since all objects allocated from the pool will
393  * be the size of the longest possible object.
394  *
395  * The solution is to use reduced-size pools. These are a kind of sub-pool where the size
396  * of the object in the sub-pool is different from the size of the object in the super-pool.
397  * This way multiple blocks from the sub-pool can be stored in a single block of the super-pool.
398  *
399  * Reduced-size pools have some limitations:
400  *
401  * - Each block in the super-pool is divided up to create blocks in the subpool. So subpool
402  * blocks sizes must be less than half the size of the super-pool block size. An attempt to
403  * create a pool with a larger block size will just return a reference to the super-pool.
404  * - Due overhead, each block actually requires 8-80 bytes more space than requested.
405  * There is little point in subdividing pools < 4x overhead, or ~300 bytes in the default
406  * configuration. Note the exact amount of overhead depends on the size of the guard bands
407  * and the size of pointer on your target.
408  * - Blocks used by the reduced pool are permanently moved from the super-pool to the reduced
409  * pool. This must be taken into account when sizing the super-pool.
410  *
411  * Example 1:
412  *
413  * A network service needs to allocate space for packets received over a network. It should
414  * Typical packet length is up to 200 bytes, but occasional packets may be up to 1500 bytes. The
415  * service needs to be able to queue at least 32 packets, up to 5 of which can be 1500 bytes.
416  * Two pools are used: A pool of 12 objects 1500 bytes in size, and a reduced-size pool of 32
417  * objects 200 bytes in size (280 bytes with overhead). Seven objects from the superpool are
418  * used to store reduced-size objects. This represents a memory savings of 60% compared with
419  * a pool of 32 1500 byte objects.
420  *
421  * Example 2:
422  *
423  * An application builds file paths which can be from 16-70 bytes. Only three such paths can be
424  * created at a time, but they can be any size. In this case it is better to just create
425  * a single pool of three 70-byte objects. Most of the potential space gains would be consumed
426  * by overhead. Even if this was not the case, the super pool still needs three free objects
427  * in addition to the objects required by the subpool, so there is no space savings.
428  *
429  * To create a reduced-size pool, use @c le_mem_CreateReducedPool(). It takes a reference to the
430  * super-pool, the initial number of objects in the sub-pool, and size of an object in the sub-pool
431  * compared with the parent pool, and it returns a reference to the new sub-pool.
432  *
433  * Reduced-size pools are deleted using @c le_mem_DeleteSubPool() like other sub-pools.
434  *
435  * To help the programmer pick the right pool to allocate from, reduced-size pools provide
436  * @c le_mem_TryVarAlloc(), @c le_mem_AssertVarAlloc() and @c le_mem_ForceVarAlloc() functions.
437  * In addition to the pool these take the object size to allocate. If this size is larger than
438  * the pool's object size and the pool is a reduced-size pool, and there is a parent pool
439  * large enough for this object, it will allocate the object from the parent pool instead.
440  * If no parent pool is large enough, the program will exit.
441  *
442  * You can call @c le_mem_GetBlockSize() to get the actual size of the object returned by
443  * one of these functions.
444  *
445  * As with other sub-pools, they cannot be deleted while any blocks are allocated from the pool,
446  * or it has any sub-pools. Reduced-size pools also automatically inherit their parent's
447  * destructor function.
448  *
449  * <HR>
450  *
451  * Copyright (C) Sierra Wireless Inc.
452  */
453 
454 //--------------------------------------------------------------------------------------------------
455 /** @file le_mem.h
456  *
457  * Legato @ref c_memory include file.
458  *
459  * Copyright (C) Sierra Wireless Inc.
460  *
461  */
462 //--------------------------------------------------------------------------------------------------
463 
464 #ifndef LEGATO_MEM_INCLUDE_GUARD
465 #define LEGATO_MEM_INCLUDE_GUARD
466 
467 #include "le_singlyLinkedList.h"
468 
469 #ifndef LE_COMPONENT_NAME
470 # define LE_COMPONENT_NAME
471 #endif
472 
473 //--------------------------------------------------------------------------------------------------
474 /**
475  * Prototype for destructor functions.
476  *
477  * @param objPtr Pointer to the object where reference count has reached zero. After the destructor
478  * returns this object's memory will be released back into the pool (and this pointer
479  * will become invalid).
480  *
481  * @return Nothing.
482  *
483  * See @ref mem_destructors for more information.
484  */
485 //--------------------------------------------------------------------------------------------------
486 typedef void (*le_mem_Destructor_t)
487 (
488  void* objPtr ///< see parameter documentation in comment above.
489 );
490 
491 // Max memory pool name bytes -- must match definition in limit.h
492 #define LE_MEM_LIMIT_MAX_MEM_POOL_NAME_BYTES 32
493 
494 //--------------------------------------------------------------------------------------------------
495 /**
496  * Definition of a memory pool.
497  *
498  * @note This should not be used directly. To create a memory pool use either le_mem_CreatePool()
499  * or LE_MEM_DEFINE_STATIC_POOL()/le_mem_InitStaticPool().
500  */
501 //--------------------------------------------------------------------------------------------------
502 typedef struct le_mem_Pool
503 {
504  le_dls_Link_t poolLink; ///< This pool's link in the list of memory pools.
505  struct le_mem_Pool* superPoolPtr; ///< A pointer to our super pool if we are a sub-pool. NULL
506  /// if we are not a sub-pool.
507 #if LE_CONFIG_MEM_POOL_STATS
508  // These members go before LE_CONFIG_MEM_POOLS so numAllocations will always be aligned, even on
509  // 32-bit architectures, even when LE_CONFIG_MEM_POOLS is not declared
510  size_t numOverflows; ///< Number of times le_mem_ForceAlloc() had to expand pool.
511  uint64_t numAllocations; ///< Total number of times an object has been allocated
512  /// from this pool.
513  size_t maxNumBlocksUsed; ///< Maximum number of allocated blocks at any one time.
514 #endif
515 #if LE_CONFIG_MEM_POOLS
516  le_sls_List_t freeList; ///< List of free memory blocks.
517 #endif
518 
519  size_t userDataSize; ///< Size of the object requested by the client in bytes.
520  size_t blockSize; ///< Number of bytes in a block, including all overhead.
521  size_t totalBlocks; ///< Total number of blocks in this pool including free
522  /// and allocated blocks.
523  size_t numBlocksInUse; ///< Number of currently allocated blocks.
524  size_t numBlocksToForce; ///< Number of blocks that is added when Force Alloc
525  /// expands the pool.
526 #if LE_CONFIG_MEM_TRACE
527  le_log_TraceRef_t memTrace; ///< If tracing is enabled, keeps track of a trace object
528  ///< for this pool.
529 #endif
530 
531  le_mem_Destructor_t destructor; ///< The destructor for objects in this pool.
532 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
533  char name[LE_MEM_LIMIT_MAX_MEM_POOL_NAME_BYTES]; ///< Name of the pool.
534 #endif
535 }
537 
538 
539 //--------------------------------------------------------------------------------------------------
540 /**
541  * Objects of this type are used to refer to a memory pool created using either
542  * le_mem_CreatePool() or le_mem_CreateSubPool().
543  */
544 //--------------------------------------------------------------------------------------------------
545 typedef struct le_mem_Pool* le_mem_PoolRef_t;
546 
547 
548 //--------------------------------------------------------------------------------------------------
549 /**
550  * List of memory pool statistics.
551  */
552 //--------------------------------------------------------------------------------------------------
553 typedef struct
554 {
555  size_t numBlocksInUse; ///< Number of currently allocated blocks.
556  size_t maxNumBlocksUsed; ///< Maximum number of allocated blocks at any one time.
557  size_t numOverflows; ///< Number of times le_mem_ForceAlloc() had to expand the pool.
558  uint64_t numAllocs; ///< Number of times an object has been allocated from this pool.
559  size_t numFree; ///< Number of free objects currently available in this pool.
560 }
562 
563 
564 #if LE_CONFIG_MEM_TRACE
565  //----------------------------------------------------------------------------------------------
566  /**
567  * Internal function used to retrieve a pool handle for a given pool block.
568  */
569  //----------------------------------------------------------------------------------------------
570  le_mem_PoolRef_t _le_mem_GetBlockPool
571  (
572  void* objPtr ///< [IN] Pointer to the object we're finding a pool for.
573  );
574 
575  typedef void* (*_le_mem_AllocFunc_t)(le_mem_PoolRef_t pool);
576 
577  //----------------------------------------------------------------------------------------------
578  /**
579  * Internal function used to call a memory allocation function and trace its call site.
580  */
581  //----------------------------------------------------------------------------------------------
582  void* _le_mem_AllocTracer
583  (
584  le_mem_PoolRef_t pool, ///< [IN] The pool activity we're tracing.
585  _le_mem_AllocFunc_t funcPtr, ///< [IN] Pointer to the mem function in question.
586  const char* poolFunction, ///< [IN] The pool function being called.
587  const char* file, ///< [IN] The file the call came from.
588  const char* callingfunction, ///< [IN] The function calling into the pool.
589  size_t line ///< [IN] The line in the function where the call
590  /// occurred.
591  );
592 
593  //----------------------------------------------------------------------------------------------
594  /**
595  * Internal function used to call a variable memory allocation function and trace its call site.
596  */
597  //----------------------------------------------------------------------------------------------
598  void* _le_mem_VarAllocTracer
599  (
600  le_mem_PoolRef_t pool, ///< [IN] The pool activity we're tracing.
601  size_t size, ///< [IN] The size of block to allocate
602  _le_mem_AllocFunc_t funcPtr, ///< [IN] Pointer to the mem function in question.
603  const char* poolFunction, ///< [IN] The pool function being called.
604  const char* file, ///< [IN] The file the call came from.
605  const char* callingfunction, ///< [IN] The function calling into the pool.
606  size_t line ///< [IN] The line in the function where the call
607  /// occurred.
608  );
609 
610  //----------------------------------------------------------------------------------------------
611  /**
612  * Internal function used to trace memory pool activity.
613  */
614  //----------------------------------------------------------------------------------------------
615  void _le_mem_Trace
616  (
617  le_mem_PoolRef_t pool, ///< [IN] The pool activity we're tracing.
618  const char* file, ///< [IN] The file the call came from.
619  const char* callingfunction, ///< [IN] The function calling into the pool.
620  size_t line, ///< [IN] The line in the function where the call
621  /// occurred.
622  const char* poolFunction, ///< [IN] The pool function being called.
623  void* blockPtr ///< [IN] Block allocated/freed.
624  );
625 #endif
626 
627 
628 /// @cond HIDDEN_IN_USER_DOCS
629 //--------------------------------------------------------------------------------------------------
630 /**
631  * Internal function used to implement le_mem_InitStaticPool() with automatic component scoping
632  * of pool names.
633  */
634 //--------------------------------------------------------------------------------------------------
635 le_mem_PoolRef_t _le_mem_InitStaticPool
636 (
637  const char* componentName, ///< [IN] Name of the component.
638  const char* name, ///< [IN] Name of the pool inside the component.
639  size_t numBlocks, ///< [IN] Number of members in the pool by default
640  size_t objSize, ///< [IN] Size of the individual objects to be allocated from this pool
641  /// (in bytes), e.g., sizeof(MyObject_t).
642  le_mem_Pool_t* poolPtr, ///< [IN] Pointer to pre-allocated pool header.
643  void* poolDataPtr ///< [IN] Pointer to pre-allocated pool data.
644 );
645 /// @endcond
646 
647 
648 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
649 //--------------------------------------------------------------------------------------------------
650 /** @cond HIDDEN_IN_USER_DOCS
651  *
652  * Internal function used to implement le_mem_CreatePool() with automatic component scoping
653  * of pool names.
654  */
655 //--------------------------------------------------------------------------------------------------
656 le_mem_PoolRef_t _le_mem_CreatePool
657 (
658  const char* componentName, ///< [IN] Name of the component.
659  const char* name, ///< [IN] Name of the pool inside the component.
660  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
661  /// (in bytes), e.g., sizeof(MyObject_t).
662 );
663 /// @endcond
664 //--------------------------------------------------------------------------------------------------
665 /**
666  * Creates an empty memory pool.
667  *
668  * @return
669  * Reference to the memory pool object.
670  *
671  * @note
672  * On failure, the process exits, so you don't have to worry about checking the returned
673  * reference for validity.
674  */
675 //--------------------------------------------------------------------------------------------------
676 static inline le_mem_PoolRef_t le_mem_CreatePool
677 (
678  const char* name, ///< [IN] Name of the pool inside the component.
679  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
680  /// (in bytes), e.g., sizeof(MyObject_t).
681 )
682 {
683  return _le_mem_CreatePool(STRINGIZE(LE_COMPONENT_NAME), name, objSize);
684 }
685 #else /* if not LE_CONFIG_MEM_POOL_NAMES_ENABLED */
686 //--------------------------------------------------------------------------------------------------
687 /** @cond HIDDEN_IN_USER_DOCS
688  *
689  * Internal function used to implement le_mem_CreatePool() with automatic component scoping
690  * of pool names.
691  */
692 //--------------------------------------------------------------------------------------------------
693 le_mem_PoolRef_t _le_mem_CreatePool
694 (
695  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
696  /// (in bytes), e.g., sizeof(MyObject_t).
697 );
698 /// @endcond
699 //--------------------------------------------------------------------------------------------------
700 /**
701  * Creates an empty memory pool.
702  *
703  * @return
704  * Reference to the memory pool object.
705  *
706  * @note
707  * On failure, the process exits, so you don't have to worry about checking the returned
708  * reference for validity.
709  */
710 //--------------------------------------------------------------------------------------------------
711 LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreatePool
712 (
713  const char* name, ///< [IN] Name of the pool inside the component.
714  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
715  /// (in bytes), e.g., sizeof(MyObject_t).
716 )
717 {
718  return _le_mem_CreatePool(objSize);
719 }
720 #endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */
721 
722 //--------------------------------------------------------------------------------------------------
723 /**
724  * Number of words in a memory pool, given number of blocks and object size.
725  *
726  * @note Only used internally
727  */
728 //--------------------------------------------------------------------------------------------------
729 #define LE_MEM_POOL_WORDS(numBlocks, objSize) \
730  ((numBlocks)*(((sizeof(le_mem_Pool_t*) + sizeof(size_t)) /* sizeof(MemBlock_t) */ + \
731  (((objSize)<sizeof(le_sls_Link_t))?sizeof(le_sls_Link_t):(objSize))+ \
732  sizeof(uint32_t)*LE_CONFIG_NUM_GUARD_BAND_WORDS*2+ \
733  sizeof(size_t) - 1) / sizeof(size_t)))
734 
735 //--------------------------------------------------------------------------------------------------
736 /**
737  * Calculate the number of blocks for a pool.
738  *
739  * @param name Pool name.
740  * @param def Default number of blocks.
741  *
742  * @return Number of blocks, either the value provided by <name>_POOL_SIZE if it is defined, or
743  * <def>. To be valid, <name>_POOL_SIZE must be defined as ,<value> (note the leading
744  * comma).
745  */
746 //--------------------------------------------------------------------------------------------------
747 #define LE_MEM_BLOCKS(name, def) (LE_DEFAULT(CAT(_mem_, CAT(name, _POOL_SIZE)), (def)))
748 
749 //--------------------------------------------------------------------------------------------------
750 /**
751  * Declare variables for a static memory pool.
752  *
753  * In a static memory pool initial pool memory is statically allocated at compile time, ensuring
754  * pool can be created with at least some elements. This is especially valuable on embedded
755  * systems.
756  *
757  * @param name Pool name.
758  * @param numBlocks Default number of blocks. This can be overriden in components using the "pools"
759  * directive.
760  * @param objSize Size of each block in the pool.
761  */
762 /*
763  * Internal Note: size_t is used instead of uint8_t to ensure alignment on platforms where
764  * alignment matters.
765  */
766 //--------------------------------------------------------------------------------------------------
767 #if LE_CONFIG_MEM_POOLS
768 # define LE_MEM_DEFINE_STATIC_POOL(name, numBlocks, objSize) \
769  static le_mem_Pool_t _mem_##name##Pool; \
770  static size_t _mem_##name##Data[LE_MEM_POOL_WORDS(LE_MEM_BLOCKS(name, numBlocks), objSize)]
771 #else
772 # define LE_MEM_DEFINE_STATIC_POOL(name, numBlocks, objSize) \
773  static le_mem_Pool_t _mem_##name##Pool
774 #endif
775 
776 //--------------------------------------------------------------------------------------------------
777 /**
778  * Declare variables for a static memory pool, must specify which object section the variable goes
779  * into
780  *
781  * By default static memory will the assigned to the bss or data section of the final object.
782  * This macro tells the linker to assign to variable to a specific section, sectionName.
783  * Essentially a "__attribute__((section("sectionName")))" will be added after the variable
784  * declaration.
785  *
786  *
787  * @param name Pool name.
788  * @param numBlocks Default number of blocks. This can be overridden in components using the "pools"
789  * directive.
790  * @param objSize Size of each block in the pool.
791  * @param sectionName __attribute__((section("section"))) will be added to the pool declaration so the
792  memory is associated with a the specific section instead of bss, data,..
793  */
794 /*
795  * Internal Note: size_t is used instead of uint8_t to ensure alignment on platforms where
796  * alignment matters.
797  */
798 //--------------------------------------------------------------------------------------------------
799 #if LE_CONFIG_MEM_POOLS
800 # define LE_MEM_DEFINE_STATIC_POOL_IN_SECTION(name, numBlocks, objSize, sectionName) \
801  static le_mem_Pool_t _mem_##name##Pool __attribute__((section(sectionName))); \
802  static size_t _mem_##name##Data[LE_MEM_POOL_WORDS( \
803  LE_MEM_BLOCKS(name, numBlocks), objSize)] __attribute__((section(sectionName)))
804 #else
805 # define LE_MEM_DEFINE_STATIC_POOL_IN_SECTION(name, numBlocks, objSize, sectionName) \
806  static le_mem_Pool_t _mem_##name##Pool __attribute__((section(sectionName)));
807 #endif
808 
809 //--------------------------------------------------------------------------------------------------
810 /**
811  * Initialize an empty static memory pool.
812  *
813  * @param name Pool name.
814  * @param numBlocks Default number of blocks. This can be overriden in components using the "pools"
815  * directive.
816  * @param objSize Size of each block in the pool.
817  *
818  * @return
819  * Reference to the memory pool object.
820  *
821  * @note
822  * This function cannot fail.
823  */
824 //--------------------------------------------------------------------------------------------------
825 #if LE_CONFIG_MEM_POOLS
826 # define le_mem_InitStaticPool(name, numBlocks, objSize) \
827  (inline_static_assert( \
828  sizeof(_mem_##name##Data) == \
829  sizeof(size_t[LE_MEM_POOL_WORDS(LE_MEM_BLOCKS(name, numBlocks), objSize)]), \
830  "initial pool size does not match definition"), \
831  _le_mem_InitStaticPool(STRINGIZE(LE_COMPONENT_NAME), #name, \
832  LE_MEM_BLOCKS(name, numBlocks), (objSize), &_mem_##name##Pool, _mem_##name##Data))
833 #else
834 # define le_mem_InitStaticPool(name, numBlocks, objSize) \
835  _le_mem_InitStaticPool(STRINGIZE(LE_COMPONENT_NAME), #name, \
836  LE_MEM_BLOCKS(name, numBlocks), (objSize), &_mem_##name##Pool, NULL)
837 #endif
838 
839 //--------------------------------------------------------------------------------------------------
840 /**
841  * Expands the size of a memory pool.
842  *
843  * @return Reference to the memory pool object (the same value passed into it).
844  *
845  * @note On failure, the process exits, so you don't have to worry about checking the returned
846  * reference for validity.
847  */
848 //--------------------------------------------------------------------------------------------------
849 le_mem_PoolRef_t le_mem_ExpandPool
850 (
851  le_mem_PoolRef_t pool, ///< [IN] Pool to be expanded.
852  size_t numObjects ///< [IN] Number of objects to add to the pool.
853 );
854 
855 
856 
857 #if !LE_CONFIG_MEM_TRACE
858  //----------------------------------------------------------------------------------------------
859  /**
860  * Attempts to allocate an object from a pool.
861  *
862  * @return
863  * Pointer to the allocated object, or NULL if the pool doesn't have any free objects
864  * to allocate.
865  */
866  //----------------------------------------------------------------------------------------------
867  void* le_mem_TryAlloc
868  (
869  le_mem_PoolRef_t pool ///< [IN] Pool from which the object is to be allocated.
870  );
871 #else
872  /// @cond HIDDEN_IN_USER_DOCS
873  void* _le_mem_TryAlloc(le_mem_PoolRef_t pool);
874  /// @endcond
875 
876 # define le_mem_TryAlloc(pool) \
877  _le_mem_AllocTracer(pool, \
878  _le_mem_TryAlloc, \
879  "le_mem_TryAlloc", \
880  STRINGIZE(LE_FILENAME), \
881  __FUNCTION__, \
882  __LINE__)
883 
884 #endif
885 
886 
887 #if !LE_CONFIG_MEM_TRACE
888  //----------------------------------------------------------------------------------------------
889  /**
890  * Allocates an object from a pool or logs a fatal error and terminates the process if the pool
891  * doesn't have any free objects to allocate.
892  *
893  * @return Pointer to the allocated object.
894  *
895  * @note On failure, the process exits, so you don't have to worry about checking the
896  * returned pointer for validity.
897  */
898  //----------------------------------------------------------------------------------------------
899  void* le_mem_AssertAlloc
900  (
901  le_mem_PoolRef_t pool ///< [IN] Pool from which the object is to be allocated.
902  );
903 #else
904  /// @cond HIDDEN_IN_USER_DOCS
905  void* _le_mem_AssertAlloc(le_mem_PoolRef_t pool);
906  /// @endcond
907 
908 # define le_mem_AssertAlloc(pool) \
909  _le_mem_AllocTracer(pool, \
910  _le_mem_AssertAlloc, \
911  "le_mem_AssertAlloc", \
912  STRINGIZE(LE_FILENAME), \
913  __FUNCTION__, \
914  __LINE__)
915 #endif
916 
917 
918 #if !LE_CONFIG_MEM_TRACE
919  //----------------------------------------------------------------------------------------------
920  /**
921  * Allocates an object from a pool or logs a warning and expands the pool if the pool
922  * doesn't have any free objects to allocate.
923  *
924  * @return Pointer to the allocated object.
925  *
926  * @note On failure, the process exits, so you don't have to worry about checking the
927  * returned pointer for validity.
928  */
929  //----------------------------------------------------------------------------------------------
930  void* le_mem_ForceAlloc
931  (
932  le_mem_PoolRef_t pool ///< [IN] Pool from which the object is to be allocated.
933  );
934 #else
935  /// @cond HIDDEN_IN_USER_DOCS
936  void* _le_mem_ForceAlloc(le_mem_PoolRef_t pool);
937  /// @endcond
938 
939 # define le_mem_ForceAlloc(pool) \
940  _le_mem_AllocTracer(pool, \
941  _le_mem_ForceAlloc, \
942  "le_mem_ForceAlloc", \
943  STRINGIZE(LE_FILENAME), \
944  __FUNCTION__, \
945  __LINE__)
946 #endif
947 
948 
949 #if !LE_CONFIG_MEM_TRACE
950  //----------------------------------------------------------------------------------------------
951  /**
952  * Attempts to allocate an object from a pool.
953  *
954  * @return
955  * Pointer to the allocated object, or NULL if the pool doesn't have any free objects
956  * to allocate.
957  */
958  //----------------------------------------------------------------------------------------------
959  void* le_mem_TryVarAlloc
960  (
961  le_mem_PoolRef_t pool, ///< [IN] Pool from which the object is to be allocated.
962  size_t size ///< [IN] The size of block to allocate
963  );
964 #else
965  /// @cond HIDDEN_IN_USER_DOCS
966  void* _le_mem_TryVarAlloc(le_mem_PoolRef_t pool, size_t size);
967  /// @endcond
968 
969 # define le_mem_TryVarAlloc(pool, size) \
970  _le_mem_VarAllocTracer(pool, \
971  size, \
972  _le_mem_TryVarAlloc, \
973  "le_mem_TryVarAlloc", \
974  STRINGIZE(LE_FILENAME), \
975  __FUNCTION__, \
976  __LINE__)
977 
978 #endif
979 
980 
981 #if !LE_CONFIG_MEM_TRACE
982  //----------------------------------------------------------------------------------------------
983  /**
984  * Allocates an object from a pool or logs a fatal error and terminates the process if the pool
985  * doesn't have any free objects to allocate.
986  *
987  * @return Pointer to the allocated object.
988  *
989  * @note On failure, the process exits, so you don't have to worry about checking the
990  * returned pointer for validity.
991  */
992  //----------------------------------------------------------------------------------------------
994  (
995  le_mem_PoolRef_t pool, ///< [IN] Pool from which the object is to be allocated.
996  size_t size ///< [IN] The size of block to allocate
997  );
998 #else
999  /// @cond HIDDEN_IN_USER_DOCS
1000  void* _le_mem_AssertVarAlloc(le_mem_PoolRef_t pool, size_t size);
1001  /// @endcond
1002 
1003 # define le_mem_AssertVarAlloc(pool, size) \
1004  _le_mem_VarAllocTracer(pool, \
1005  size, \
1006  _le_mem_AssertVarAlloc, \
1007  "le_mem_AssertVarAlloc", \
1008  STRINGIZE(LE_FILENAME), \
1009  __FUNCTION__, \
1010  __LINE__)
1011 #endif
1012 
1013 
1014 #if !LE_CONFIG_MEM_TRACE
1015  //----------------------------------------------------------------------------------------------
1016  /**
1017  * Allocates an object from a pool or logs a warning and expands the pool if the pool
1018  * doesn't have any free objects to allocate.
1019  *
1020  * @return Pointer to the allocated object.
1021  *
1022  * @note On failure, the process exits, so you don't have to worry about checking the
1023  * returned pointer for validity.
1024  */
1025  //----------------------------------------------------------------------------------------------
1026  void* le_mem_ForceVarAlloc
1027  (
1028  le_mem_PoolRef_t pool, ///< [IN] Pool from which the object is to be allocated.
1029  size_t size ///< [IN] The size of block to allocate
1030  );
1031 #else
1032  /// @cond HIDDEN_IN_USER_DOCS
1033  void* _le_mem_ForceVarAlloc(le_mem_PoolRef_t pool, size_t size);
1034  /// @endcond
1035 
1036 # define le_mem_ForceVarAlloc(pool, size) \
1037  _le_mem_VarAllocTracer(pool, \
1038  size, \
1039  _le_mem_ForceVarAlloc, \
1040  "le_mem_ForceVarAlloc", \
1041  STRINGIZE(LE_FILENAME), \
1042  __FUNCTION__, \
1043  __LINE__)
1044 #endif
1045 
1046 //--------------------------------------------------------------------------------------------------
1047 /**
1048  * Attempts to allocate an object from a pool using the configured allocation failure behaviour
1049  * (force or assert). Forced allocation will expand into the heap if the configured pool size is
1050  * exceeded, while assert allocation will abort the program with an error if the pool cannot satisfy
1051  * the request.
1052  *
1053  * @param pool Pool from which the object is to be allocated.
1054  *
1055  * @return Pointer to the allocated object.
1056  */
1057 //--------------------------------------------------------------------------------------------------
1058 #if LE_CONFIG_MEM_ALLOC_FORCE
1059 # define le_mem_Alloc(pool) le_mem_ForceAlloc(pool)
1060 #elif LE_CONFIG_MEM_ALLOC_ASSERT
1061 # define le_mem_Alloc(pool) le_mem_AssertAlloc(pool)
1062 #else
1063 # error "No supported allocation scheme selected!"
1064 #endif
1065 
1066 //--------------------------------------------------------------------------------------------------
1067 /**
1068  * Attempts to allocate a variably-sized object from a pool using the configured allocation failure
1069  * behaviour (force or assert). Forced allocation will expand into the heap if the configured pool
1070  * size is exceeded, while assert allocation will abort the program with an error if the pool cannot
1071  * satisfy the request.
1072  *
1073  * @param pool Pool from which the object is to be allocated.
1074  * @param size The size of block to allocate.
1075  *
1076  * @return Pointer to the allocated object.
1077  */
1078 //--------------------------------------------------------------------------------------------------
1079 #if LE_CONFIG_MEM_ALLOC_FORCE
1080 # define le_mem_VarAlloc(pool, size) le_mem_ForceVarAlloc((pool), (size))
1081 #elif LE_CONFIG_MEM_ALLOC_ASSERT
1082 # define le_mem_VarAlloc(pool, size) le_mem_AssertVarAlloc((pool), (size))
1083 #else
1084 # error "No supported allocation scheme selected!"
1085 #endif
1086 
1087 //--------------------------------------------------------------------------------------------------
1088 /**
1089  * Sets the number of objects that are added when le_mem_ForceAlloc expands the pool.
1090  *
1091  * @return
1092  * Nothing.
1093  *
1094  * @note
1095  * The default value is one.
1096  */
1097 //--------------------------------------------------------------------------------------------------
1099 (
1100  le_mem_PoolRef_t pool, ///< [IN] Pool to set the number of objects for.
1101  size_t numObjects ///< [IN] Number of objects that is added when
1102  /// le_mem_ForceAlloc expands the pool.
1103 );
1104 
1105 
1106 #if !LE_CONFIG_MEM_TRACE
1107  //----------------------------------------------------------------------------------------------
1108  /**
1109  * Releases an object. If the object's reference count has reached zero, it will be destructed
1110  * and its memory will be put back into the pool for later reuse.
1111  *
1112  * @return
1113  * Nothing.
1114  *
1115  * @warning
1116  * - <b>Don't EVER access an object after releasing it.</b> It might not exist anymore.
1117  * - If the object has a destructor accessing a data structure shared by multiple
1118  * threads, ensure you hold the mutex (or take other measures to prevent races) before
1119  * releasing the object.
1120  */
1121  //----------------------------------------------------------------------------------------------
1122  void le_mem_Release
1123  (
1124  void* objPtr ///< [IN] Pointer to the object to be released.
1125  );
1126 #else
1127  /// @cond HIDDEN_IN_USER_DOCS
1128  void _le_mem_Release(void* objPtr);
1129  /// @endcond
1130 
1131 # define le_mem_Release(objPtr) \
1132  _le_mem_Trace(_le_mem_GetBlockPool(objPtr), \
1133  STRINGIZE(LE_FILENAME), \
1134  __FUNCTION__, \
1135  __LINE__, \
1136  "le_mem_Release", \
1137  (objPtr)); \
1138  _le_mem_Release(objPtr);
1139 #endif
1140 
1141 
1142 #if !LE_CONFIG_MEM_TRACE
1143  //----------------------------------------------------------------------------------------------
1144  /**
1145  * Increments the reference count on an object by 1.
1146  *
1147  * See @ref mem_ref_counting for more information.
1148  *
1149  * @return
1150  * Nothing.
1151  */
1152  //----------------------------------------------------------------------------------------------
1153  void le_mem_AddRef
1154  (
1155  void* objPtr ///< [IN] Pointer to the object.
1156  );
1157 #else
1158  /// @cond HIDDEN_IN_USER_DOCS
1159  void _le_mem_AddRef(void* objPtr);
1160  /// @endcond
1161 
1162 # define le_mem_AddRef(objPtr) \
1163  _le_mem_Trace(_le_mem_GetBlockPool(objPtr), \
1164  STRINGIZE(LE_FILENAME), \
1165  __FUNCTION__, \
1166  __LINE__, \
1167  "le_mem_AddRef", \
1168  (objPtr)); \
1169  _le_mem_AddRef(objPtr);
1170 #endif
1171 
1172 //--------------------------------------------------------------------------------------------------
1173 /**
1174  * Fetches the size of a block (in bytes).
1175  *
1176  * @return
1177  * Object size, in bytes.
1178  */
1179 //--------------------------------------------------------------------------------------------------
1180 size_t le_mem_GetBlockSize
1181 (
1182  void* objPtr ///< [IN] Pointer to the object to get size of.
1183 );
1184 
1185 //----------------------------------------------------------------------------------------------
1186 /**
1187  * Fetches the reference count on an object.
1188  *
1189  * See @ref mem_ref_counting for more information.
1190  *
1191  * @warning If using this in a multi-threaded application that shares memory pool objects
1192  * between threads, steps must be taken to coordinate the threads (e.g., using a mutex)
1193  * to ensure that the reference count value fetched remains correct when it is used.
1194  *
1195  * @return
1196  * The reference count on the object.
1197  */
1198 //----------------------------------------------------------------------------------------------
1199 size_t le_mem_GetRefCount
1200 (
1201  void* objPtr ///< [IN] Pointer to the object.
1202 );
1203 
1204 
1205 //--------------------------------------------------------------------------------------------------
1206 /**
1207  * Sets the destructor function for a specified pool.
1208  *
1209  * See @ref mem_destructors for more information.
1210  *
1211  * @return
1212  * Nothing.
1213  */
1214 //--------------------------------------------------------------------------------------------------
1216 (
1217  le_mem_PoolRef_t pool, ///< [IN] The pool.
1218  le_mem_Destructor_t destructor ///< [IN] Destructor function.
1219 );
1220 
1221 
1222 //--------------------------------------------------------------------------------------------------
1223 /**
1224  * Fetches the statistics for a specified pool.
1225  *
1226  * @return
1227  * Nothing. Uses output parameter instead.
1228  */
1229 //--------------------------------------------------------------------------------------------------
1230 void le_mem_GetStats
1231 (
1232  le_mem_PoolRef_t pool, ///< [IN] Pool where stats are to be fetched.
1233  le_mem_PoolStats_t* statsPtr ///< [OUT] Pointer to where the stats will be stored.
1234 );
1235 
1236 
1237 //--------------------------------------------------------------------------------------------------
1238 /**
1239  * Resets the statistics for a specified pool.
1240  *
1241  * @return
1242  * Nothing.
1243  */
1244 //--------------------------------------------------------------------------------------------------
1245 void le_mem_ResetStats
1246 (
1247  le_mem_PoolRef_t pool ///< [IN] Pool where stats are to be reset.
1248 );
1249 
1250 
1251 //--------------------------------------------------------------------------------------------------
1252 /**
1253  * Gets the memory pool's name, including the component name prefix.
1254  *
1255  * If the pool were given the name "myPool" and the component that it belongs to is called
1256  * "myComponent", then the full pool name returned by this function would be "myComponent.myPool".
1257  *
1258  * @return
1259  * LE_OK if successful.
1260  * LE_OVERFLOW if the name was truncated to fit in the provided buffer.
1261  */
1262 //--------------------------------------------------------------------------------------------------
1264 (
1265  le_mem_PoolRef_t pool, ///< [IN] The memory pool.
1266  char* namePtr, ///< [OUT] Buffer to store the name of the memory pool.
1267  size_t bufSize ///< [IN] Size of the buffer namePtr points to.
1268 );
1269 
1270 
1271 //--------------------------------------------------------------------------------------------------
1272 /**
1273  * Checks if the specified pool is a sub-pool.
1274  *
1275  * @return
1276  * true if it is a sub-pool.
1277  * false if it is not a sub-pool.
1278  */
1279 //--------------------------------------------------------------------------------------------------
1280 bool le_mem_IsSubPool
1281 (
1282  le_mem_PoolRef_t pool ///< [IN] The memory pool.
1283 );
1284 
1285 
1286 //--------------------------------------------------------------------------------------------------
1287 /**
1288  * Fetches the number of objects a specified pool can hold (this includes both the number of
1289  * free and in-use objects).
1290  *
1291  * @return
1292  * Total number of objects.
1293  */
1294 //--------------------------------------------------------------------------------------------------
1295 size_t le_mem_GetObjectCount
1296 (
1297  le_mem_PoolRef_t pool ///< [IN] Pool where number of objects is to be fetched.
1298 );
1299 
1300 
1301 //--------------------------------------------------------------------------------------------------
1302 /**
1303  * Fetches the size of the objects in a specified pool (in bytes).
1304  *
1305  * @return
1306  * Object size, in bytes.
1307  */
1308 //--------------------------------------------------------------------------------------------------
1309 size_t le_mem_GetObjectSize
1310 (
1311  le_mem_PoolRef_t pool ///< [IN] Pool where object size is to be fetched.
1312 );
1313 
1314 
1315 //--------------------------------------------------------------------------------------------------
1316 /**
1317  * Fetches the total size of the object including all the memory overhead in a given pool (in bytes).
1318  *
1319  * @return
1320  * Total object memory size, in bytes.
1321  */
1322 //--------------------------------------------------------------------------------------------------
1324 (
1325  le_mem_PoolRef_t pool ///< [IN] The pool whose object memory size is to be fetched.
1326 );
1327 
1328 
1329 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
1330 //--------------------------------------------------------------------------------------------------
1331 /** @cond HIDDEN_IN_USER_DOCS
1332  *
1333  * Internal function used to implement le_mem_FindPool() with automatic component scoping
1334  * of pool names.
1335  */
1336 //--------------------------------------------------------------------------------------------------
1337 le_mem_PoolRef_t _le_mem_FindPool
1338 (
1339  const char* componentName, ///< [IN] Name of the component.
1340  const char* name ///< [IN] Name of the pool inside the component.
1341 );
1342 /// @endcond
1343 //--------------------------------------------------------------------------------------------------
1344 /**
1345  * Finds a pool based on the pool's name.
1346  *
1347  * @return
1348  * Reference to the pool, or NULL if the pool doesn't exist.
1349  */
1350 //--------------------------------------------------------------------------------------------------
1351 static inline le_mem_PoolRef_t le_mem_FindPool
1353  const char* name ///< [IN] Name of the pool inside the component.
1354 )
1355 {
1356  return _le_mem_FindPool(STRINGIZE(LE_COMPONENT_NAME), name);
1357 }
1358 #else
1359 //--------------------------------------------------------------------------------------------------
1360 /**
1361  * Finds a pool based on the pool's name.
1362  *
1363  * @return
1364  * Reference to the pool, or NULL if the pool doesn't exist.
1365  */
1366 //--------------------------------------------------------------------------------------------------
1367 LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_FindPool
1368 (
1369  const char* name ///< [IN] Name of the pool inside the component.
1370 )
1371 {
1372  return NULL;
1373 }
1374 #endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1375 
1376 
1377 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
1378 //--------------------------------------------------------------------------------------------------
1379 /** @cond HIDDEN_IN_USER_DOCS
1380  *
1381  * Internal function used to implement le_mem_CreateSubPool() with automatic component scoping
1382  * of pool names.
1383  */
1384 //--------------------------------------------------------------------------------------------------
1385 le_mem_PoolRef_t _le_mem_CreateSubPool
1386 (
1387  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1388  const char* componentName, ///< [IN] Name of the component.
1389  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1390  /// sub-pool).
1391  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
1392 );
1393 /// @endcond
1394 //--------------------------------------------------------------------------------------------------
1395 /**
1396  * Creates a sub-pool.
1397  *
1398  * See @ref mem_sub_pools for more information.
1399  *
1400  * @return
1401  * Reference to the sub-pool.
1402  */
1403 //--------------------------------------------------------------------------------------------------
1404 static inline le_mem_PoolRef_t le_mem_CreateSubPool
1406  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1407  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1408  /// sub-pool).
1409  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
1410 )
1411 {
1412  return _le_mem_CreateSubPool(superPool, STRINGIZE(LE_COMPONENT_NAME), name, numObjects);
1413 }
1414 #else /* if not LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1415 //--------------------------------------------------------------------------------------------------
1416 /** @cond HIDDEN_IN_USER_DOCS
1417  *
1418  * Internal function used to implement le_mem_CreateSubPool() with automatic component scoping
1419  * of pool names.
1420  */
1421 //--------------------------------------------------------------------------------------------------
1422 le_mem_PoolRef_t _le_mem_CreateSubPool
1423 (
1424  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1425  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
1426 );
1427 /// @endcond
1428 //--------------------------------------------------------------------------------------------------
1429 /**
1430  * Creates a sub-pool.
1431  *
1432  * See @ref mem_sub_pools for more information.
1433  *
1434  * @return
1435  * Reference to the sub-pool.
1436  */
1437 //--------------------------------------------------------------------------------------------------
1438 LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreateSubPool
1439 (
1440  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1441  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1442  /// sub-pool).
1443  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
1444 )
1445 {
1446  return _le_mem_CreateSubPool(superPool, numObjects);
1447 }
1448 #endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1449 
1450 
1451 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
1452 //--------------------------------------------------------------------------------------------------
1453 /** @cond HIDDEN_IN_USER_DOCS
1454  *
1455  * Internal function used to implement le_mem_CreateSubPool() with automatic component scoping
1456  * of pool names.
1457  */
1458 //--------------------------------------------------------------------------------------------------
1459 le_mem_PoolRef_t _le_mem_CreateReducedPool
1460 (
1461  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1462  const char* componentName, ///< [IN] Name of the component.
1463  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1464  /// sub-pool).
1465  size_t numObjects, ///< [IN] Number of objects to take from the super-pool.
1466  size_t objSize ///< [IN] Minimum size of objects in the subpool.
1467 );
1468 /// @endcond
1469 //--------------------------------------------------------------------------------------------------
1470 /**
1471  * Creates a sub-pool of smaller objects.
1472  *
1473  * See @ref mem_reduced_pools for more information.
1474  *
1475  * @return
1476  * Reference to the sub-pool.
1477  */
1478 //--------------------------------------------------------------------------------------------------
1479 static inline le_mem_PoolRef_t le_mem_CreateReducedPool
1481  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1482  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1483  /// sub-pool).
1484  size_t numObjects, ///< [IN] Minimum number of objects in the subpool
1485  ///< by default.
1486  size_t objSize ///< [IN] Minimum size of objects in the subpool.
1487 )
1488 {
1489  return _le_mem_CreateReducedPool(superPool, STRINGIZE(LE_COMPONENT_NAME), name, numObjects, objSize);
1490 }
1491 #else /* if not LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1492 //--------------------------------------------------------------------------------------------------
1493 /** @cond HIDDEN_IN_USER_DOCS
1494  *
1495  * Internal function used to implement le_mem_CreateSubPool() with automatic component scoping
1496  * of pool names.
1497  */
1498 //--------------------------------------------------------------------------------------------------
1499 le_mem_PoolRef_t _le_mem_CreateReducedPool
1500 (
1501  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1502  size_t numObjects, ///< [IN] Minimum number of objects in the subpool
1503  ///< by default.
1504  size_t objSize ///< [IN] Minimum size of objects in the subpool.
1505 );
1506 /// @endcond
1507 //--------------------------------------------------------------------------------------------------
1508 /**
1509  * Creates a sub-pool of smaller objects.
1510  *
1511  * See @ref mem_reduced_pools for more information.
1512  *
1513  * @return
1514  * Reference to the sub-pool.
1515  */
1516 //--------------------------------------------------------------------------------------------------
1518 (
1519  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1520  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1521  /// sub-pool).
1522  size_t numObjects, ///< [IN] Minimum number of objects in the subpool
1523  ///< by default.
1524  size_t objSize ///< [IN] Minimum size of objects in the subpool.
1525 )
1526 {
1527  return _le_mem_CreateReducedPool(superPool, numObjects, objSize);
1528 }
1529 #endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1530 
1531 
1532 //--------------------------------------------------------------------------------------------------
1533 /**
1534  * Deletes a sub-pool.
1535  *
1536  * See @ref mem_sub_pools for more information.
1537  *
1538  * @return
1539  * Nothing.
1540  */
1541 //--------------------------------------------------------------------------------------------------
1543 (
1544  le_mem_PoolRef_t subPool ///< [IN] Sub-pool to be deleted.
1545 );
1546 
1547 #if LE_CONFIG_RTOS
1548 //--------------------------------------------------------------------------------------------------
1549 /**
1550  * Compress memory pools ready for hibernate-to-RAM
1551  *
1552  * This compresses the memory pools ready for hibernation. All Legato tasks must remain
1553  * suspended until after le_mem_Resume() is called.
1554  *
1555  * @return Nothing
1556  */
1557 //--------------------------------------------------------------------------------------------------
1558 void le_mem_Hibernate
1559 (
1560  void **freeStartPtr, ///< [OUT] Beginning of unused memory which does not need to be
1561  ///< preserved in hibernation
1562  void **freeEndPtr ///< [OUT] End of unused memory
1563 );
1564 
1565 //--------------------------------------------------------------------------------------------------
1566 /**
1567  * Decompress memory pools after waking from hibernate-to-RAM
1568  *
1569  * This decompresses memory pools after hibernation. After this function returns, Legato tasks
1570  * may be resumed.
1571  *
1572  * @return Nothing
1573  */
1574 //--------------------------------------------------------------------------------------------------
1575 void le_mem_Resume
1576 (
1577  void
1578 );
1579 
1580 #endif /* end LE_CONFIG_RTOS */
1581 
1582 //--------------------------------------------------------------------------------------------------
1583 /**
1584  * Duplicate a UTF-8 string. The space for the duplicate string will be allocated from the provided
1585  * memory pool using le_mem_VarAlloc().
1586  *
1587  * @return The allocated duplicate of the string. This may later be released with
1588  * le_mem_Release().
1589  */
1590 //--------------------------------------------------------------------------------------------------
1591 char *le_mem_StrDup
1592 (
1593  le_mem_PoolRef_t poolRef, ///< Pool from which to allocate the string.
1594  const char *srcStr ///< String to duplicate.
1595 );
1596 
1597 #endif // LEGATO_MEM_INCLUDE_GUARD
size_t numBlocksToForce
Definition: le_mem.h:524
size_t numFree
Number of free objects currently available in this pool.
Definition: le_mem.h:559
uint64_t numAllocations
Definition: le_mem.h:511
void * le_mem_TryAlloc(le_mem_PoolRef_t pool)
le_sls_List_t freeList
List of free memory blocks.
Definition: le_mem.h:516
void * le_mem_TryVarAlloc(le_mem_PoolRef_t pool, size_t size)
le_mem_PoolRef_t le_mem_ExpandPool(le_mem_PoolRef_t pool, size_t numObjects)
le_result_t
Definition: le_basics.h:46
void * le_mem_AssertAlloc(le_mem_PoolRef_t pool)
void le_mem_GetStats(le_mem_PoolRef_t pool, le_mem_PoolStats_t *statsPtr)
void le_mem_Resume(void)
size_t numBlocksInUse
Number of currently allocated blocks.
Definition: le_mem.h:555
size_t totalBlocks
Definition: le_mem.h:521
struct le_mem_Pool * superPoolPtr
Definition: le_mem.h:505
#define STRINGIZE(x)
Definition: le_basics.h:234
void le_mem_SetDestructor(le_mem_PoolRef_t pool, le_mem_Destructor_t destructor)
void * le_mem_AssertVarAlloc(le_mem_PoolRef_t pool, size_t size)
uint64_t numAllocs
Number of times an object has been allocated from this pool.
Definition: le_mem.h:558
size_t maxNumBlocksUsed
Maximum number of allocated blocks at any one time.
Definition: le_mem.h:513
size_t maxNumBlocksUsed
Maximum number of allocated blocks at any one time.
Definition: le_mem.h:556
void * le_mem_ForceVarAlloc(le_mem_PoolRef_t pool, size_t size)
void le_mem_ResetStats(le_mem_PoolRef_t pool)
size_t numOverflows
Number of times le_mem_ForceAlloc() had to expand the pool.
Definition: le_mem.h:557
static le_mem_PoolRef_t le_mem_CreateReducedPool(le_mem_PoolRef_t superPool, const char *name, size_t numObjects, size_t objSize)
Definition: le_mem.h:1480
void le_mem_SetNumObjsToForce(le_mem_PoolRef_t pool, size_t numObjects)
size_t numOverflows
Number of times le_mem_ForceAlloc() had to expand pool.
Definition: le_mem.h:510
char * le_mem_StrDup(le_mem_PoolRef_t poolRef, const char *srcStr)
void le_mem_DeleteSubPool(le_mem_PoolRef_t subPool)
struct le_mem_Pool * le_mem_PoolRef_t
Definition: le_mem.h:545
le_result_t le_mem_GetName(le_mem_PoolRef_t pool, char *namePtr, size_t bufSize)
bool le_mem_IsSubPool(le_mem_PoolRef_t pool)
void le_mem_Release(void *objPtr)
Definition: le_mem.h:553
static le_mem_PoolRef_t le_mem_FindPool(const char *name)
Definition: le_mem.h:1352
size_t blockSize
Number of bytes in a block, including all overhead.
Definition: le_mem.h:520
void(* le_mem_Destructor_t)(void *objPtr)
Definition: le_mem.h:487
size_t le_mem_GetObjectCount(le_mem_PoolRef_t pool)
Definition: le_mem.h:502
Definition: le_singlyLinkedList.h:201
size_t le_mem_GetObjectFullSize(le_mem_PoolRef_t pool)
le_mem_Destructor_t destructor
The destructor for objects in this pool.
Definition: le_mem.h:531
size_t le_mem_GetBlockSize(void *objPtr)
static le_mem_PoolRef_t le_mem_CreatePool(const char *name, size_t objSize)
Definition: le_mem.h:677
size_t le_mem_GetObjectSize(le_mem_PoolRef_t pool)
le_dls_Link_t poolLink
This pool&#39;s link in the list of memory pools.
Definition: le_mem.h:504
static le_mem_PoolRef_t le_mem_CreateSubPool(le_mem_PoolRef_t superPool, const char *name, size_t numObjects)
Definition: le_mem.h:1405
void le_mem_AddRef(void *objPtr)
void * le_mem_ForceAlloc(le_mem_PoolRef_t pool)
size_t userDataSize
Size of the object requested by the client in bytes.
Definition: le_mem.h:519
void le_mem_Hibernate(void **freeStartPtr, void **freeEndPtr)
size_t numBlocksInUse
Number of currently allocated blocks.
Definition: le_mem.h:523
size_t le_mem_GetRefCount(void *objPtr)
#define LE_DECLARE_INLINE
Definition: le_basics.h:333