Memory Pools
Memory pools are one of the most misunderstood concepts in APR. Most new developers either use too many or too few pools, because they do not understand exactly what a memory pool represents or why it should be used. At its most basic level a memory pool (as defined by APR) is about scope. Pools are used to define how long memory is available, but they are also used to define when resources are cleaned up.
When a pool is created, it is allocated an 8K block of memory. After that, it is possible to allocate memory out of the pool using apr_palloc. If more memory is requested than is currently available to the pool, another 8K is given to the pool. The memory is never freed for the lifetime of the pool. It continues to grow until the pool is either cleared or destroyed. When the pool is cleared, the memory is marked as available again, and new calls to apr_palloc will reuse the same memory. In this way, memory pools keep applications from calling malloc too often because a steady-state is quickly reached where the maximum amount of required memory is already in a pool and the memory is re-used forever. When the pool is destroyed, the memory is released back to the parent of the current pool.
However, since the memory is never freed, a memory pool could be a recipe for huge memory leaks. Pools remove the danger of memory leaks by making pools hierarchical. When an application is about to perform a short operation that needs memory, a sub-pool is created within the current pool. When the operation is complete, the pool is destroyed, giving the memory back to the current pool for use in either a new sub-pool or in this pool itself. This way, the free function is never called, but you get the same behavior you would get if you had called free. One small trick: it is always possible to create a pool without a parent by passing NULL in as the parent pool. When this pool is destroyed, the memory is actually released using the free function.
Many programmers are afraid to create sub-pools, thinking that creating a sub-pool must be a very expensive operation. In reality, sub-pool creation is very cheap, and pools should be created whenever you have an isolated task to perform.
The other way that pools manage scope is by allowing you to tie resources to pool scope. In APR, this is done through cleanups. The idea is that you can register a cleanup with a pool, so that when the pool is cleared or destroyed, the cleanup is run. If you are doing something like reading a file and you have a pool that is specifically used for reading the file, you know for a fact that you won't need the file to remain open after the pool is destroyed. So, you can register a cleanup with the pool to close the file and then ignore the actual act of closing the file. If used properly, cleanups can make program termination much easier to implement. For example, if your program creates a file to store the process ID on start-up, you will want that file to be deleted when the process dies. To accomplish this, create a pool whose scope is the lifetime of the program. Then, register a cleanup to delete the file when the pool dies. As part of terminating the process, destroy the pool, and the file will be destroyed. This looks like it is just trading one type of cleanup for another (deleting the file instead of destroying the pool). The difference is that you can register any number of cleanups with one pool, so by destroying the pool, you can delete the file and also perform other tasks, such as unallocating any semaphores you have opened.
