git.m6w6.name Git - m6w6/libmemcached/blob - libmemcached/protocol/cache.h

   1 /*  vim:expandtab:shiftwidth=2:tabstop=2:smarttab:
   2  *
   3  *  Libmemcached library
   4  *
   5  *  Copyright (C) 2011 Data Differential, http://datadifferential.com/
   6  *
   7  *  Redistribution and use in source and binary forms, with or without
   8  *  modification, are permitted provided that the following conditions are
   9  *  met:
  10  *
  11  *      * Redistributions of source code must retain the above copyright
  12  *  notice, this list of conditions and the following disclaimer.
  13  *
  14  *      * Redistributions in binary form must reproduce the above
  15  *  copyright notice, this list of conditions and the following disclaimer
  16  *  in the documentation and/or other materials provided with the
  17  *  distribution.
  18  *
  19  *      * The names of its contributors may not be used to endorse or
  20  *  promote products derived from this software without specific prior
  21  *  written permission.
  22  *
  23  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  26  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  29  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  30  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  31  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  32  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  33  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  *
  35  */
  36
  37 /* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
  38 #pragma once
  39
  40 #include <pthread.h>
  41
  42 #ifdef HAVE_UMEM_H
  43 # include <umem.h>
  44 # define cache_t umem_cache_t
  45 # define cache_alloc(a) umem_cache_alloc(a, UMEM_DEFAULT)
  46 # define cache_free(a, b) umem_cache_free(a, b)
  47 # define cache_create(a,b,c,d,e) umem_cache_create((char*)a, b, c, d, e, NULL, NULL, NULL, 0)
  48 # define cache_destroy(a) umem_cache_destroy(a);
  49 #else
  50 # ifndef NDEBUG
  51 /* may be used for debug purposes */
  52 extern int cache_error;
  53 # endif
  54
  55 /**
  56  * Constructor used to initialize allocated objects
  57  *
  58  * @param obj pointer to the object to initialized.
  59  * @param notused1 This parameter is currently not used.
  60  * @param notused2 This parameter is currently not used.
  61  * @return you should return 0, but currently this is not checked
  62  */
  63 typedef int cache_constructor_t(void* obj, void* notused1, int notused2);
  64 /**
  65  * Destructor used to clean up allocated objects before they are
  66  * returned to the operating system.
  67  *
  68  * @param obj pointer to the object to initialized.
  69  * @param notused1 This parameter is currently not used.
  70  * @param notused2 This parameter is currently not used.
  71  * @return you should return 0, but currently this is not checked
  72  */
  73 typedef void cache_destructor_t(void* obj, void* notused);
  74
  75 /**
  76  * Definition of the structure to keep track of the internal details of
  77  * the cache allocator. Touching any of these variables results in
  78  * undefined behavior.
  79  */
  80 typedef struct {
  81     /** Mutex to protect access to the structure */
  82     pthread_mutex_t mutex;
  83     /** Name of the cache objects in this cache (provided by the caller) */
  84     char *name;
  85     /** List of pointers to available buffers in this cache */
  86     void **ptr;
  87     /** The size of each element in this cache */
  88     size_t bufsize;
  89     /** The capacity of the list of elements */
  90     size_t freetotal;
  91     /** The current number of free elements */
  92     size_t freecurr;
  93     /** The constructor to be called each time we allocate more memory */
  94     cache_constructor_t* constructor;
  95     /** The destructor to be called each time before we release memory */
  96     cache_destructor_t* destructor;
  97 } cache_t;
  98
  99 /**
 100  * Create an object cache.
 101  *
 102  * The object cache will let you allocate objects of the same size. It is fully
 103  * MT safe, so you may allocate objects from multiple threads without having to
 104  * do any syncrhonization in the application code.
 105  *
 106  * @param name the name of the object cache. This name may be used for debug purposes
 107  *             and may help you track down what kind of object you have problems with
 108  *             (buffer overruns, leakage etc)
 109  * @param bufsize the size of each object in the cache
 110  * @param align the alignment requirements of the objects in the cache.
 111  * @param constructor the function to be called to initialize memory when we need
 112  *                    to allocate more memory from the os.
 113  * @param destructor the function to be called before we release the memory back
 114  *                   to the os.
 115  * @return a handle to an object cache if successful, NULL otherwise.
 116  */
 117 cache_t* cache_create(const char* name, size_t bufsize, size_t align,
 118                       cache_constructor_t* constructor,
 119                       cache_destructor_t* destructor);
 120 /**
 121  * Destroy an object cache.
 122  *
 123  * Destroy and invalidate an object cache. You should return all buffers allocated
 124  * with cache_alloc by using cache_free before calling this function. Not doing
 125  * so results in undefined behavior (the buffers may or may not be invalidated)
 126  *
 127  * @param handle the handle to the object cache to destroy.
 128  */
 129 void cache_destroy(cache_t* handle);
 130 /**
 131  * Allocate an object from the cache.
 132  *
 133  * @param handle the handle to the object cache to allocate from
 134  * @return a pointer to an initialized object from the cache, or NULL if
 135  *         the allocation cannot be satisfied.
 136  */
 137 void* cache_alloc(cache_t* handle);
 138 /**
 139  * Return an object back to the cache.
 140  *
 141  * The caller should return the object in an initialized state so that
 142  * the object may be returned in an expected state from cache_alloc.
 143  *
 144  * @param handle handle to the object cache to return the object to
 145  * @param ptr pointer to the object to return.
 146  */
 147 void cache_free(cache_t* handle, void* ptr);
 148 #endif //  HAVE_UMEM_H