1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 */
17
18 /*
19 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
20 * file for a list of people on the GLib Team. See the ChangeLog
21 * files for a list of changes. These files are distributed with
22 * GLib at ftp://ftp.gtk.org/pub/gtk/.
23 */
24
25 /*
26 * MT safe
27 */
28
29 #include "config.h"
30
31 /* we know we are deprecated here, no need for warnings */
32 #ifndef GLIB_DISABLE_DEPRECATION_WARNINGS
33 #define GLIB_DISABLE_DEPRECATION_WARNINGS
34 #endif
35
36 #include "gcache.h"
37
38 #include "gslice.h"
39 #include "ghash.h"
40 #include "gtestutils.h"
41
42 /**
43 * SECTION:caches
44 * @title: Caches
45 * @short_description: caches allow sharing of complex data structures
46 * to save resources
47 *
48 * A #GCache allows sharing of complex data structures, in order to
49 * save system resources.
50 *
51 * GCache uses keys and values. A GCache key describes the properties
52 * of a particular resource. A GCache value is the actual resource.
53 *
54 * GCache has been marked as deprecated, since this API is rarely
55 * used and not very actively maintained.
56 */
57
58 typedef struct _GCacheNode GCacheNode;
59
60 struct _GCacheNode
61 {
62 /* A reference counted node */
63 gpointer value;
64 gint ref_count;
65 };
66
67 /**
68 * GCache:
69 *
70 * The #GCache struct is an opaque data structure containing
71 * information about a #GCache. It should only be accessed via the
72 * following functions.
73 *
74 * Deprecated:2.32: Use a #GHashTable instead
75 */
76 struct _GCache
77 {
78 /* Called to create a value from a key */
79 GCacheNewFunc value_new_func;
80
81 /* Called to destroy a value */
82 GCacheDestroyFunc value_destroy_func;
83
84 /* Called to duplicate a key */
85 GCacheDupFunc key_dup_func;
86
87 /* Called to destroy a key */
88 GCacheDestroyFunc key_destroy_func;
89
90 /* Associates keys with nodes */
91 GHashTable *key_table;
92
93 /* Associates nodes with keys */
94 GHashTable *value_table;
95 };
96
97 static inline GCacheNode*
g_cache_node_new(gpointer value)98 g_cache_node_new (gpointer value)
99 {
100 GCacheNode *node = g_slice_new (GCacheNode);
101 node->value = value;
102 node->ref_count = 1;
103 return node;
104 }
105
106 static inline void
g_cache_node_destroy(GCacheNode * node)107 g_cache_node_destroy (GCacheNode *node)
108 {
109 g_slice_free (GCacheNode, node);
110 }
111
112 /**
113 * g_cache_new:
114 * @value_new_func: a function to create a new object given a key.
115 * This is called by g_cache_insert() if an object
116 * with the given key does not already exist
117 * @value_destroy_func: a function to destroy an object. It is called
118 * by g_cache_remove() when the object is no
119 * longer needed (i.e. its reference count drops
120 * to 0)
121 * @key_dup_func: a function to copy a key. It is called by
122 * g_cache_insert() if the key does not already exist in
123 * the #GCache
124 * @key_destroy_func: a function to destroy a key. It is called by
125 * g_cache_remove() when the object is no longer
126 * needed (i.e. its reference count drops to 0)
127 * @hash_key_func: a function to create a hash value from a key
128 * @hash_value_func: a function to create a hash value from a value
129 * @key_equal_func: a function to compare two keys. It should return
130 * %TRUE if the two keys are equivalent
131 *
132 * Creates a new #GCache.
133 *
134 * Returns: a new #GCache
135 *
136 * Deprecated:2.32: Use a #GHashTable instead
137 */
138
139 /**
140 * GCacheNewFunc:
141 * @key: a #GCache key
142 *
143 * Specifies the type of the @value_new_func function passed to
144 * g_cache_new(). It is passed a #GCache key and should create the
145 * value corresponding to the key.
146 *
147 * Returns: a new #GCache value corresponding to the key.
148 */
149
150 /**
151 * GCacheDestroyFunc:
152 * @value: the #GCache value to destroy
153 *
154 * Specifies the type of the @value_destroy_func and @key_destroy_func
155 * functions passed to g_cache_new(). The functions are passed a
156 * pointer to the #GCache key or #GCache value and should free any
157 * memory and other resources associated with it.
158 */
159
160 /**
161 * GCacheDupFunc:
162 * @value: the #GCache key to destroy (__not__ a
163 * #GCache value as it seems)
164 *
165 * Specifies the type of the @key_dup_func function passed to
166 * g_cache_new(). The function is passed a key
167 * (__not__ a value as the prototype implies) and
168 * should return a duplicate of the key.
169 *
170 * Returns: a copy of the #GCache key
171 */
172 GCache*
g_cache_new(GCacheNewFunc value_new_func,GCacheDestroyFunc value_destroy_func,GCacheDupFunc key_dup_func,GCacheDestroyFunc key_destroy_func,GHashFunc hash_key_func,GHashFunc hash_value_func,GEqualFunc key_equal_func)173 g_cache_new (GCacheNewFunc value_new_func,
174 GCacheDestroyFunc value_destroy_func,
175 GCacheDupFunc key_dup_func,
176 GCacheDestroyFunc key_destroy_func,
177 GHashFunc hash_key_func,
178 GHashFunc hash_value_func,
179 GEqualFunc key_equal_func)
180 {
181 GCache *cache;
182
183 g_return_val_if_fail (value_new_func != NULL, NULL);
184 g_return_val_if_fail (value_destroy_func != NULL, NULL);
185 g_return_val_if_fail (key_dup_func != NULL, NULL);
186 g_return_val_if_fail (key_destroy_func != NULL, NULL);
187 g_return_val_if_fail (hash_key_func != NULL, NULL);
188 g_return_val_if_fail (hash_value_func != NULL, NULL);
189 g_return_val_if_fail (key_equal_func != NULL, NULL);
190
191 cache = g_slice_new (GCache);
192 cache->value_new_func = value_new_func;
193 cache->value_destroy_func = value_destroy_func;
194 cache->key_dup_func = key_dup_func;
195 cache->key_destroy_func = key_destroy_func;
196 cache->key_table = g_hash_table_new (hash_key_func, key_equal_func);
197 cache->value_table = g_hash_table_new (hash_value_func, NULL);
198
199 return cache;
200 }
201
202 /**
203 * g_cache_destroy:
204 * @cache: a #GCache
205 *
206 * Frees the memory allocated for the #GCache.
207 *
208 * Note that it does not destroy the keys and values which were
209 * contained in the #GCache.
210 *
211 * Deprecated:2.32: Use a #GHashTable instead
212 */
213 void
g_cache_destroy(GCache * cache)214 g_cache_destroy (GCache *cache)
215 {
216 g_return_if_fail (cache != NULL);
217
218 g_hash_table_destroy (cache->key_table);
219 g_hash_table_destroy (cache->value_table);
220 g_slice_free (GCache, cache);
221 }
222
223 /**
224 * g_cache_insert:
225 * @cache: a #GCache
226 * @key: a key describing a #GCache object
227 *
228 * Gets the value corresponding to the given key, creating it if
229 * necessary. It first checks if the value already exists in the
230 * #GCache, by using the @key_equal_func function passed to
231 * g_cache_new(). If it does already exist it is returned, and its
232 * reference count is increased by one. If the value does not currently
233 * exist, if is created by calling the @value_new_func. The key is
234 * duplicated by calling @key_dup_func and the duplicated key and value
235 * are inserted into the #GCache.
236 *
237 * Returns: a pointer to a #GCache value
238 *
239 * Deprecated:2.32: Use a #GHashTable instead
240 */
241 gpointer
g_cache_insert(GCache * cache,gpointer key)242 g_cache_insert (GCache *cache,
243 gpointer key)
244 {
245 GCacheNode *node;
246 gpointer value;
247
248 g_return_val_if_fail (cache != NULL, NULL);
249
250 node = g_hash_table_lookup (cache->key_table, key);
251 if (node)
252 {
253 node->ref_count += 1;
254 return node->value;
255 }
256
257 key = (* cache->key_dup_func) (key);
258 value = (* cache->value_new_func) (key);
259 node = g_cache_node_new (value);
260
261 g_hash_table_insert (cache->key_table, key, node);
262 g_hash_table_insert (cache->value_table, value, key);
263
264 return node->value;
265 }
266
267 /**
268 * g_cache_remove:
269 * @cache: a #GCache
270 * @value: the value to remove
271 *
272 * Decreases the reference count of the given value. If it drops to 0
273 * then the value and its corresponding key are destroyed, using the
274 * @value_destroy_func and @key_destroy_func passed to g_cache_new().
275 *
276 * Deprecated:2.32: Use a #GHashTable instead
277 */
278 void
g_cache_remove(GCache * cache,gconstpointer value)279 g_cache_remove (GCache *cache,
280 gconstpointer value)
281 {
282 GCacheNode *node;
283 gpointer key;
284
285 g_return_if_fail (cache != NULL);
286
287 key = g_hash_table_lookup (cache->value_table, value);
288 node = g_hash_table_lookup (cache->key_table, key);
289
290 g_return_if_fail (node != NULL);
291
292 node->ref_count -= 1;
293 if (node->ref_count == 0)
294 {
295 g_hash_table_remove (cache->value_table, value);
296 g_hash_table_remove (cache->key_table, key);
297
298 (* cache->key_destroy_func) (key);
299 (* cache->value_destroy_func) (node->value);
300 g_cache_node_destroy (node);
301 }
302 }
303
304 /**
305 * g_cache_key_foreach:
306 * @cache: a #GCache
307 * @func: the function to call with each #GCache key
308 * @user_data: user data to pass to the function
309 *
310 * Calls the given function for each of the keys in the #GCache.
311 *
312 * NOTE @func is passed three parameters, the value and key of a cache
313 * entry and the @user_data. The order of value and key is different
314 * from the order in which g_hash_table_foreach() passes key-value
315 * pairs to its callback function !
316 *
317 * Deprecated:2.32: Use a #GHashTable instead
318 */
319 void
g_cache_key_foreach(GCache * cache,GHFunc func,gpointer user_data)320 g_cache_key_foreach (GCache *cache,
321 GHFunc func,
322 gpointer user_data)
323 {
324 g_return_if_fail (cache != NULL);
325 g_return_if_fail (func != NULL);
326
327 g_hash_table_foreach (cache->value_table, func, user_data);
328 }
329
330 /**
331 * g_cache_value_foreach:
332 * @cache: a #GCache
333 * @func: the function to call with each #GCache value
334 * @user_data: user data to pass to the function
335 *
336 * Calls the given function for each of the values in the #GCache.
337 *
338 * Deprecated:2.10: The reason is that it passes pointers to internal
339 * data structures to @func; use g_cache_key_foreach() instead
340 */
341 void
g_cache_value_foreach(GCache * cache,GHFunc func,gpointer user_data)342 g_cache_value_foreach (GCache *cache,
343 GHFunc func,
344 gpointer user_data)
345 {
346 g_return_if_fail (cache != NULL);
347 g_return_if_fail (func != NULL);
348
349 g_hash_table_foreach (cache->key_table, func, user_data);
350 }
351