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  * To create a sub-pool, call @c le_mem_CreateSubPool(). It takes a reference to the super-pool
375  * and the number of objects to move to the sub-pool, and it returns a reference to the new sub-pool.
376  *
377  * To delete a sub-pool, call @c le_mem_DeleteSubPool(). Do not try to use it to delete a pool that
378  * was created using le_mem_CreatePool(). It's only for sub-pools created using le_mem_CreateSubPool().
379  * Also, it's @b not okay to delete a sub-pool while there are still blocks allocated from it, or
380  * if it has any sub-pools. You'll see errors in your logs if you do that.
381  *
382  * Sub-Pools automatically inherit their parent's destructor function.
383  *
384  * @section mem_reduced_pools Reduced-size pools
385  *
386  * One problem that occurs with memory pools is where objects of different sizes need to be
387  * stored. A classic example is strings -- the longest string an application needs to be able
388  * to handle may be much longer than the typical string size. In this case a lot of memory
389  * will be wasted with standard memory pools, since all objects allocated from the pool will
390  * be the size of the longest possible object.
391  *
392  * The solution is to use reduced-size pools. These are a kind of sub-pool where the size
393  * of the object in the sub-pool is different from the size of the object in the super-pool.
394  * This way multiple blocks from the sub-pool can be stored in a single block of the super-pool.
395  *
396  * Reduced-size pools have some limitations:
397  *
398  * - Each block in the super-pool is divided up to create blocks in the subpool. So subpool
399  * blocks sizes must be less than half the size of the super-pool block size. An attempt to
400  * create a pool with a larger block size will just return a reference to the super-pool.
401  * - Due overhead, each block actually requires 8-80 bytes more space than requested.
402  * There is little point in subdividing pools < 4x overhead, or ~300 bytes in the default
403  * configuration. Note the exact amount of overhead depends on the size of the guard bands
404  * and the size of pointer on your target.
405  * - Blocks used by the reduced pool are permanently moved from the super-pool to the reduced
406  * pool. This must be taken into account when sizing the super-pool.
407  *
408  * Example 1:
409  *
410  * A network service needs to allocate space for packets received over a network. It should
411  * Typical packet length is up to 200 bytes, but occasional packets may be up to 1500 bytes. The
412  * service needs to be able to queue at least 32 packets, up to 5 of which can be 1500 bytes.
413  * Two pools are used: A pool of 12 objects 1500 bytes in size, and a reduced-size pool of 32
414  * objects 200 bytes in size (280 bytes with overhead). Seven objects from the superpool are
415  * used to store reduced-size objects. This represents a memory savings of 60% compared with
416  * a pool of 32 1500 byte objects.
417  *
418  * Example 2:
419  *
420  * An application builds file paths which can be from 16-70 bytes. Only three such paths can be
421  * created at a time, but they can be any size. In this case it is better to just create
422  * a single pool of three 70-byte objects. Most of the potential space gains would be consumed
423  * by overhead. Even if this was not the case, the super pool still needs three free objects
424  * in addition to the objects required by the subpool, so there is no space savings.
425  *
426  * To create a reduced-size pool, use @c le_mem_CreateReducedPool(). It takes a reference to the
427  * super-pool, the initial number of objects in the sub-pool, and size of an object in the sub-pool
428  * compared with the parent pool, and it returns a reference to the new sub-pool.
429  *
430  * Reduced-size pools are deleted using @c le_mem_DeleteSubPool() like other sub-pools.
431  *
432  * To help the programmer pick the right pool to allocate from, reduced-size pools provide
433  * @c le_mem_TryVarAlloc(), @c le_mem_AssertVarAlloc() and @c le_mem_ForceVarAlloc() functions.
434  * In addition to the pool these take the object size to allocate. If this size is larger than
435  * the pool's object size and the pool is a reduced-size pool, and there is a parent pool
436  * large enough for this object, it will allocate the object from the parent pool instead.
437  * If no parent pool is large enough, the program will exit.
438  *
439  * You can call @c le_mem_GetBlockSize() to get the actual size of the object returned by
440  * one of these functions.
441  *
442  * As with other sub-pools, they cannot be deleted while any blocks are allocated from the pool,
443  * or it has any sub-pools. Reduced-size pools also automatically inherit their parent's
444  * destructor function.
445  *
446  * <HR>
447  *
448  * Copyright (C) Sierra Wireless Inc.
449  */
450 
451 //--------------------------------------------------------------------------------------------------
452 /** @file le_mem.h
453  *
454  * Legato @ref c_memory include file.
455  *
456  * Copyright (C) Sierra Wireless Inc.
457  *
458  */
459 //--------------------------------------------------------------------------------------------------
460 
461 #ifndef LEGATO_MEM_INCLUDE_GUARD
462 #define LEGATO_MEM_INCLUDE_GUARD
463 
464 #include "le_singlyLinkedList.h"
465 
466 #ifndef LE_COMPONENT_NAME
467 # define LE_COMPONENT_NAME
468 #endif
469 
470 //--------------------------------------------------------------------------------------------------
471 /**
472  * Prototype for destructor functions.
473  *
474  * @param objPtr Pointer to the object where reference count has reached zero. After the destructor
475  * returns this object's memory will be released back into the pool (and this pointer
476  * will become invalid).
477  *
478  * @return Nothing.
479  *
480  * See @ref mem_destructors for more information.
481  */
482 //--------------------------------------------------------------------------------------------------
483 typedef void (*le_mem_Destructor_t)
484 (
485  void* objPtr ///< see parameter documentation in comment above.
486 );
487 
488 // Max memory pool name bytes -- must match definition in limit.h
489 #define LE_MEM_LIMIT_MAX_MEM_POOL_NAME_BYTES 32
490 
491 //--------------------------------------------------------------------------------------------------
492 /**
493  * Definition of a memory pool.
494  *
495  * @note This should not be used directly. To create a memory pool use either le_mem_CreatePool()
496  * or LE_MEM_DEFINE_STATIC_POOL()/le_mem_InitStaticPool().
497  */
498 //--------------------------------------------------------------------------------------------------
499 typedef struct le_mem_Pool
500 {
501  le_dls_Link_t poolLink; ///< This pool's link in the list of memory pools.
502  struct le_mem_Pool* superPoolPtr; ///< A pointer to our super pool if we are a sub-pool. NULL
503  /// if we are not a sub-pool.
504 #if LE_CONFIG_MEM_POOL_STATS
505  // These members go before LE_CONFIG_MEM_POOLS so numAllocations will always be aligned, even on
506  // 32-bit architectures, even when LE_CONFIG_MEM_POOLS is not declared
507  size_t numOverflows; ///< Number of times le_mem_ForceAlloc() had to expand pool.
508  uint64_t numAllocations; ///< Total number of times an object has been allocated
509  /// from this pool.
510  size_t maxNumBlocksUsed; ///< Maximum number of allocated blocks at any one time.
511 #endif
512 #if LE_CONFIG_MEM_POOLS
513  le_sls_List_t freeList; ///< List of free memory blocks.
514 #endif
515 
516  size_t userDataSize; ///< Size of the object requested by the client in bytes.
517  size_t blockSize; ///< Number of bytes in a block, including all overhead.
518  size_t totalBlocks; ///< Total number of blocks in this pool including free
519  /// and allocated blocks.
520  size_t numBlocksInUse; ///< Number of currently allocated blocks.
521  size_t numBlocksToForce; ///< Number of blocks that is added when Force Alloc
522  /// expands the pool.
523 #if LE_CONFIG_MEM_TRACE
524  le_log_TraceRef_t memTrace; ///< If tracing is enabled, keeps track of a trace object
525  ///< for this pool.
526 #endif
527 
528  le_mem_Destructor_t destructor; ///< The destructor for objects in this pool.
529 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
530  char name[LE_MEM_LIMIT_MAX_MEM_POOL_NAME_BYTES]; ///< Name of the pool.
531 #endif
532 }
534 
535 
536 //--------------------------------------------------------------------------------------------------
537 /**
538  * Objects of this type are used to refer to a memory pool created using either
539  * le_mem_CreatePool() or le_mem_CreateSubPool().
540  */
541 //--------------------------------------------------------------------------------------------------
542 typedef struct le_mem_Pool* le_mem_PoolRef_t;
543 
544 
545 //--------------------------------------------------------------------------------------------------
546 /**
547  * List of memory pool statistics.
548  */
549 //--------------------------------------------------------------------------------------------------
550 typedef struct
551 {
552  size_t numBlocksInUse; ///< Number of currently allocated blocks.
553  size_t maxNumBlocksUsed; ///< Maximum number of allocated blocks at any one time.
554  size_t numOverflows; ///< Number of times le_mem_ForceAlloc() had to expand the pool.
555  uint64_t numAllocs; ///< Number of times an object has been allocated from this pool.
556  size_t numFree; ///< Number of free objects currently available in this pool.
557 }
559 
560 
561 #if LE_CONFIG_MEM_TRACE
562  //----------------------------------------------------------------------------------------------
563  /**
564  * Internal function used to retrieve a pool handle for a given pool block.
565  */
566  //----------------------------------------------------------------------------------------------
567  le_mem_PoolRef_t _le_mem_GetBlockPool
568  (
569  void* objPtr ///< [IN] Pointer to the object we're finding a pool for.
570  );
571 
572  typedef void* (*_le_mem_AllocFunc_t)(le_mem_PoolRef_t pool);
573 
574  //----------------------------------------------------------------------------------------------
575  /**
576  * Internal function used to call a memory allocation function and trace its call site.
577  */
578  //----------------------------------------------------------------------------------------------
579  void* _le_mem_AllocTracer
580  (
581  le_mem_PoolRef_t pool, ///< [IN] The pool activity we're tracing.
582  _le_mem_AllocFunc_t funcPtr, ///< [IN] Pointer to the mem function in question.
583  const char* poolFunction, ///< [IN] The pool function being called.
584  const char* file, ///< [IN] The file the call came from.
585  const char* callingfunction, ///< [IN] The function calling into the pool.
586  size_t line ///< [IN] The line in the function where the call
587  /// occurred.
588  );
589 
590  //----------------------------------------------------------------------------------------------
591  /**
592  * Internal function used to call a variable memory allocation function and trace its call site.
593  */
594  //----------------------------------------------------------------------------------------------
595  void* _le_mem_VarAllocTracer
596  (
597  le_mem_PoolRef_t pool, ///< [IN] The pool activity we're tracing.
598  size_t size, ///< [IN] The size of block to allocate
599  _le_mem_AllocFunc_t funcPtr, ///< [IN] Pointer to the mem function in question.
600  const char* poolFunction, ///< [IN] The pool function being called.
601  const char* file, ///< [IN] The file the call came from.
602  const char* callingfunction, ///< [IN] The function calling into the pool.
603  size_t line ///< [IN] The line in the function where the call
604  /// occurred.
605  );
606 
607  //----------------------------------------------------------------------------------------------
608  /**
609  * Internal function used to trace memory pool activity.
610  */
611  //----------------------------------------------------------------------------------------------
612  void _le_mem_Trace
613  (
614  le_mem_PoolRef_t pool, ///< [IN] The pool activity we're tracing.
615  const char* file, ///< [IN] The file the call came from.
616  const char* callingfunction, ///< [IN] The function calling into the pool.
617  size_t line, ///< [IN] The line in the function where the call
618  /// occurred.
619  const char* poolFunction, ///< [IN] The pool function being called.
620  void* blockPtr ///< [IN] Block allocated/freed.
621  );
622 #endif
623 
624 
625 /// @cond HIDDEN_IN_USER_DOCS
626 //--------------------------------------------------------------------------------------------------
627 /**
628  * Internal function used to implement le_mem_InitStaticPool() with automatic component scoping
629  * of pool names.
630  */
631 //--------------------------------------------------------------------------------------------------
632 le_mem_PoolRef_t _le_mem_InitStaticPool
633 (
634  const char* componentName, ///< [IN] Name of the component.
635  const char* name, ///< [IN] Name of the pool inside the component.
636  size_t numBlocks, ///< [IN] Number of members in the pool by default
637  size_t objSize, ///< [IN] Size of the individual objects to be allocated from this pool
638  /// (in bytes), e.g., sizeof(MyObject_t).
639  le_mem_Pool_t* poolPtr, ///< [IN] Pointer to pre-allocated pool header.
640  void* poolDataPtr ///< [IN] Pointer to pre-allocated pool data.
641 );
642 /// @endcond
643 
644 
645 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
646 //--------------------------------------------------------------------------------------------------
647 /** @cond HIDDEN_IN_USER_DOCS
648  *
649  * Internal function used to implement le_mem_CreatePool() with automatic component scoping
650  * of pool names.
651  */
652 //--------------------------------------------------------------------------------------------------
653 le_mem_PoolRef_t _le_mem_CreatePool
654 (
655  const char* componentName, ///< [IN] Name of the component.
656  const char* name, ///< [IN] Name of the pool inside the component.
657  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
658  /// (in bytes), e.g., sizeof(MyObject_t).
659 );
660 /// @endcond
661 //--------------------------------------------------------------------------------------------------
662 /**
663  * Creates an empty memory pool.
664  *
665  * @return
666  * Reference to the memory pool object.
667  *
668  * @note
669  * On failure, the process exits, so you don't have to worry about checking the returned
670  * reference for validity.
671  */
672 //--------------------------------------------------------------------------------------------------
673 static inline le_mem_PoolRef_t le_mem_CreatePool
674 (
675  const char* name, ///< [IN] Name of the pool inside the component.
676  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
677  /// (in bytes), e.g., sizeof(MyObject_t).
678 )
679 {
680  return _le_mem_CreatePool(STRINGIZE(LE_COMPONENT_NAME), name, objSize);
681 }
682 #else /* if not LE_CONFIG_MEM_POOL_NAMES_ENABLED */
683 //--------------------------------------------------------------------------------------------------
684 /** @cond HIDDEN_IN_USER_DOCS
685  *
686  * Internal function used to implement le_mem_CreatePool() with automatic component scoping
687  * of pool names.
688  */
689 //--------------------------------------------------------------------------------------------------
690 le_mem_PoolRef_t _le_mem_CreatePool
691 (
692  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
693  /// (in bytes), e.g., sizeof(MyObject_t).
694 );
695 /// @endcond
696 //--------------------------------------------------------------------------------------------------
697 /**
698  * Creates an empty memory pool.
699  *
700  * @return
701  * Reference to the memory pool object.
702  *
703  * @note
704  * On failure, the process exits, so you don't have to worry about checking the returned
705  * reference for validity.
706  */
707 //--------------------------------------------------------------------------------------------------
708 LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreatePool
709 (
710  const char* name, ///< [IN] Name of the pool inside the component.
711  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
712  /// (in bytes), e.g., sizeof(MyObject_t).
713 )
714 {
715  return _le_mem_CreatePool(objSize);
716 }
717 #endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */
718 
719 //--------------------------------------------------------------------------------------------------
720 /**
721  * Number of words in a memory pool, given number of blocks and object size.
722  *
723  * @note Only used internally
724  */
725 //--------------------------------------------------------------------------------------------------
726 #define LE_MEM_POOL_WORDS(numBlocks, objSize) \
727  ((numBlocks)*(((sizeof(le_mem_Pool_t*) + sizeof(size_t)) /* sizeof(MemBlock_t) */ + \
728  (((objSize)<sizeof(le_sls_Link_t))?sizeof(le_sls_Link_t):(objSize))+ \
729  sizeof(uint32_t)*LE_CONFIG_NUM_GUARD_BAND_WORDS*2+ \
730  sizeof(size_t) - 1) / sizeof(size_t)))
731 
732 //--------------------------------------------------------------------------------------------------
733 /**
734  * Calculate the number of blocks for a pool.
735  *
736  * @param name Pool name.
737  * @param def Default number of blocks.
738  *
739  * @return Number of blocks, either the value provided by <name>_POOL_SIZE if it is defined, or
740  * <def>. To be valid, <name>_POOL_SIZE must be defined as ,<value> (note the leading
741  * comma).
742  */
743 //--------------------------------------------------------------------------------------------------
744 #define LE_MEM_BLOCKS(name, def) (LE_DEFAULT(CAT(_mem_, CAT(name, _POOL_SIZE)), (def)))
745 
746 //--------------------------------------------------------------------------------------------------
747 /**
748  * Declare variables for a static memory pool.
749  *
750  * In a static memory pool initial pool memory is statically allocated at compile time, ensuring
751  * pool can be created with at least some elements. This is especially valuable on embedded
752  * systems.
753  *
754  * @param name Pool name.
755  * @param numBlocks Default number of blocks. This can be overriden in components using the "pools"
756  * directive.
757  * @param objSize Size of each block in the pool.
758  */
759 /*
760  * Internal Note: size_t is used instead of uint8_t to ensure alignment on platforms where
761  * alignment matters.
762  */
763 //--------------------------------------------------------------------------------------------------
764 #if LE_CONFIG_MEM_POOLS
765 # define LE_MEM_DEFINE_STATIC_POOL(name, numBlocks, objSize) \
766  static le_mem_Pool_t _mem_##name##Pool; \
767  static size_t _mem_##name##Data[LE_MEM_POOL_WORDS(LE_MEM_BLOCKS(name, numBlocks), objSize)]
768 #else
769 # define LE_MEM_DEFINE_STATIC_POOL(name, numBlocks, objSize) \
770  static le_mem_Pool_t _mem_##name##Pool
771 #endif
772 
773 //--------------------------------------------------------------------------------------------------
774 /**
775  * Declare variables for a static memory pool, must specify which object section the variable goes
776  * into
777  *
778  * By default static memory will the assigned to the bss or data section of the final object.
779  * This macro tells the linker to assign to variable to a specific section, sectionName.
780  * Essentially a "__attribute__((section("sectionName")))" will be added after the variable
781  * declaration.
782  *
783  *
784  * @param name Pool name.
785  * @param numBlocks Default number of blocks. This can be overridden in components using the "pools"
786  * directive.
787  * @param objSize Size of each block in the pool.
788  * @param sectionName __attribute__((section("section"))) will be added to the pool declaration so the
789  memory is associated with a the specific section instead of bss, data,..
790  */
791 /*
792  * Internal Note: size_t is used instead of uint8_t to ensure alignment on platforms where
793  * alignment matters.
794  */
795 //--------------------------------------------------------------------------------------------------
796 #if LE_CONFIG_MEM_POOLS
797 # define LE_MEM_DEFINE_STATIC_POOL_IN_SECTION(name, numBlocks, objSize, sectionName) \
798  static le_mem_Pool_t _mem_##name##Pool __attribute__((section(sectionName))); \
799  static size_t _mem_##name##Data[LE_MEM_POOL_WORDS( \
800  LE_MEM_BLOCKS(name, numBlocks), objSize)] __attribute__((section(sectionName)))
801 #else
802 # define LE_MEM_DEFINE_STATIC_POOL_IN_SECTION(name, numBlocks, objSize, sectionName) \
803  static le_mem_Pool_t _mem_##name##Pool __attribute__((section(sectionName)));
804 #endif
805 
806 //--------------------------------------------------------------------------------------------------
807 /**
808  * Initialize an empty static memory pool.
809  *
810  * @param name Pool name.
811  * @param numBlocks Default number of blocks. This can be overriden in components using the "pools"
812  * directive.
813  * @param objSize Size of each block in the pool.
814  *
815  * @return
816  * Reference to the memory pool object.
817  *
818  * @note
819  * This function cannot fail.
820  */
821 //--------------------------------------------------------------------------------------------------
822 #if LE_CONFIG_MEM_POOLS
823 # define le_mem_InitStaticPool(name, numBlocks, objSize) \
824  (inline_static_assert( \
825  sizeof(_mem_##name##Data) == \
826  sizeof(size_t[LE_MEM_POOL_WORDS(LE_MEM_BLOCKS(name, numBlocks), objSize)]), \
827  "initial pool size does not match definition"), \
828  _le_mem_InitStaticPool(STRINGIZE(LE_COMPONENT_NAME), #name, \
829  LE_MEM_BLOCKS(name, numBlocks), (objSize), &_mem_##name##Pool, _mem_##name##Data))
830 #else
831 # define le_mem_InitStaticPool(name, numBlocks, objSize) \
832  _le_mem_InitStaticPool(STRINGIZE(LE_COMPONENT_NAME), #name, \
833  LE_MEM_BLOCKS(name, numBlocks), (objSize), &_mem_##name##Pool, NULL)
834 #endif
835 
836 //--------------------------------------------------------------------------------------------------
837 /**
838  * Expands the size of a memory pool.
839  *
840  * @return Reference to the memory pool object (the same value passed into it).
841  *
842  * @note On failure, the process exits, so you don't have to worry about checking the returned
843  * reference for validity.
844  */
845 //--------------------------------------------------------------------------------------------------
846 le_mem_PoolRef_t le_mem_ExpandPool
847 (
848  le_mem_PoolRef_t pool, ///< [IN] Pool to be expanded.
849  size_t numObjects ///< [IN] Number of objects to add to the pool.
850 );
851 
852 
853 
854 #if !LE_CONFIG_MEM_TRACE
855  //----------------------------------------------------------------------------------------------
856  /**
857  * Attempts to allocate an object from a pool.
858  *
859  * @return
860  * Pointer to the allocated object, or NULL if the pool doesn't have any free objects
861  * to allocate.
862  */
863  //----------------------------------------------------------------------------------------------
864  void* le_mem_TryAlloc
865  (
866  le_mem_PoolRef_t pool ///< [IN] Pool from which the object is to be allocated.
867  );
868 #else
869  /// @cond HIDDEN_IN_USER_DOCS
870  void* _le_mem_TryAlloc(le_mem_PoolRef_t pool);
871  /// @endcond
872 
873 # define le_mem_TryAlloc(pool) \
874  _le_mem_AllocTracer(pool, \
875  _le_mem_TryAlloc, \
876  "le_mem_TryAlloc", \
877  STRINGIZE(LE_FILENAME), \
878  __FUNCTION__, \
879  __LINE__)
880 
881 #endif
882 
883 
884 #if !LE_CONFIG_MEM_TRACE
885  //----------------------------------------------------------------------------------------------
886  /**
887  * Allocates an object from a pool or logs a fatal error and terminates the process if the pool
888  * doesn't have any free objects to allocate.
889  *
890  * @return Pointer to the allocated object.
891  *
892  * @note On failure, the process exits, so you don't have to worry about checking the
893  * returned pointer for validity.
894  */
895  //----------------------------------------------------------------------------------------------
896  void* le_mem_AssertAlloc
897  (
898  le_mem_PoolRef_t pool ///< [IN] Pool from which the object is to be allocated.
899  );
900 #else
901  /// @cond HIDDEN_IN_USER_DOCS
902  void* _le_mem_AssertAlloc(le_mem_PoolRef_t pool);
903  /// @endcond
904 
905 # define le_mem_AssertAlloc(pool) \
906  _le_mem_AllocTracer(pool, \
907  _le_mem_AssertAlloc, \
908  "le_mem_AssertAlloc", \
909  STRINGIZE(LE_FILENAME), \
910  __FUNCTION__, \
911  __LINE__)
912 #endif
913 
914 
915 #if !LE_CONFIG_MEM_TRACE
916  //----------------------------------------------------------------------------------------------
917  /**
918  * Allocates an object from a pool or logs a warning and expands the pool if the pool
919  * doesn't have any free objects to allocate.
920  *
921  * @return Pointer to the allocated object.
922  *
923  * @note On failure, the process exits, so you don't have to worry about checking the
924  * returned pointer for validity.
925  */
926  //----------------------------------------------------------------------------------------------
927  void* le_mem_ForceAlloc
928  (
929  le_mem_PoolRef_t pool ///< [IN] Pool from which the object is to be allocated.
930  );
931 #else
932  /// @cond HIDDEN_IN_USER_DOCS
933  void* _le_mem_ForceAlloc(le_mem_PoolRef_t pool);
934  /// @endcond
935 
936 # define le_mem_ForceAlloc(pool) \
937  _le_mem_AllocTracer(pool, \
938  _le_mem_ForceAlloc, \
939  "le_mem_ForceAlloc", \
940  STRINGIZE(LE_FILENAME), \
941  __FUNCTION__, \
942  __LINE__)
943 #endif
944 
945 
946 #if !LE_CONFIG_MEM_TRACE
947  //----------------------------------------------------------------------------------------------
948  /**
949  * Attempts to allocate an object from a pool.
950  *
951  * @return
952  * Pointer to the allocated object, or NULL if the pool doesn't have any free objects
953  * to allocate.
954  */
955  //----------------------------------------------------------------------------------------------
956  void* le_mem_TryVarAlloc
957  (
958  le_mem_PoolRef_t pool, ///< [IN] Pool from which the object is to be allocated.
959  size_t size ///< [IN] The size of block to allocate
960  );
961 #else
962  /// @cond HIDDEN_IN_USER_DOCS
963  void* _le_mem_TryVarAlloc(le_mem_PoolRef_t pool, size_t size);
964  /// @endcond
965 
966 # define le_mem_TryVarAlloc(pool, size) \
967  _le_mem_VarAllocTracer(pool, \
968  size, \
969  _le_mem_TryVarAlloc, \
970  "le_mem_TryVarAlloc", \
971  STRINGIZE(LE_FILENAME), \
972  __FUNCTION__, \
973  __LINE__)
974 
975 #endif
976 
977 
978 #if !LE_CONFIG_MEM_TRACE
979  //----------------------------------------------------------------------------------------------
980  /**
981  * Allocates an object from a pool or logs a fatal error and terminates the process if the pool
982  * doesn't have any free objects to allocate.
983  *
984  * @return Pointer to the allocated object.
985  *
986  * @note On failure, the process exits, so you don't have to worry about checking the
987  * returned pointer for validity.
988  */
989  //----------------------------------------------------------------------------------------------
991  (
992  le_mem_PoolRef_t pool, ///< [IN] Pool from which the object is to be allocated.
993  size_t size ///< [IN] The size of block to allocate
994  );
995 #else
996  /// @cond HIDDEN_IN_USER_DOCS
997  void* _le_mem_AssertVarAlloc(le_mem_PoolRef_t pool, size_t size);
998  /// @endcond
999 
1000 # define le_mem_AssertVarAlloc(pool, size) \
1001  _le_mem_VarAllocTracer(pool, \
1002  size, \
1003  _le_mem_AssertVarAlloc, \
1004  "le_mem_AssertVarAlloc", \
1005  STRINGIZE(LE_FILENAME), \
1006  __FUNCTION__, \
1007  __LINE__)
1008 #endif
1009 
1010 
1011 #if !LE_CONFIG_MEM_TRACE
1012  //----------------------------------------------------------------------------------------------
1013  /**
1014  * Allocates an object from a pool or logs a warning and expands the pool if the pool
1015  * doesn't have any free objects to allocate.
1016  *
1017  * @return Pointer to the allocated object.
1018  *
1019  * @note On failure, the process exits, so you don't have to worry about checking the
1020  * returned pointer for validity.
1021  */
1022  //----------------------------------------------------------------------------------------------
1023  void* le_mem_ForceVarAlloc
1024  (
1025  le_mem_PoolRef_t pool, ///< [IN] Pool from which the object is to be allocated.
1026  size_t size ///< [IN] The size of block to allocate
1027  );
1028 #else
1029  /// @cond HIDDEN_IN_USER_DOCS
1030  void* _le_mem_ForceVarAlloc(le_mem_PoolRef_t pool, size_t size);
1031  /// @endcond
1032 
1033 # define le_mem_ForceVarAlloc(pool, size) \
1034  _le_mem_VarAllocTracer(pool, \
1035  size, \
1036  _le_mem_ForceVarAlloc, \
1037  "le_mem_ForceVarAlloc", \
1038  STRINGIZE(LE_FILENAME), \
1039  __FUNCTION__, \
1040  __LINE__)
1041 #endif
1042 
1043 //--------------------------------------------------------------------------------------------------
1044 /**
1045  * Attempts to allocate an object from a pool using the configured allocation failure behaviour
1046  * (force or assert). Forced allocation will expand into the heap if the configured pool size is
1047  * exceeded, while assert allocation will abort the program with an error if the pool cannot satisfy
1048  * the request.
1049  *
1050  * @param pool Pool from which the object is to be allocated.
1051  *
1052  * @return Pointer to the allocated object.
1053  */
1054 //--------------------------------------------------------------------------------------------------
1055 #if LE_CONFIG_MEM_ALLOC_FORCE
1056 # define le_mem_Alloc(pool) le_mem_ForceAlloc(pool)
1057 #elif LE_CONFIG_MEM_ALLOC_ASSERT
1058 # define le_mem_Alloc(pool) le_mem_AssertAlloc(pool)
1059 #else
1060 # error "No supported allocation scheme selected!"
1061 #endif
1062 
1063 //--------------------------------------------------------------------------------------------------
1064 /**
1065  * Attempts to allocate a variably-sized object from a pool using the configured allocation failure
1066  * behaviour (force or assert). Forced allocation will expand into the heap if the configured pool
1067  * size is exceeded, while assert allocation will abort the program with an error if the pool cannot
1068  * satisfy the request.
1069  *
1070  * @param pool Pool from which the object is to be allocated.
1071  * @param size The size of block to allocate.
1072  *
1073  * @return Pointer to the allocated object.
1074  */
1075 //--------------------------------------------------------------------------------------------------
1076 #if LE_CONFIG_MEM_ALLOC_FORCE
1077 # define le_mem_VarAlloc(pool, size) le_mem_ForceVarAlloc((pool), (size))
1078 #elif LE_CONFIG_MEM_ALLOC_ASSERT
1079 # define le_mem_VarAlloc(pool, size) le_mem_AssertVarAlloc((pool), (size))
1080 #else
1081 # error "No supported allocation scheme selected!"
1082 #endif
1083 
1084 //--------------------------------------------------------------------------------------------------
1085 /**
1086  * Sets the number of objects that are added when le_mem_ForceAlloc expands the pool.
1087  *
1088  * @return
1089  * Nothing.
1090  *
1091  * @note
1092  * The default value is one.
1093  */
1094 //--------------------------------------------------------------------------------------------------
1096 (
1097  le_mem_PoolRef_t pool, ///< [IN] Pool to set the number of objects for.
1098  size_t numObjects ///< [IN] Number of objects that is added when
1099  /// le_mem_ForceAlloc expands the pool.
1100 );
1101 
1102 
1103 #if !LE_CONFIG_MEM_TRACE
1104  //----------------------------------------------------------------------------------------------
1105  /**
1106  * Releases an object. If the object's reference count has reached zero, it will be destructed
1107  * and its memory will be put back into the pool for later reuse.
1108  *
1109  * @return
1110  * Nothing.
1111  *
1112  * @warning
1113  * - <b>Don't EVER access an object after releasing it.</b> It might not exist anymore.
1114  * - If the object has a destructor accessing a data structure shared by multiple
1115  * threads, ensure you hold the mutex (or take other measures to prevent races) before
1116  * releasing the object.
1117  */
1118  //----------------------------------------------------------------------------------------------
1119  void le_mem_Release
1120  (
1121  void* objPtr ///< [IN] Pointer to the object to be released.
1122  );
1123 #else
1124  /// @cond HIDDEN_IN_USER_DOCS
1125  void _le_mem_Release(void* objPtr);
1126  /// @endcond
1127 
1128 # define le_mem_Release(objPtr) \
1129  _le_mem_Trace(_le_mem_GetBlockPool(objPtr), \
1130  STRINGIZE(LE_FILENAME), \
1131  __FUNCTION__, \
1132  __LINE__, \
1133  "le_mem_Release", \
1134  (objPtr)); \
1135  _le_mem_Release(objPtr);
1136 #endif
1137 
1138 
1139 #if !LE_CONFIG_MEM_TRACE
1140  //----------------------------------------------------------------------------------------------
1141  /**
1142  * Increments the reference count on an object by 1.
1143  *
1144  * See @ref mem_ref_counting for more information.
1145  *
1146  * @return
1147  * Nothing.
1148  */
1149  //----------------------------------------------------------------------------------------------
1150  void le_mem_AddRef
1151  (
1152  void* objPtr ///< [IN] Pointer to the object.
1153  );
1154 #else
1155  /// @cond HIDDEN_IN_USER_DOCS
1156  void _le_mem_AddRef(void* objPtr);
1157  /// @endcond
1158 
1159 # define le_mem_AddRef(objPtr) \
1160  _le_mem_Trace(_le_mem_GetBlockPool(objPtr), \
1161  STRINGIZE(LE_FILENAME), \
1162  __FUNCTION__, \
1163  __LINE__, \
1164  "le_mem_AddRef", \
1165  (objPtr)); \
1166  _le_mem_AddRef(objPtr);
1167 #endif
1168 
1169 //--------------------------------------------------------------------------------------------------
1170 /**
1171  * Fetches the size of a block (in bytes).
1172  *
1173  * @return
1174  * Object size, in bytes.
1175  */
1176 //--------------------------------------------------------------------------------------------------
1177 size_t le_mem_GetBlockSize
1178 (
1179  void* objPtr ///< [IN] Pointer to the object to get size of.
1180 );
1181 
1182 //----------------------------------------------------------------------------------------------
1183 /**
1184  * Fetches the reference count on an object.
1185  *
1186  * See @ref mem_ref_counting for more information.
1187  *
1188  * @warning If using this in a multi-threaded application that shares memory pool objects
1189  * between threads, steps must be taken to coordinate the threads (e.g., using a mutex)
1190  * to ensure that the reference count value fetched remains correct when it is used.
1191  *
1192  * @return
1193  * The reference count on the object.
1194  */
1195 //----------------------------------------------------------------------------------------------
1196 size_t le_mem_GetRefCount
1197 (
1198  void* objPtr ///< [IN] Pointer to the object.
1199 );
1200 
1201 
1202 //--------------------------------------------------------------------------------------------------
1203 /**
1204  * Sets the destructor function for a specified pool.
1205  *
1206  * See @ref mem_destructors for more information.
1207  *
1208  * @return
1209  * Nothing.
1210  */
1211 //--------------------------------------------------------------------------------------------------
1213 (
1214  le_mem_PoolRef_t pool, ///< [IN] The pool.
1215  le_mem_Destructor_t destructor ///< [IN] Destructor function.
1216 );
1217 
1218 
1219 //--------------------------------------------------------------------------------------------------
1220 /**
1221  * Fetches the statistics for a specified pool.
1222  *
1223  * @return
1224  * Nothing. Uses output parameter instead.
1225  */
1226 //--------------------------------------------------------------------------------------------------
1227 void le_mem_GetStats
1228 (
1229  le_mem_PoolRef_t pool, ///< [IN] Pool where stats are to be fetched.
1230  le_mem_PoolStats_t* statsPtr ///< [OUT] Pointer to where the stats will be stored.
1231 );
1232 
1233 
1234 //--------------------------------------------------------------------------------------------------
1235 /**
1236  * Resets the statistics for a specified pool.
1237  *
1238  * @return
1239  * Nothing.
1240  */
1241 //--------------------------------------------------------------------------------------------------
1242 void le_mem_ResetStats
1243 (
1244  le_mem_PoolRef_t pool ///< [IN] Pool where stats are to be reset.
1245 );
1246 
1247 
1248 //--------------------------------------------------------------------------------------------------
1249 /**
1250  * Gets the memory pool's name, including the component name prefix.
1251  *
1252  * If the pool were given the name "myPool" and the component that it belongs to is called
1253  * "myComponent", then the full pool name returned by this function would be "myComponent.myPool".
1254  *
1255  * @return
1256  * LE_OK if successful.
1257  * LE_OVERFLOW if the name was truncated to fit in the provided buffer.
1258  */
1259 //--------------------------------------------------------------------------------------------------
1261 (
1262  le_mem_PoolRef_t pool, ///< [IN] The memory pool.
1263  char* namePtr, ///< [OUT] Buffer to store the name of the memory pool.
1264  size_t bufSize ///< [IN] Size of the buffer namePtr points to.
1265 );
1266 
1267 
1268 //--------------------------------------------------------------------------------------------------
1269 /**
1270  * Checks if the specified pool is a sub-pool.
1271  *
1272  * @return
1273  * true if it is a sub-pool.
1274  * false if it is not a sub-pool.
1275  */
1276 //--------------------------------------------------------------------------------------------------
1277 bool le_mem_IsSubPool
1278 (
1279  le_mem_PoolRef_t pool ///< [IN] The memory pool.
1280 );
1281 
1282 
1283 //--------------------------------------------------------------------------------------------------
1284 /**
1285  * Fetches the number of objects a specified pool can hold (this includes both the number of
1286  * free and in-use objects).
1287  *
1288  * @return
1289  * Total number of objects.
1290  */
1291 //--------------------------------------------------------------------------------------------------
1292 size_t le_mem_GetObjectCount
1293 (
1294  le_mem_PoolRef_t pool ///< [IN] Pool where number of objects is to be fetched.
1295 );
1296 
1297 
1298 //--------------------------------------------------------------------------------------------------
1299 /**
1300  * Fetches the size of the objects in a specified pool (in bytes).
1301  *
1302  * @return
1303  * Object size, in bytes.
1304  */
1305 //--------------------------------------------------------------------------------------------------
1306 size_t le_mem_GetObjectSize
1307 (
1308  le_mem_PoolRef_t pool ///< [IN] Pool where object size is to be fetched.
1309 );
1310 
1311 
1312 //--------------------------------------------------------------------------------------------------
1313 /**
1314  * Fetches the total size of the object including all the memory overhead in a given pool (in bytes).
1315  *
1316  * @return
1317  * Total object memory size, in bytes.
1318  */
1319 //--------------------------------------------------------------------------------------------------
1321 (
1322  le_mem_PoolRef_t pool ///< [IN] The pool whose object memory size is to be fetched.
1323 );
1324 
1325 
1326 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
1327 //--------------------------------------------------------------------------------------------------
1328 /** @cond HIDDEN_IN_USER_DOCS
1329  *
1330  * Internal function used to implement le_mem_FindPool() with automatic component scoping
1331  * of pool names.
1332  */
1333 //--------------------------------------------------------------------------------------------------
1334 le_mem_PoolRef_t _le_mem_FindPool
1335 (
1336  const char* componentName, ///< [IN] Name of the component.
1337  const char* name ///< [IN] Name of the pool inside the component.
1338 );
1339 /// @endcond
1340 //--------------------------------------------------------------------------------------------------
1341 /**
1342  * Finds a pool based on the pool's name.
1343  *
1344  * @return
1345  * Reference to the pool, or NULL if the pool doesn't exist.
1346  */
1347 //--------------------------------------------------------------------------------------------------
1348 static inline le_mem_PoolRef_t le_mem_FindPool
1350  const char* name ///< [IN] Name of the pool inside the component.
1351 )
1352 {
1353  return _le_mem_FindPool(STRINGIZE(LE_COMPONENT_NAME), name);
1354 }
1355 #else
1356 //--------------------------------------------------------------------------------------------------
1357 /**
1358  * Finds a pool based on the pool's name.
1359  *
1360  * @return
1361  * Reference to the pool, or NULL if the pool doesn't exist.
1362  */
1363 //--------------------------------------------------------------------------------------------------
1364 LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_FindPool
1365 (
1366  const char* name ///< [IN] Name of the pool inside the component.
1367 )
1368 {
1369  return NULL;
1370 }
1371 #endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1372 
1373 
1374 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
1375 //--------------------------------------------------------------------------------------------------
1376 /** @cond HIDDEN_IN_USER_DOCS
1377  *
1378  * Internal function used to implement le_mem_CreateSubPool() with automatic component scoping
1379  * of pool names.
1380  */
1381 //--------------------------------------------------------------------------------------------------
1382 le_mem_PoolRef_t _le_mem_CreateSubPool
1383 (
1384  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1385  const char* componentName, ///< [IN] Name of the component.
1386  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1387  /// sub-pool).
1388  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
1389 );
1390 /// @endcond
1391 //--------------------------------------------------------------------------------------------------
1392 /**
1393  * Creates a sub-pool.
1394  *
1395  * See @ref mem_sub_pools for more information.
1396  *
1397  * @return
1398  * Reference to the sub-pool.
1399  */
1400 //--------------------------------------------------------------------------------------------------
1401 static inline le_mem_PoolRef_t le_mem_CreateSubPool
1403  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1404  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1405  /// sub-pool).
1406  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
1407 )
1408 {
1409  return _le_mem_CreateSubPool(superPool, STRINGIZE(LE_COMPONENT_NAME), name, numObjects);
1410 }
1411 #else /* if not LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1412 //--------------------------------------------------------------------------------------------------
1413 /** @cond HIDDEN_IN_USER_DOCS
1414  *
1415  * Internal function used to implement le_mem_CreateSubPool() with automatic component scoping
1416  * of pool names.
1417  */
1418 //--------------------------------------------------------------------------------------------------
1419 le_mem_PoolRef_t _le_mem_CreateSubPool
1420 (
1421  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1422  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
1423 );
1424 /// @endcond
1425 //--------------------------------------------------------------------------------------------------
1426 /**
1427  * Creates a sub-pool.
1428  *
1429  * See @ref mem_sub_pools for more information.
1430  *
1431  * @return
1432  * Reference to the sub-pool.
1433  */
1434 //--------------------------------------------------------------------------------------------------
1435 LE_DECLARE_INLINE le_mem_PoolRef_t le_mem_CreateSubPool
1436 (
1437  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1438  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1439  /// sub-pool).
1440  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
1441 )
1442 {
1443  return _le_mem_CreateSubPool(superPool, numObjects);
1444 }
1445 #endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1446 
1447 
1448 #if LE_CONFIG_MEM_POOL_NAMES_ENABLED
1449 //--------------------------------------------------------------------------------------------------
1450 /** @cond HIDDEN_IN_USER_DOCS
1451  *
1452  * Internal function used to implement le_mem_CreateSubPool() with automatic component scoping
1453  * of pool names.
1454  */
1455 //--------------------------------------------------------------------------------------------------
1456 le_mem_PoolRef_t _le_mem_CreateReducedPool
1457 (
1458  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1459  const char* componentName, ///< [IN] Name of the component.
1460  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1461  /// sub-pool).
1462  size_t numObjects, ///< [IN] Number of objects to take from the super-pool.
1463  size_t objSize ///< [IN] Minimum size of objects in the subpool.
1464 );
1465 /// @endcond
1466 //--------------------------------------------------------------------------------------------------
1467 /**
1468  * Creates a sub-pool of smaller objects.
1469  *
1470  * See @ref mem_reduced_pools for more information.
1471  *
1472  * @return
1473  * Reference to the sub-pool.
1474  */
1475 //--------------------------------------------------------------------------------------------------
1476 static inline le_mem_PoolRef_t le_mem_CreateReducedPool
1478  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1479  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1480  /// sub-pool).
1481  size_t numObjects, ///< [IN] Minimum number of objects in the subpool
1482  ///< by default.
1483  size_t objSize ///< [IN] Minimum size of objects in the subpool.
1484 )
1485 {
1486  return _le_mem_CreateReducedPool(superPool, STRINGIZE(LE_COMPONENT_NAME), name, numObjects, objSize);
1487 }
1488 #else /* if not LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1489 //--------------------------------------------------------------------------------------------------
1490 /** @cond HIDDEN_IN_USER_DOCS
1491  *
1492  * Internal function used to implement le_mem_CreateSubPool() with automatic component scoping
1493  * of pool names.
1494  */
1495 //--------------------------------------------------------------------------------------------------
1496 le_mem_PoolRef_t _le_mem_CreateReducedPool
1497 (
1498  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1499  size_t numObjects, ///< [IN] Minimum number of objects in the subpool
1500  ///< by default.
1501  size_t objSize ///< [IN] Minimum size of objects in the subpool.
1502 );
1503 /// @endcond
1504 //--------------------------------------------------------------------------------------------------
1505 /**
1506  * Creates a sub-pool of smaller objects.
1507  *
1508  * See @ref mem_reduced_pools for more information.
1509  *
1510  * @return
1511  * Reference to the sub-pool.
1512  */
1513 //--------------------------------------------------------------------------------------------------
1515 (
1516  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
1517  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
1518  /// sub-pool).
1519  size_t numObjects, ///< [IN] Minimum number of objects in the subpool
1520  ///< by default.
1521  size_t objSize ///< [IN] Minimum size of objects in the subpool.
1522 )
1523 {
1524  return _le_mem_CreateReducedPool(superPool, numObjects, objSize);
1525 }
1526 #endif /* end LE_CONFIG_MEM_POOL_NAMES_ENABLED */
1527 
1528 
1529 //--------------------------------------------------------------------------------------------------
1530 /**
1531  * Deletes a sub-pool.
1532  *
1533  * See @ref mem_sub_pools for more information.
1534  *
1535  * @return
1536  * Nothing.
1537  */
1538 //--------------------------------------------------------------------------------------------------
1540 (
1541  le_mem_PoolRef_t subPool ///< [IN] Sub-pool to be deleted.
1542 );
1543 
1544 #if LE_CONFIG_RTOS
1545 //--------------------------------------------------------------------------------------------------
1546 /**
1547  * Compress memory pools ready for hibernate-to-RAM
1548  *
1549  * This compresses the memory pools ready for hibernation. All Legato tasks must remain
1550  * suspended until after le_mem_Resume() is called.
1551  *
1552  * @return Nothing
1553  */
1554 //--------------------------------------------------------------------------------------------------
1555 void le_mem_Hibernate
1556 (
1557  void **freeStartPtr, ///< [OUT] Beginning of unused memory which does not need to be
1558  ///< preserved in hibernation
1559  void **freeEndPtr ///< [OUT] End of unused memory
1560 );
1561 
1562 //--------------------------------------------------------------------------------------------------
1563 /**
1564  * Decompress memory pools after waking from hibernate-to-RAM
1565  *
1566  * This decompresses memory pools after hibernation. After this function returns, Legato tasks
1567  * may be resumed.
1568  *
1569  * @return Nothing
1570  */
1571 //--------------------------------------------------------------------------------------------------
1572 void le_mem_Resume
1573 (
1574  void
1575 );
1576 
1577 #endif /* end LE_CONFIG_RTOS */
1578 
1579 //--------------------------------------------------------------------------------------------------
1580 /**
1581  * Duplicate a UTF-8 string. The space for the duplicate string will be allocated from the provided
1582  * memory pool using le_mem_VarAlloc().
1583  *
1584  * @return The allocated duplicate of the string. This may later be released with
1585  * le_mem_Release().
1586  */
1587 //--------------------------------------------------------------------------------------------------
1588 char *le_mem_StrDup
1589 (
1590  le_mem_PoolRef_t poolRef, ///< Pool from which to allocate the string.
1591  const char *srcStr ///< String to duplicate.
1592 );
1593 
1594 #endif // LEGATO_MEM_INCLUDE_GUARD
size_t numBlocksToForce
Definition: le_mem.h:521
size_t numFree
Number of free objects currently available in this pool.
Definition: le_mem.h:556
uint64_t numAllocations
Definition: le_mem.h:508
void * le_mem_TryAlloc(le_mem_PoolRef_t pool)
le_sls_List_t freeList
List of free memory blocks.
Definition: le_mem.h:513
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:45
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:552
size_t totalBlocks
Definition: le_mem.h:518
struct le_mem_Pool * superPoolPtr
Definition: le_mem.h:502
#define STRINGIZE(x)
Definition: le_basics.h:218
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:555
size_t maxNumBlocksUsed
Maximum number of allocated blocks at any one time.
Definition: le_mem.h:510
size_t maxNumBlocksUsed
Maximum number of allocated blocks at any one time.
Definition: le_mem.h:553
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:554
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:1477
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:507
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:542
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:550
static le_mem_PoolRef_t le_mem_FindPool(const char *name)
Definition: le_mem.h:1349
size_t blockSize
Number of bytes in a block, including all overhead.
Definition: le_mem.h:517
void(* le_mem_Destructor_t)(void *objPtr)
Definition: le_mem.h:484
size_t le_mem_GetObjectCount(le_mem_PoolRef_t pool)
Definition: le_mem.h:499
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:528
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:674
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:501
static le_mem_PoolRef_t le_mem_CreateSubPool(le_mem_PoolRef_t superPool, const char *name, size_t numObjects)
Definition: le_mem.h:1402
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:516
void le_mem_Hibernate(void **freeStartPtr, void **freeEndPtr)
size_t numBlocksInUse
Number of currently allocated blocks.
Definition: le_mem.h:520
size_t le_mem_GetRefCount(void *objPtr)
#define LE_DECLARE_INLINE
Definition: le_basics.h:317