glib/deprecated/gcache.c

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