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* |
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 |
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* |
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_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 | */ |
213 | void |
214 | g_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 | */ |
241 | gpointer |
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 (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 | */ |
278 | void |
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 (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 | */ |
319 | void |
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 (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 | */ |
341 | void |
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 (hash_table: cache->key_table, func, user_data); |
350 | } |
351 | |