/* $Id: pool.h 974 2007-02-19 01:13:53Z bennylp $ *//*  * Copyright (C)2003-2007 Benny Prijono <benny@prijono.org> * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA  */#include <pj/list.h>/* See if we use pool's alternate API. * The alternate API is used e.g. to implement pool debugging. */#if PJ_HAS_POOL_ALT_API#  include <pj/pool_alt.h>#endif#ifndef __PJ_POOL_H__#define __PJ_POOL_H__/** * @file pool.h * @brief Memory Pool. */PJ_BEGIN_DECL/** * @defgroup PJ_POOL_GROUP Fast Memory Pool * @ingroup PJ * @brief * Memory pools allow dynamic memory allocation comparable to malloc or the  * new in operator C++. Those implementations are not desirable for very * high performance applications or real-time systems, because of the  * performance bottlenecks and it suffers from fragmentation issue. * * \section PJ_POOL_INTRO_SEC PJLIB's Memory Pool * \subsection PJ_POOL_ADVANTAGE_SUBSEC Advantages *  * PJLIB's pool has many advantages over traditional malloc/new operator and * over other memory pool implementations, because: *  - unlike other memory pool implementation, it allows allocation of *    memory chunks of different sizes, *  - it's very very fast.  *    \n *    Memory chunk allocation is not only an O(1)  *    operation, but it's also very simple (just  *    few pointer arithmetic operations) and it doesn't require locking  *    any mutex, *  - it's memory efficient. *    \n *    Pool doesn't keep track individual memory chunks allocated by *    applications, so there is no additional overhead needed for each *    memory allocation (other than possible additional of few bytes, up to *    PJ_POOL_ALIGNMENT-1, for aligning the memory).  *    But see the @ref PJ_POOL_CAVEATS_SUBSEC below. *  - it prevents memory leaks.  *    \n *    Memory pool inherently has garbage collection functionality. In fact,  *    there is no need to free the chunks allocated from the memory pool. *    All chunks previously allocated from the pool will be freed once the *    pool itself is destroyed. This would prevent memory leaks that haunt *    programmers for decades, and it provides additional performance  *    advantage over traditional malloc/new operator. * * Even more, PJLIB's memory pool provides some additional usability and * flexibility for applications: *  - memory leaks are easily traceable, since memory pool is assigned name, *    and application can inspect what pools currently active in the system. *  - by design, memory allocation from a pool is not thread safe. We assumed *    that a pool will be owned by a higher level object, and thread safety  *    should be handled by that object. This enables very fast pool operations *    and prevents unnecessary locking operations, *  - by default, the memory pool API behaves more like C++ new operator,  *    in that it will throw PJ_NO_MEMORY_EXCEPTION exception (see  *    @ref PJ_EXCEPT) when memory chunk allocation fails. This enables failure *    handling to be done on more high level function (instead of checking *    the result of pj_pool_alloc() everytime). If application doesn't like *    this, the default behavior can be changed on global basis by supplying  *    different policy to the pool factory. *  - any memory allocation backend allocator/deallocator may be used. By *    default, the policy uses malloc() and free() to manage the pool's block, *    but application may use different strategy, for example to allocate *    memory blocks from a globally static memory location. * * * \subsection PJ_POOL_PERFORMANCE_SUBSEC Performance *  * The result of PJLIB's memory design and careful implementation is a * memory allocation strategy that can speed-up the memory allocations * and deallocations by up to <b>30 times</b> compared to standard * malloc()/free() (more than 150 million allocations per second on a * P4/3.0GHz Linux machine). * * (Note: your mileage may vary, of course. You can see how much PJLIB's *  pool improves the performance over malloc()/free() in your target *  system by running pjlib-test application). * * * \subsection PJ_POOL_CAVEATS_SUBSEC Caveats * * There are some caveats though! * * When creating pool, PJLIB requires applications to specify the initial * pool size, and as soon as the pool is created, PJLIB allocates memory * from the system by that size. Application designers MUST choose the  * initial pool size carefully, since choosing too big value will result in * wasting system's memory. * * But the pool can grow. Application designer can specify how the * pool will grow in size, by specifying the size increment when creating * the pool. * * The pool, however, <b>cannot</b> shrink! Since there is <b>no</b>  * function to deallocate memory chunks, there is no way for the pool to  * release back unused memory to the system.  * Application designers must be aware that constant memory allocations  * from pool that has infinite life-time may cause the memory usage of  * the application to grow over time. * * * \section PJ_POOL_USING_SEC Using Memory Pool * * This section describes how to use PJLIB's memory pool framework. * As we hope the readers will witness, PJLIB's memory pool API is quite * straightforward.  * * \subsection PJ_POOL_USING_F Create Pool Factory * First, application needs to initialize a pool factory (this normally * only needs to be done once in one application). PJLIB provides * a pool factory implementation called caching pool (see @ref  * PJ_CACHING_POOL), and it is initialized by calling #pj_caching_pool_init(). * * \subsection PJ_POOL_USING_P Create The Pool * Then application creates the pool object itself with #pj_pool_create(), * specifying among other thing the pool factory where the pool should * be created from, the pool name, initial size, and increment/expansion * size. * * \subsection PJ_POOL_USING_M Allocate Memory as Required * Then whenever application needs to allocate dynamic memory, it would * call #pj_pool_alloc(), #pj_pool_calloc(), or #pj_pool_zalloc() to * allocate memory chunks from the pool. * * \subsection PJ_POOL_USING_DP Destroy the Pool * When application has finished with the pool, it should call  * #pj_pool_release() to release the pool object back to the factory.  * Depending on the types of the factory, this may release the memory back  * to the operating system. * * \subsection PJ_POOL_USING_Dc Destroy the Pool Factory * And finally, before application quites, it should deinitialize the * pool factory, to make sure that all memory blocks allocated by the * factory are released back to the operating system. After this, of  * course no more memory pool allocation can be requested. * * \subsection PJ_POOL_USING_EX Example * Below is a sample complete program that utilizes PJLIB's memory pool. * * \code   #include <pjlib.h>   #define THIS_FILE    "pool_sample.c"   static void my_perror(const char *title, pj_status_t status)   {        char errmsg[PJ_ERR_MSG_SIZE];	pj_strerror(status, errmsg, sizeof(errmsg));	PJ_LOG(1,(THIS_FILE, "%s: %s [status=%d]", title, errmsg, status));   }   static void pool_demo_1(pj_pool_factory *pfactory)   {	unsigned i;	pj_pool_t *pool;	// Must create pool before we can allocate anything	pool = pj_pool_create(pfactory,	 // the factory			      "pool1",	 // pool's name			      4000,	 // initial size			      4000,	 // increment size			      NULL);	 // use default callback.	if (pool == NULL) {	    my_perror("Error creating pool", PJ_ENOMEM);	    return;	}	// Demo: allocate some memory chunks	for (i=0; i<1000; ++i) {	    void *p;	    p = pj_pool_alloc(pool, (pj_rand()+1) % 512);	    // Do something with p	    ...	    // Look! No need to free p!!	}	// Done with silly demo, must free pool to release all memory.	pj_pool_release(pool);   }   int main()   {	pj_caching_pool cp;	pj_status_t status;        // Must init PJLIB before anything else	status = pj_init();	if (status != PJ_SUCCESS) {	    my_perror("Error initializing PJLIB", status);	    return 1;	}	// Create the pool factory, in this case, a caching pool.	pj_caching_pool_init(&cp, &pj_pool_factory_default_policy, 			     1024*1024 );	// Do a demo	pool_demo_1(&cp.factory);	// Done with demos, destroy caching pool before exiting app.	pj_caching_pool_destroy(&cp);	return 0;   }   \endcode * * More information about pool factory, the pool object, and caching pool * can be found on the Module Links below. *//** * @defgroup PJ_POOL Memory Pool Object * @ingroup PJ_POOL_GROUP * @brief * The memory pool is an opaque object created by pool factory. * Application uses this object to request a memory chunk, by calling * #pj_pool_alloc(), #pj_pool_calloc(), or #pj_pool_zalloc().  * When the application has finished using * the pool, it must call #pj_pool_release() to free all the chunks previously * allocated and release the pool back to the factory. * * A memory pool is initialized with an initial amount of memory, which is * called a block. Pool can be configured to dynamically allocate more memory  * blocks when it runs out of memory.  * * The pool doesn't keep track of individual memory allocations * by user, and the user doesn't have to free these indidual allocations. This * makes memory allocation simple and very fast. All the memory allocated from * the pool will be destroyed when the pool itself is destroyed. * * \section PJ_POOL_THREADING_SEC More on Threading Policies * - By design, memory allocation from a pool is not thread safe. We assumed  *   that a pool will be owned by an object, and thread safety should be  *   handled by that object. Thus these functions are not thread safe:  *	- #pj_pool_alloc,  *	- #pj_pool_calloc,  *	- and other pool statistic functions. * - Threading in the pool factory is decided by the policy set for the *   factory when it was created. * * \section PJ_POOL_EXAMPLES_SEC Examples * * For some sample codes on how to use the pool, please see: *  - @ref page_pjlib_pool_test * * @{ *//** * The type for function to receive callback from the pool when it is unable * to allocate memory. The elegant way to handle this condition is to throw * exception, and this is what is expected by most of this library  * components. */typedef void pj_pool_callback(pj_pool_t *pool, pj_size_t size);/** * This class, which is used internally by the pool, describes a single  * block of memory from which user memory allocations will be allocated from. */typedef struct pj_pool_block{    PJ_DECL_LIST_MEMBER(struct pj_pool_block);  /**< List's prev and next.  */    unsigned char    *buf;                      /**< Start of buffer.       */    unsigned char    *cur;                      /**< Current alloc ptr.     */    unsigned char    *end;                      /**< End of buffer.         */} pj_pool_block;/** * This structure describes the memory pool. Only implementors of pool factory * need to care about the contents of this structure. */struct pj_pool_t{    PJ_DECL_LIST_MEMBER(struct pj_pool_t);  /**< Standard list elements.    */    /** Pool name */    char	    obj_name[PJ_MAX_OBJ_NAME];    /** Pool factory. */    pj_pool_factory *factory;    /** Data put by factory */    void	    *factory_data;    /** Current capacity allocated by the pool. */    pj_size_t	    capacity;    /** Size of memory block to be allocated when the pool runs out of memory */    pj_size_t	    increment_size;    /** List of memory blocks allcoated by the pool. */    pj_pool_block   block_list;    /** The callback to be called when the pool is unable to allocate memory. */    pj_pool_callback *callback;};/** * Guidance on how much memory required for initial pool administrative data. */#define PJ_POOL_SIZE	        (sizeof(struct pj_pool_t))/**  * Pool memory alignment (must be power of 2).  */#ifndef PJ_POOL_ALIGNMENT#   define PJ_POOL_ALIGNMENT    4#endif/** * Create a new pool from the pool factory. This wrapper will call create_pool * member of the pool factory. * * @param factory	    The pool factory. * @param name		    The name to be assigned to the pool. The name should  *			    not be longer than PJ_MAX_OBJ_NAME (32 chars), or  *			    otherwise it will be truncated. * @param initial_size	    The size of initial memory blocks taken by the pool. *			    Note that the pool will take 68+20 bytes for  *			    administrative area from this block. * @param increment_size    the size of each additional blocks to be allocated *			    when the pool is running out of memory. If user  *			    requests memory which is larger than this size, then  *			    an error occurs. *			    Note that each time a pool allocates additional block,  *			    it needs PJ_POOL_SIZE more to store some  *			    administrative info. * @param callback	    Callback to be called when error occurs in the pool. *			    If this value is NULL, then the callback from pool *			    factory policy will be used. *			    Note that when an error occurs during pool creation,  *			    the callback itself is not called. Instead, NULL  *			    will be returned. * * @return                  The memory pool, or NULL. */PJ_IDECL(pj_pool_t*) pj_pool_create(pj_pool_factory *factory, 				    const char *name,				    pj_size_t initial_size, 				    pj_size_t increment_size,				    pj_pool_callback *callback);/** * Release the pool back to pool factory. * * @param pool	    Memory pool. */PJ_IDECL(void) pj_pool_release( pj_pool_t *pool );/** * Get pool object name. * * @param pool the pool. * * @return pool name as NULL terminated string. */PJ_IDECL(const char *) pj_pool_getobjname( const pj_pool_t *pool );/** * Reset the pool to its state when it was initialized. * This means that if additional blocks have been allocated during runtime,  * then they will be freed. Only the original block allocated during  * initialization is retained. This function will also reset the internal  * counters, such as pool capacity and used size. * * @param pool the pool. */PJ_DECL(void) pj_pool_reset( pj_pool_t *pool );/** * Get the pool capacity, that is, the system storage that have been allocated * by the pool, and have been used/will be used to allocate user requests. * There's no guarantee that the returned value represent a single * contiguous block, because the capacity may be spread in several blocks. * * @param pool	the pool. * * @return the capacity.