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
58typedef struct _GCacheNode GCacheNode;
59
60struct _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 */
76struct _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
97static inline GCacheNode*
98g_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
106static inline void
107g_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 */
172GCache*
173g_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_func: hash_key_func, key_equal_func);
197 cache->value_table = g_hash_table_new (hash_func: 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 */
213void
214g_cache_destroy (GCache *cache)
215{
216 g_return_if_fail (cache != NULL);
217
218 g_hash_table_destroy (hash_table: cache->key_table);
219 g_hash_table_destroy (hash_table: 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 */
241gpointer
242g_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 (hash_table: 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 (hash_table: cache->key_table, key, value: node);
262 g_hash_table_insert (hash_table: cache->value_table, key: value, 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 */
278void
279g_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 (hash_table: cache->value_table, key: value);
288 node = g_hash_table_lookup (hash_table: 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 (hash_table: cache->value_table, key: value);
296 g_hash_table_remove (hash_table: 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 */
319void
320g_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 (hash_table: 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 */
341void
342g_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 (hash_table: cache->key_table, func, user_data);
350}
351

source code of gtk/subprojects/glib/glib/deprecated/gcache.c