Merge lp:~tangent-org/libmemcached/1.0-build/ Build: jenkins-Libmemcached-187
[m6w6/libmemcached] / libmemcachedprotocol / 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