1 /* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 #ifndef CACHE_H 3 #define CACHE_H 4 #include <pthread.h> 5 #include "queue.h" 6 7 #ifndef NDEBUG 8 /* may be used for debug purposes */ 9 extern int cache_error; 10 #endif 11 12 struct cache_free_s { 13 STAILQ_ENTRY(cache_free_s) c_next; 14 }; 15 16 //typedef STAILQ_HEAD(cache_head_s, cache_free_s) cache_head_t; 17 /** 18 * Definition of the structure to keep track of the internal details of 19 * the cache allocator. Touching any of these variables results in 20 * undefined behavior. 21 */ 22 typedef struct { 23 /** Mutex to protect access to the structure */ 24 pthread_mutex_t mutex; 25 /** Name of the cache objects in this cache (provided by the caller) */ 26 char *name; 27 /** freelist of available buffers */ 28 STAILQ_HEAD(cache_head, cache_free_s) head; 29 /** The size of each element in this cache */ 30 size_t bufsize; 31 /** The capacity of the list of elements */ 32 int freetotal; 33 /** Total malloc'ed objects */ 34 int total; 35 /** The current number of free elements */ 36 int freecurr; 37 /** A limit on the total number of elements */ 38 int limit; 39 } cache_t; 40 41 /** 42 * Create an object cache. 43 * 44 * The object cache will let you allocate objects of the same size. It is fully 45 * MT safe, so you may allocate objects from multiple threads without having to 46 * do any synchronization in the application code. 47 * 48 * @param name the name of the object cache. This name may be used for debug purposes 49 * and may help you track down what kind of object you have problems with 50 * (buffer overruns, leakage etc) 51 * @param bufsize the size of each object in the cache 52 * @param align the alignment requirements of the objects in the cache. 53 * @param constructor the function to be called to initialize memory when we need 54 * to allocate more memory from the os. 55 * @param destructor the function to be called before we release the memory back 56 * to the os. 57 * @return a handle to an object cache if successful, NULL otherwise. 58 */ 59 cache_t* cache_create(const char* name, size_t bufsize, size_t align); 60 61 /** 62 * Destroy an object cache. 63 * 64 * Destroy and invalidate an object cache. You should return all buffers allocated 65 * with cache_alloc by using cache_free before calling this function. Not doing 66 * so results in undefined behavior (the buffers may or may not be invalidated) 67 * 68 * @param handle the handle to the object cache to destroy. 69 */ 70 void cache_destroy(cache_t* handle); 71 /** 72 * Allocate an object from the cache. 73 * 74 * @param handle the handle to the object cache to allocate from 75 * @return a pointer to an initialized object from the cache, or NULL if 76 * the allocation cannot be satisfied. 77 */ 78 void* cache_alloc(cache_t* handle); 79 void* do_cache_alloc(cache_t* handle); 80 /** 81 * Return an object back to the cache. 82 * 83 * The caller should return the object in an initialized state so that 84 * the object may be returned in an expected state from cache_alloc. 85 * 86 * @param handle handle to the object cache to return the object to 87 * @param ptr pointer to the object to return. 88 */ 89 void cache_free(cache_t* handle, void* ptr); 90 void do_cache_free(cache_t* handle, void* ptr); 91 /** 92 * Set or adjust a limit for the number of objects to malloc 93 * 94 * @param handle handle to the object cache to adjust 95 * @param limit the number of objects to cache before returning NULL 96 */ 97 void cache_set_limit(cache_t* handle, int limit); 98 99 #endif 100