le_mem.h

Go to the documentation of this file.
1 /**
2  * @page c_memory Dynamic Memory Allocation API
3  *
4  *
5  * @ref 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 objects specified 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.
380  * You'll see errors in your logs if you do that.
381  *
382  * Sub-Pools automatically inherit their parent's destructor function.
383  *
384  * @note You can't create sub-pools of sub-pools (i.e., sub-pools that get their blocks from another
385  * sub-pool).
386  *
387  * <HR>
388  *
389  * Copyright (C) Sierra Wireless Inc.
390  */
391 
392 //--------------------------------------------------------------------------------------------------
393 /** @file le_mem.h
394  *
395  * Legato @ref c_memory include file.
396  *
397  * Copyright (C) Sierra Wireless Inc.
398  *
399  */
400 //--------------------------------------------------------------------------------------------------
401 
402 #ifndef LEGATO_MEM_INCLUDE_GUARD
403 #define LEGATO_MEM_INCLUDE_GUARD
404 
405 #ifndef LE_COMPONENT_NAME
406 #define LE_COMPONENT_NAME
407 #endif
408 
409 
410 //--------------------------------------------------------------------------------------------------
411 /**
412  * Objects of this type are used to refer to a memory pool created using either
413  * le_mem_CreatePool() or le_mem_CreateSubPool().
414  */
415 //--------------------------------------------------------------------------------------------------
416 typedef struct le_mem_Pool* le_mem_PoolRef_t;
417 
418 
419 //--------------------------------------------------------------------------------------------------
420 /**
421  * Prototype for destructor functions.
422  *
423  * @param objPtr Pointer to the object where reference count has reached zero. After the destructor
424  * returns this object's memory will be released back into the pool (and this pointer
425  * will become invalid).
426  *
427  * @return Nothing.
428  *
429  * See @ref mem_destructors for more information.
430  */
431 //--------------------------------------------------------------------------------------------------
432 typedef void (*le_mem_Destructor_t)
433 (
434  void* objPtr ///< see parameter documentation in comment above.
435 );
436 
437 
438 //--------------------------------------------------------------------------------------------------
439 /**
440  * List of memory pool statistics.
441  */
442 //--------------------------------------------------------------------------------------------------
443 typedef struct
444 {
445  size_t numBlocksInUse; ///< Number of currently allocated blocks.
446  size_t maxNumBlocksUsed; ///< Maximum number of allocated blocks at any one time.
447  size_t numOverflows; ///< Number of times le_mem_ForceAlloc() had to expand the pool.
448  uint64_t numAllocs; ///< Number of times an object has been allocated from this pool.
449  size_t numFree; ///< Number of free objects currently available in this pool.
450 }
452 
453 
454 #if LE_CONFIG_MEM_TRACE
455  //----------------------------------------------------------------------------------------------
456  /**
457  * Internal function used to retrieve a pool handle for a given pool block.
458  */
459  //----------------------------------------------------------------------------------------------
460  le_mem_PoolRef_t _le_mem_GetBlockPool
461  (
462  void* objPtr ///< [IN] Pointer to the object we're finding a pool for.
463  );
464 
465  typedef void* (*_le_mem_AllocFunc_t)(le_mem_PoolRef_t pool);
466 
467  //----------------------------------------------------------------------------------------------
468  /**
469  * Internal function used to call a memory allocation function and trace its call site.
470  */
471  //----------------------------------------------------------------------------------------------
472  void* _le_mem_AllocTracer
473  (
474  le_mem_PoolRef_t pool, ///< [IN] The pool activity we're tracing.
475  _le_mem_AllocFunc_t funcPtr, ///< [IN] Pointer to the mem function in question.
476  const char* poolFunction, ///< [IN] The pool function being called.
477  const char* file, ///< [IN] The file the call came from.
478  const char* callingfunction, ///< [IN] The function calling into the pool.
479  size_t line ///< [IN] The line in the function where the call
480  /// occurred.
481  );
482 
483  //----------------------------------------------------------------------------------------------
484  /**
485  * Internal function used to trace memory pool activity.
486  */
487  //----------------------------------------------------------------------------------------------
488  void _le_mem_Trace
489  (
490  le_mem_PoolRef_t pool, ///< [IN] The pool activity we're tracing.
491  const char* file, ///< [IN] The file the call came from.
492  const char* callingfunction, ///< [IN] The function calling into the pool.
493  size_t line, ///< [IN] The line in the function where the call
494  /// occurred.
495  const char* poolFunction, ///< [IN] The pool function being called.
496  void* blockPtr ///< [IN] Block allocated/freed.
497  );
498 #endif
499 
500 
501 //--------------------------------------------------------------------------------------------------
502 /** @cond HIDDEN_IN_USER_DOCS
503  *
504  * Internal function used to implement le_mem_CreatePool() with automatic component scoping
505  * of pool names.
506  */
507 //--------------------------------------------------------------------------------------------------
508 le_mem_PoolRef_t _le_mem_CreatePool
509 (
510  const char* componentName, ///< [IN] Name of the component.
511  const char* name, ///< [IN] Name of the pool inside the component.
512  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
513  /// (in bytes), e.g., sizeof(MyObject_t).
514 );
515 /// @endcond
516 
517 
518 //--------------------------------------------------------------------------------------------------
519 /**
520  * Creates an empty memory pool.
521  *
522  * @return
523  * Reference to the memory pool object.
524  *
525  * @note
526  * On failure, the process exits, so you don't have to worry about checking the returned
527  * reference for validity.
528  */
529 //--------------------------------------------------------------------------------------------------
531 (
532  const char* name, ///< [IN] Name of the pool (will be copied into the Pool).
533  size_t objSize ///< [IN] Size of the individual objects to be allocated from this pool
534  /// (in bytes), e.g., sizeof(MyObject_t).
535 )
536 {
537  return _le_mem_CreatePool(STRINGIZE(LE_COMPONENT_NAME), name, objSize);
538 }
539 
540 
541 //--------------------------------------------------------------------------------------------------
542 /**
543  * Expands the size of a memory pool.
544  *
545  * @return Reference to the memory pool object (the same value passed into it).
546  *
547  * @note On failure, the process exits, so you don't have to worry about checking the returned
548  * reference for validity.
549  */
550 //--------------------------------------------------------------------------------------------------
552 (
553  le_mem_PoolRef_t pool, ///< [IN] Pool to be expanded.
554  size_t numObjects ///< [IN] Number of objects to add to the pool.
555 );
556 
557 
558 
559 #if !LE_CONFIG_MEM_TRACE
560  //----------------------------------------------------------------------------------------------
561  /**
562  * Attempts to allocate an object from a pool.
563  *
564  * @return
565  * Pointer to the allocated object, or NULL if the pool doesn't have any free objects
566  * to allocate.
567  */
568  //----------------------------------------------------------------------------------------------
569  void* le_mem_TryAlloc
570  (
571  le_mem_PoolRef_t pool ///< [IN] Pool from which the object is to be allocated.
572  );
573 #else
574  /// @cond HIDDEN_IN_USER_DOCS
575  void* _le_mem_TryAlloc(le_mem_PoolRef_t pool);
576  /// @endcond
577 
578  #define le_mem_TryAlloc(pool) \
579  _le_mem_AllocTracer(pool, \
580  _le_mem_TryAlloc, \
581  "le_mem_TryAlloc", \
582  STRINGIZE(LE_FILENAME), \
583  __FUNCTION__, \
584  __LINE__)
585 
586 #endif
587 
588 
589 #if !LE_CONFIG_MEM_TRACE
590  //----------------------------------------------------------------------------------------------
591  /**
592  * Allocates an object from a pool or logs a fatal error and terminates the process if the pool
593  * doesn't have any free objects to allocate.
594  *
595  * @return Pointer to the allocated object.
596  *
597  * @note On failure, the process exits, so you don't have to worry about checking the
598  * returned pointer for validity.
599  */
600  //----------------------------------------------------------------------------------------------
601  void* le_mem_AssertAlloc
602  (
603  le_mem_PoolRef_t pool ///< [IN] Pool from which the object is to be allocated.
604  );
605 #else
606  /// @cond HIDDEN_IN_USER_DOCS
607  void* _le_mem_AssertAlloc(le_mem_PoolRef_t pool);
608  /// @endcond
609 
610  #define le_mem_AssertAlloc(pool) \
611  _le_mem_AllocTracer(pool, \
612  _le_mem_AssertAlloc, \
613  "le_mem_AssertAlloc", \
614  STRINGIZE(LE_FILENAME), \
615  __FUNCTION__, \
616  __LINE__)
617 #endif
618 
619 
620 #if !LE_CONFIG_MEM_TRACE
621  //----------------------------------------------------------------------------------------------
622  /**
623  * Allocates an object from a pool or logs a warning and expands the pool if the pool
624  * doesn't have any free objects to allocate.
625  *
626  * @return Pointer to the allocated object.
627  *
628  * @note On failure, the process exits, so you don't have to worry about checking the
629  * returned pointer for validity.
630  */
631  //----------------------------------------------------------------------------------------------
632  void* le_mem_ForceAlloc
633  (
634  le_mem_PoolRef_t pool ///< [IN] Pool from which the object is to be allocated.
635  );
636 #else
637  /// @cond HIDDEN_IN_USER_DOCS
638  void* _le_mem_ForceAlloc(le_mem_PoolRef_t pool);
639  /// @endcond
640 
641  #define le_mem_ForceAlloc(pool) \
642  _le_mem_AllocTracer(pool, \
643  _le_mem_ForceAlloc, \
644  "le_mem_ForceAlloc", \
645  STRINGIZE(LE_FILENAME), \
646  __FUNCTION__, \
647  __LINE__)
648 #endif
649 
650 
651 //--------------------------------------------------------------------------------------------------
652 /**
653  * Sets the number of objects that are added when le_mem_ForceAlloc expands the pool.
654  *
655  * @return
656  * Nothing.
657  *
658  * @note
659  * The default value is one.
660  */
661 //--------------------------------------------------------------------------------------------------
663 (
664  le_mem_PoolRef_t pool, ///< [IN] Pool to set the number of objects for.
665  size_t numObjects ///< [IN] Number of objects that is added when
666  /// le_mem_ForceAlloc expands the pool.
667 );
668 
669 
670 #if !LE_CONFIG_MEM_TRACE
671  //----------------------------------------------------------------------------------------------
672  /**
673  * Releases an object. If the object's reference count has reached zero, it will be destructed
674  * and its memory will be put back into the pool for later reuse.
675  *
676  * @return
677  * Nothing.
678  *
679  * @warning
680  * - <b>Don't EVER access an object after releasing it.</b> It might not exist anymore.
681  * - If the object has a destructor accessing a data structure shared by multiple
682  * threads, ensure you hold the mutex (or take other measures to prevent races) before
683  * releasing the object.
684  */
685  //----------------------------------------------------------------------------------------------
686  void le_mem_Release
687  (
688  void* objPtr ///< [IN] Pointer to the object to be released.
689  );
690 #else
691  /// @cond HIDDEN_IN_USER_DOCS
692  void _le_mem_Release(void* objPtr);
693  /// @endcond
694 
695  #define le_mem_Release(objPtr) \
696  _le_mem_Trace(_le_mem_GetBlockPool(objPtr), \
697  STRINGIZE(LE_FILENAME), \
698  __FUNCTION__, \
699  __LINE__, \
700  "le_mem_Release", \
701  (objPtr)); \
702  _le_mem_Release(objPtr);
703 #endif
704 
705 
706 #if !LE_CONFIG_MEM_TRACE
707  //----------------------------------------------------------------------------------------------
708  /**
709  * Increments the reference count on an object by 1.
710  *
711  * See @ref mem_ref_counting for more information.
712  */
713  //----------------------------------------------------------------------------------------------
714  void le_mem_AddRef
715  (
716  void* objPtr ///< [IN] Pointer to the object.
717  );
718 #else
719  /// @cond HIDDEN_IN_USER_DOCS
720  void _le_mem_AddRef(void* objPtr);
721  /// @endcond
722 
723  #define le_mem_AddRef(objPtr) \
724  _le_mem_Trace(_le_mem_GetBlockPool(objPtr), \
725  STRINGIZE(LE_FILENAME), \
726  __FUNCTION__, \
727  __LINE__, \
728  "le_mem_AddRef", \
729  (objPtr)); \
730  _le_mem_AddRef(objPtr);
731 #endif
732 
733 
734 //----------------------------------------------------------------------------------------------
735 /**
736  * Fetches the reference count on an object.
737  *
738  * See @ref mem_ref_counting for more information.
739  *
740  * @warning If using this in a multi-threaded application that shares memory pool objects
741  * between threads, steps must be taken to coordinate the threads (e.g., using a mutex)
742  * to ensure that the reference count value fetched remains correct when it is used.
743  *
744  * @return
745  * The reference count on the object.
746  */
747 //----------------------------------------------------------------------------------------------
748 size_t le_mem_GetRefCount
749 (
750  void* objPtr ///< [IN] Pointer to the object.
751 );
752 
753 
754 //--------------------------------------------------------------------------------------------------
755 /**
756  * Sets the destructor function for a specified pool.
757  *
758  * See @ref mem_destructors for more information.
759  *
760  * @return
761  * Nothing.
762  */
763 //--------------------------------------------------------------------------------------------------
765 (
766  le_mem_PoolRef_t pool, ///< [IN] The pool.
767  le_mem_Destructor_t destructor ///< [IN] Destructor function.
768 );
769 
770 
771 //--------------------------------------------------------------------------------------------------
772 /**
773  * Fetches the statistics for a specified pool.
774  *
775  * @return
776  * Nothing. Uses output parameter instead.
777  */
778 //--------------------------------------------------------------------------------------------------
779 void le_mem_GetStats
780 (
781  le_mem_PoolRef_t pool, ///< [IN] Pool where stats are to be fetched.
782  le_mem_PoolStats_t* statsPtr ///< [OUT] Pointer to where the stats will be stored.
783 );
784 
785 
786 //--------------------------------------------------------------------------------------------------
787 /**
788  * Resets the statistics for a specified pool.
789  *
790  * @return
791  * Nothing.
792  */
793 //--------------------------------------------------------------------------------------------------
795 (
796  le_mem_PoolRef_t pool ///< [IN] Pool where stats are to be reset.
797 );
798 
799 
800 //--------------------------------------------------------------------------------------------------
801 /**
802  * Gets the memory pool's name, including the component name prefix.
803  *
804  * If the pool were given the name "myPool" and the component that it belongs to is called
805  * "myComponent", then the full pool name returned by this function would be "myComponent.myPool".
806  *
807  * @return
808  * LE_OK if successful.
809  * LE_OVERFLOW if the name was truncated to fit in the provided buffer.
810  */
811 //--------------------------------------------------------------------------------------------------
813 (
814  le_mem_PoolRef_t pool, ///< [IN] The memory pool.
815  char* namePtr, ///< [OUT] Buffer to store the name of the memory pool.
816  size_t bufSize ///< [IN] Size of the buffer namePtr points to.
817 );
818 
819 
820 //--------------------------------------------------------------------------------------------------
821 /**
822  * Checks if the specified pool is a sub-pool.
823  *
824  * @return
825  * true if it is a sub-pool.
826  * false if it is not a sub-pool.
827  */
828 //--------------------------------------------------------------------------------------------------
829 const bool le_mem_IsSubPool
830 (
831  le_mem_PoolRef_t pool ///< [IN] The memory pool.
832 );
833 
834 
835 //--------------------------------------------------------------------------------------------------
836 /**
837  * Fetches the number of objects a specified pool can hold (this includes both the number of
838  * free and in-use objects).
839  *
840  * @return
841  * Total number of objects.
842  */
843 //--------------------------------------------------------------------------------------------------
845 (
846  le_mem_PoolRef_t pool ///< [IN] Pool where number of objects is to be fetched.
847 );
848 
849 
850 //--------------------------------------------------------------------------------------------------
851 /**
852  * Fetches the size of the objects in a specified pool (in bytes).
853  *
854  * @return
855  * Object size, in bytes.
856  */
857 //--------------------------------------------------------------------------------------------------
859 (
860  le_mem_PoolRef_t pool ///< [IN] Pool where object size is to be fetched.
861 );
862 
863 
864 //--------------------------------------------------------------------------------------------------
865 /**
866  * Fetches the total size of the object including all the memory overhead in a given pool (in bytes).
867  *
868  * @return
869  * Total object memory size, in bytes.
870  */
871 //--------------------------------------------------------------------------------------------------
873 (
874  le_mem_PoolRef_t pool ///< [IN] The pool whose object memory size is to be fetched.
875 );
876 
877 
878 //--------------------------------------------------------------------------------------------------
879 /** @cond HIDDEN_IN_USER_DOCS
880  *
881  * Internal function used to implement le_mem_FindPool() with automatic component scoping
882  * of pool names.
883  */
884 //--------------------------------------------------------------------------------------------------
885 le_mem_PoolRef_t _le_mem_FindPool
886 (
887  const char* componentName, ///< [IN] Name of the component.
888  const char* name ///< [IN] Name of the pool inside the component.
889 );
890 /// @endcond
891 
892 
893 //--------------------------------------------------------------------------------------------------
894 /**
895  * Finds a pool based on the pool's name.
896  *
897  * @return
898  * Reference to the pool, or NULL if the pool doesn't exist.
899  */
900 //--------------------------------------------------------------------------------------------------
901 static inline le_mem_PoolRef_t le_mem_FindPool
902 (
903  const char* name ///< [IN] Name of the pool.
904 )
905 {
906  return _le_mem_FindPool(STRINGIZE(LE_COMPONENT_NAME), name);
907 }
908 
909 
910 //--------------------------------------------------------------------------------------------------
911 /** @cond HIDDEN_IN_USER_DOCS
912  *
913  * Internal function used to implement le_mem_CreateSubPool() with automatic component scoping
914  * of pool names.
915  */
916 //--------------------------------------------------------------------------------------------------
917 le_mem_PoolRef_t _le_mem_CreateSubPool
918 (
919  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
920  const char* componentName, ///< [IN] Name of the component.
921  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
922  /// sub-pool).
923  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
924 );
925 /// @endcond
926 
927 
928 //--------------------------------------------------------------------------------------------------
929 /**
930  * Creates a sub-pool. You can't create sub-pools of sub-pools so do not attempt to pass a
931  * sub-pool in the superPool parameter.
932  *
933  * See @ref mem_sub_pools for more information.
934  *
935  * @return
936  * Reference to the sub-pool.
937  */
938 //--------------------------------------------------------------------------------------------------
940 (
941  le_mem_PoolRef_t superPool, ///< [IN] Super-pool.
942  const char* name, ///< [IN] Name of the sub-pool (will be copied into the
943  /// sub-pool).
944  size_t numObjects ///< [IN] Number of objects to take from the super-pool.
945 )
946 {
947  return _le_mem_CreateSubPool(superPool, STRINGIZE(LE_COMPONENT_NAME), name, numObjects);
948 }
949 
950 
951 //--------------------------------------------------------------------------------------------------
952 /**
953  * Deletes a sub-pool.
954  *
955  * See @ref mem_sub_pools for more information.
956  *
957  * @return
958  * Nothing.
959  */
960 //--------------------------------------------------------------------------------------------------
962 (
963  le_mem_PoolRef_t subPool ///< [IN] Sub-pool to be deleted.
964 );
965 
966 
967 #endif // LEGATO_MEM_INCLUDE_GUARD
size_t numFree
Number of free objects currently available in this pool.
Definition: le_mem.h:449
void * le_mem_TryAlloc(le_mem_PoolRef_t pool)
le_mem_PoolRef_t le_mem_ExpandPool(le_mem_PoolRef_t pool, size_t numObjects)
le_result_t
Definition: le_basics.h:35
void * le_mem_AssertAlloc(le_mem_PoolRef_t pool)
void le_mem_GetStats(le_mem_PoolRef_t pool, le_mem_PoolStats_t *statsPtr)
const bool le_mem_IsSubPool(le_mem_PoolRef_t pool)
size_t numBlocksInUse
Number of currently allocated blocks.
Definition: le_mem.h:445
static le_mem_PoolRef_t le_mem_FindPool(const char *name)
Definition: le_mem.h:902
#define STRINGIZE(x)
Definition: le_basics.h:206
void le_mem_SetDestructor(le_mem_PoolRef_t pool, le_mem_Destructor_t destructor)
uint64_t numAllocs
Number of times an object has been allocated from this pool.
Definition: le_mem.h:448
size_t maxNumBlocksUsed
Maximum number of allocated blocks at any one time.
Definition: le_mem.h:446
static le_mem_PoolRef_t le_mem_CreatePool(const char *name, size_t objSize)
Definition: le_mem.h:531
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:447
void le_mem_SetNumObjsToForce(le_mem_PoolRef_t pool, size_t numObjects)
void le_mem_DeleteSubPool(le_mem_PoolRef_t subPool)
struct le_mem_Pool * le_mem_PoolRef_t
Definition: le_mem.h:416
le_result_t le_mem_GetName(le_mem_PoolRef_t pool, char *namePtr, size_t bufSize)
void le_mem_Release(void *objPtr)
Definition: le_mem.h:443
void(* le_mem_Destructor_t)(void *objPtr)
Definition: le_mem.h:433
size_t le_mem_GetObjectCount(le_mem_PoolRef_t pool)
size_t le_mem_GetObjectFullSize(le_mem_PoolRef_t pool)
size_t le_mem_GetObjectSize(le_mem_PoolRef_t pool)
void le_mem_AddRef(void *objPtr)
void * le_mem_ForceAlloc(le_mem_PoolRef_t pool)
size_t le_mem_GetRefCount(void *objPtr)
static le_mem_PoolRef_t le_mem_CreateSubPool(le_mem_PoolRef_t superPool, const char *name, size_t numObjects)
Definition: le_mem.h:940