mempool.h

00001 /* mempool.h - a memory pool implementation
00002  *
00003  * cp_mempool is a memory pool for fixed allocation sizes. 
00004  *
00005  * cp_shared_mempool is a collection of cp_mempool objects. cp_shared_mempool
00006  * allows sharing cp_mempool instances that serve the same allocation size. 
00007  * Call cp_shared_mempool_register to request an allocation size and use the 
00008  * returned cp_mempool. 
00009  *
00010  * cp_shared_mempool may also be used for aribitrary sizes allocations, but
00011  * this does not necessarily improve performance. Tests on Open BSD show 
00012  * significant gains, whereas tests on Linux show a performance degradation for
00013  * generic allocation operations. Using cp_shared_mempool to share cp_mempool
00014  * objects between cp_* data structures does not reduce performance. The test
00015  * results are not conclusive and performance characteristics may also be 
00016  * application specific. For best results, benchmark performance for your 
00017  * application in realistic deployment scenarios before deciding whether to use
00018  * cp_shared_mempool.
00019  *
00020  * After instantiating a cp_shared_mempool, you may set one of 
00021  * CP_SHARED_MEMPOOL_TYPE_2 or CP_SHARED_MEMPOOL_TYPE_1. If TYPE_2 is set, 
00022  * requests for unregistered allocation sizes will return the requested size
00023  * rounded up to the machine word size, after instantiating a cp_mempool 
00024  * serving the requested size if none exists. This could potentially use up
00025  * large amounts of memory. If TYPE_1 is set, unregistered allocation sizes
00026  * are rounded up to the next bit. E.g. a request for 513 bytes will return a
00027  * chunk of 1024 bytes. This might also use up large amounts of memory. 
00028  *
00029  * Both cp_mempool and cp_shared_mempool represent a trade off of memory for
00030  * speed and should not be used if memory is tight or if the total allocation
00031  * may exceed the amount of physical memory available to the program, so as to
00032  * prevent swapping. Note that even if using the provided cp_mempool_free or 
00033  * cp_shared_mempool_free functions, the memory returned to the pool is kept 
00034  * for future requests and is ultimately released back to the general "malloc"
00035  * library only when the memory pool is destroyed. 
00036  * 
00037  * AUTHOR: Kyle Wheeler, Ilan Aelion
00038  */
00039 #ifndef _CP_MEMPOOL_H
00040 #define _CP_MEMPOOL_H
00041 
00042 #include "common.h"
00043 #include "collection.h"
00044 
00045 __BEGIN_DECLS
00046 
00047 struct _cp_mempool;
00048 
00049 typedef void (*cp_mempool_callback_fn)(void *prm, 
00050                                        struct _cp_mempool *pool, 
00051                                        void *mem);
00052 
00053 typedef struct _cp_mempool
00054 {
00055     size_t item_size;
00056     size_t alloc_size;
00057     size_t items_per_alloc;
00058 
00059     char *reuse_pool;
00060     char *alloc_pool;
00061     size_t alloc_pool_pos;
00062 
00063     int refcount;
00064 
00065     cp_mempool_callback_fn alloc_callback;
00066     void *callback_prm;
00067 
00068     int mode;
00069     cp_mutex *lock;
00070 #if !defined(CP_HAS_PTHREAD_MUTEX_RECURSIVE) && !defined(CP_HAS_PTHREAD_MUTEX_RECURSIVE_NP)
00071     cp_thread txowner;
00072 #endif /* CP_HAS_PTHREAD_MUTEX_RECURSIVE */
00073 } cp_mempool;
00074 
00075 #define cp_mempool_item_size(p) ((p)->item_size)
00076 
00077 /* cp_mempool_create_by_option */
00078 CPROPS_DLL
00079 cp_mempool *cp_mempool_create_by_option(const int mode, 
00080                                         size_t chunksize, 
00081                                         size_t multiple);
00082 
00083 /* cp_mempool_create_by_option */
00084 CPROPS_DLL
00085 cp_mempool *cp_mempool_create(const size_t chunksize);
00086 
00087 /* increment refcount */
00088 CPROPS_DLL
00089 int cp_mempool_inc_refcount(cp_mempool *pool);
00090 
00091 /* cp_mempool_alloc */
00092 CPROPS_DLL
00093 void *cp_mempool_alloc(cp_mempool * const pool);
00094 
00095 /* cp_mempool_calloc */
00096 CPROPS_DLL
00097 void *cp_mempool_calloc(cp_mempool * const pool);
00098 
00099 /* cp_mempool_free */
00100 CPROPS_DLL
00101 int cp_mempool_free(cp_mempool * const pool, void *data);
00102 
00103 /* cp_mempool_destroy */
00104 CPROPS_DLL
00105 void cp_mempool_destroy(cp_mempool *pool);
00106 
00107 #include "rb.h"
00108 #include "hashtable.h"
00109 
00110 typedef struct _shared_mempool_entry
00111 {
00112     size_t item_size;
00113     cp_mempool *pool;
00114     struct _shared_mempool_entry *next;
00115 } shared_mempool_entry;
00116 
00117 /* cp_shared_mempool is a generalized memory pool. It allows requesting variable
00118  * block sizes. For best results, register the required block sizes in advance.
00119  * requests for unregistered block sizes will return memory from a default
00120  * internal list, which rounds up the block size to the next bit. For example
00121  * allocating an unregisterd block of size 12 will return a 16 byte block. 
00122  * In partcular large allocations could return a lot of extra memory.
00123  */
00124 typedef CPROPS_DLL struct _cp_shared_mempool
00125 {
00126     unsigned int reg_tbl_size;
00127     unsigned int reg_tbl_count;
00128 
00129     shared_mempool_entry **reg_tbl;
00130     struct _cp_rbtree *chunk_tracker;
00131 
00132     int mode;
00133     int gm_mode;
00134 
00135     /* lock for mempool lists */
00136     cp_mutex *lock;
00137 
00138     int multiple; /* number of pages to allocate in sub pools */
00139 } cp_shared_mempool;
00140 
00141 /* ``smaller'': arbitrary size allocations are rounded up to the next bit. The
00142  * pool is ``smaller'' in that up to about WORD_SIZE internal memory pools are
00143  * allocated to serve unregistered allocation size requests.
00144  */
00145 #define CP_SHARED_MEMPOOL_TYPE_1 1
00146 /* ``faster'': arbitrary size allocations are rounded up to the word size. The 
00147  * pool is ``faster'' in that typically the allocation overhead is smaller, and
00148  * the number of operations required to determine which pool to use internally
00149  * is smaller. On the other hand, since a large number of memory pool could be
00150  * allocated internally, this may not be usable in some circumstances. 
00151  */
00152 #define CP_SHARED_MEMPOOL_TYPE_2 2
00153 
00154 /* cp_shared_mempool_create */
00155 CPROPS_DLL
00156 cp_shared_mempool *cp_shared_mempool_create();
00157 
00158 /* cp_shared_mempool_create_by_option */
00159 CPROPS_DLL
00160 cp_shared_mempool *
00161     cp_shared_mempool_create_by_option(int mode, 
00162                                        int arbitrary_allocation_strategy,
00163                                        int size_hint, 
00164                                        int page_count);
00165 
00166 /* cp_shared_mempool destroy */
00167 CPROPS_DLL
00168 void cp_shared_mempool_destroy(cp_shared_mempool *pool);
00169 
00170 /* cp_shared_mempool_register */
00171 CPROPS_DLL
00172 cp_mempool *cp_shared_mempool_register(cp_shared_mempool *pool, size_t size);
00173 
00174 /* cp_shared_mempool_alloc */
00175 CPROPS_DLL
00176 void *cp_shared_mempool_alloc(cp_shared_mempool *pool, size_t size);
00177 
00178 /* cp_shared_mempool_calloc */
00179 CPROPS_DLL
00180 void *cp_shared_mempool_calloc(cp_shared_mempool *pool, size_t size);
00181 
00182 /* cp_shared_mempool_free */
00183 CPROPS_DLL
00184 void cp_shared_mempool_free(cp_shared_mempool *pool, void *p);
00185 
00186 __END_DECLS
00187 
00188 #endif /* _CP_MEMPOOL_H */
00189 

Generated on Mon Dec 5 23:00:22 2011 for cprops by  doxygen 1.4.7