git.m6w6.name Git - awesomized/libmemcached/blob - memcached/cache.h

   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
   6 #ifdef HAVE_UMEM_H
   7 #include <umem.h>
   8 #define cache_t umem_cache_t
   9 #define cache_alloc(a) umem_cache_alloc(a, UMEM_DEFAULT)
  10 #define cache_free(a, b) umem_cache_free(a, b)
  11 #define cache_create(a,b,c,d,e) umem_cache_create((char*)a, b, c, d, e, NULL, NULL, NULL, 0)
  12 #define cache_destroy(a) umem_cache_destroy(a);
  13
  14 #else
  15
  16 #ifndef NDEBUG
  17 /* may be used for debug purposes */
  18 extern int cache_error;
  19 #endif
  20
  21 /**
  22  * Constructor used to initialize allocated objects
  23  *
  24  * @param obj pointer to the object to initialized.
  25  * @param notused1 This parameter is currently not used.
  26  * @param notused2 This parameter is currently not used.
  27  * @return you should return 0, but currently this is not checked
  28  */
  29 typedef int cache_constructor_t(void* obj, void* notused1, int notused2);
  30 /**
  31  * Destructor used to clean up allocated objects before they are
  32  * returned to the operating system.
  33  *
  34  * @param obj pointer to the object to initialized.
  35  * @param notused1 This parameter is currently not used.
  36  * @param notused2 This parameter is currently not used.
  37  * @return you should return 0, but currently this is not checked
  38  */
  39 typedef void cache_destructor_t(void* obj, void* notused);
  40
  41 /**
  42  * Definition of the structure to keep track of the internal details of
  43  * the cache allocator. Touching any of these variables results in
  44  * undefined behavior.
  45  */
  46 typedef struct {
  47     /** Mutex to protect access to the structure */
  48     pthread_mutex_t mutex;
  49     /** Name of the cache objects in this cache (provided by the caller) */
  50     char *name;
  51     /** List of pointers to available buffers in this cache */
  52     void **ptr;
  53     /** The size of each element in this cache */
  54     size_t bufsize;
  55     /** The capacity of the list of elements */
  56     int freetotal;
  57     /** The current number of free elements */
  58     int freecurr;
  59     /** The constructor to be called each time we allocate more memory */
  60     cache_constructor_t* constructor;
  61     /** The destructor to be called each time before we release memory */
  62     cache_destructor_t* destructor;
  63 } cache_t;
  64
  65 /**
  66  * Create an object cache.
  67  *
  68  * The object cache will let you allocate objects of the same size. It is fully
  69  * MT safe, so you may allocate objects from multiple threads without having to
  70  * do any syncrhonization in the application code.
  71  *
  72  * @param name the name of the object cache. This name may be used for debug purposes
  73  *             and may help you track down what kind of object you have problems with
  74  *             (buffer overruns, leakage etc)
  75  * @param bufsize the size of each object in the cache
  76  * @param align the alignment requirements of the objects in the cache.
  77  * @param constructor the function to be called to initialize memory when we need
  78  *                    to allocate more memory from the os.
  79  * @param destructor the function to be called before we release the memory back
  80  *                   to the os.
  81  * @return a handle to an object cache if successful, NULL otherwise.
  82  */
  83 cache_t* cache_create(const char* name, size_t bufsize, size_t align,
  84                       cache_constructor_t* constructor,
  85                       cache_destructor_t* destructor);
  86 /**
  87  * Destroy an object cache.
  88  *
  89  * Destroy and invalidate an object cache. You should return all buffers allocated
  90  * with cache_alloc by using cache_free before calling this function. Not doing
  91  * so results in undefined behavior (the buffers may or may not be invalidated)
  92  *
  93  * @param handle the handle to the object cache to destroy.
  94  */
  95 void cache_destroy(cache_t* handle);
  96 /**
  97  * Allocate an object from the cache.
  98  *
  99  * @param handle the handle to the object cache to allocate from
 100  * @return a pointer to an initialized object from the cache, or NULL if
 101  *         the allocation cannot be satisfied.
 102  */
 103 void* cache_alloc(cache_t* handle);
 104 /**
 105  * Return an object back to the cache.
 106  *
 107  * The caller should return the object in an initialized state so that
 108  * the object may be returned in an expected state from cache_alloc.
 109  *
 110  * @param handle handle to the object cache to return the object to
 111  * @param ptr pointer to the object to return.
 112  */
 113 void cache_free(cache_t* handle, void* ptr);
 114 #endif
 115
 116 #endif