le_mem.h
Go to the documentation of this file.
10 * malloc, free, strdup, calloc, realloc, etc. can result in performance degradation and out-of-memory13 * This is due to fragmentation of the heap. The degraded performance and exhausted memory result from indirect interactions37 * starts-up, and use them until your process terminates. It's up to the OS to clean-up the memory38 * 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.)48 * The following sections describe these, beginning with the most basic usage and working up to more54 * Before allocating memory from a pool, the pool must be created using le_mem_CreatePool(), passing55 * it the name of the pool and the size of the objects to be allocated from that pool. This returns60 * one function with three parameters) to make it virtually impossible to accidentally get the parameters88 * reference that it was given. This allows the xx_pt_ProcessStart() function to be re-implemented102 * For a discussion on how to pick the number of objects to have in your pools, see @ref mem_pool_sizes.108 * - @c le_mem_AssertAlloc() - Log an error and take down the process if there are no free blocks in110 * - @c le_mem_ForceAlloc() - If there are no free blocks in the pool, log a warning and automatically141 * Also, each object knows which pool it came from, so the code that releases the object doesn't have to care.159 * - Whenever someone calls le_mem_AddRef() on an object, its reference count is incremented by 1.161 * - When its reference count reaches zero, it's destroyed (i.e., its memory is released back into the pool.)166 * - increment its reference count and pass a pointer to the object to another function (or thread, data structure, etc.).168 * - release the object without having to worry about when the other function is finished with it.180 * Destructors are a powerful feature of C++. Anyone who has any non-trivial experience with C++ has185 * In Legato, it's possible to call @c le_mem_SetDestructor() to attach a function to a memory pool189 * the destructor returns, the object will be fully destroyed, and its memory will be released back224 * PointDestructor() for each object in the pointList, and the "Destroying point..." message will253 * The memory system also supports two different forms of diagnostics. Both are enabled by defining259 * For instance, the configTree node pool is called, "configTree.nodePool". So to enable a trace of266 * The second diagnostic build flag is @c LE_MEM_VALGRIND. When @c LE_MEM_VALGRIND is enabled, the267 * pools are disabled and instead malloc and free are directly used. Thus enabling the use of tools287 * Although memory pools are @a thread-safe, they are not @a async-safe. This means that memory pools289 * by a normal thread. To be safe, <b> don't call any memory pool functions from within a signal handler. </b>293 * between threads, so it's easy to forget to synchronize calls to @c le_mem_Release() with other code302 * Ideally, the pools should be fully allocated to their maximum sizes at start-up so there aren't308 * Choosing the right size for your pools correctly at start-up is easy to do if there is a maximum311 * carrier that will never carry more than 24 calls at a time, then it's obvious that you need to328 * of client. It can have multiple clients at the same time, but it doesn't know how many clients329 * or what their resource needs will be until the clients register with it at start-up. We'd want330 * those clients to be as decoupled from each other as possible (i.e., we want the clients know as little333 * report their own needs to the service-provider. Also, we don't want each client to have to wait335 * the services offered by the service-provider. That would add more complexity to the interactions349 * a problem because we can't @a shrink pools or delete pools when clients go away. This is where354 * Essentially, a Sub-Pool is a memory pool that gets its blocks from another pool (the super-pool).358 * dynamically pop into existence and later disappear again. When a client attaches to the service364 * so what's the point of having a sub-pool, when all of the resources could just be allocated from375 * To delete a sub-pool, call @c le_mem_DeleteSubPool(). Do not try to use it to delete a pool that376 * was created using le_mem_CreatePool(). It's only for sub-pools created using le_mem_CreateSubPool().382 * @note You can't create sub-pools of sub-pools (i.e., sub-pools that get their blocks from another390 //--------------------------------------------------------------------------------------------------398 //--------------------------------------------------------------------------------------------------408 //--------------------------------------------------------------------------------------------------413 //--------------------------------------------------------------------------------------------------417 //--------------------------------------------------------------------------------------------------421 * @param objPtr Pointer to the object where reference count has reached zero. After the destructor429 //--------------------------------------------------------------------------------------------------431 (436 //--------------------------------------------------------------------------------------------------440 //--------------------------------------------------------------------------------------------------453 //----------------------------------------------------------------------------------------------457 //----------------------------------------------------------------------------------------------465 //----------------------------------------------------------------------------------------------469 //----------------------------------------------------------------------------------------------481 //----------------------------------------------------------------------------------------------485 //----------------------------------------------------------------------------------------------499 //--------------------------------------------------------------------------------------------------505 //--------------------------------------------------------------------------------------------------516 //--------------------------------------------------------------------------------------------------527 //--------------------------------------------------------------------------------------------------529 (539 //--------------------------------------------------------------------------------------------------548 //--------------------------------------------------------------------------------------------------558 //----------------------------------------------------------------------------------------------566 //----------------------------------------------------------------------------------------------588 //----------------------------------------------------------------------------------------------598 //----------------------------------------------------------------------------------------------619 //----------------------------------------------------------------------------------------------629 //----------------------------------------------------------------------------------------------649 //--------------------------------------------------------------------------------------------------659 //--------------------------------------------------------------------------------------------------669 //----------------------------------------------------------------------------------------------683 //----------------------------------------------------------------------------------------------705 //----------------------------------------------------------------------------------------------714 //----------------------------------------------------------------------------------------------735 //--------------------------------------------------------------------------------------------------744 //--------------------------------------------------------------------------------------------------752 //--------------------------------------------------------------------------------------------------759 //--------------------------------------------------------------------------------------------------767 //--------------------------------------------------------------------------------------------------774 //--------------------------------------------------------------------------------------------------781 //--------------------------------------------------------------------------------------------------786 * "myComponent", then the full pool name returned by this function would be "myComponent.myPool".792 //--------------------------------------------------------------------------------------------------801 //--------------------------------------------------------------------------------------------------809 //--------------------------------------------------------------------------------------------------816 //--------------------------------------------------------------------------------------------------824 //--------------------------------------------------------------------------------------------------831 //--------------------------------------------------------------------------------------------------838 //--------------------------------------------------------------------------------------------------845 //--------------------------------------------------------------------------------------------------847 * Fetches the total size of the object including all the memory overhead in a given pool (in bytes).852 //--------------------------------------------------------------------------------------------------859 //--------------------------------------------------------------------------------------------------865 //--------------------------------------------------------------------------------------------------874 //--------------------------------------------------------------------------------------------------881 //--------------------------------------------------------------------------------------------------883 (891 //--------------------------------------------------------------------------------------------------897 //--------------------------------------------------------------------------------------------------909 //--------------------------------------------------------------------------------------------------919 //--------------------------------------------------------------------------------------------------921 (932 //--------------------------------------------------------------------------------------------------941 //--------------------------------------------------------------------------------------------------void * le_mem_TryAlloc(le_mem_PoolRef_t pool)le_mem_PoolRef_t le_mem_ExpandPool(le_mem_PoolRef_t pool, size_t numObjects)uint64_t numAllocsNumber of times an object has been allocated from this pool.Definition: le_mem.h:446void * 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 numBlocksInUseNumber of currently allocated blocks.Definition: le_mem.h:443size_t maxNumBlocksUsedMaximum number of allocated blocks at any one time.Definition: le_mem.h:444void le_mem_SetDestructor(le_mem_PoolRef_t pool, le_mem_Destructor_t destructor)static le_mem_PoolRef_t le_mem_CreatePool(const char *name, size_t objSize)Definition: le_mem.h:529void le_mem_ResetStats(le_mem_PoolRef_t pool)void le_mem_SetNumObjsToForce(le_mem_PoolRef_t pool, size_t numObjects)void le_mem_DeleteSubPool(le_mem_PoolRef_t subPool)le_result_t le_mem_GetName(le_mem_PoolRef_t pool, char *namePtr, size_t bufSize)void le_mem_Release(void *objPtr)size_t numFreeNumber of free objects currently available in this pool.Definition: le_mem.h:447size_t numOverflowsNumber of times le_mem_ForceAlloc() had to expand the pool.Definition: le_mem.h:445size_t le_mem_GetObjectCount(le_mem_PoolRef_t pool)Definition: le_mem.h:441size_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)static le_mem_PoolRef_t le_mem_CreateSubPool(le_mem_PoolRef_t superPool, const char *name, size_t numObjects)Definition: le_mem.h:921