glib/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  * GTK+ uses caches for #GtkStyles and #GdkGCs. These consume a lot of
  49  * resources, so a #GCache is used to see if a #GtkStyle or #GdkGC with
  50  * the required properties already exists. If it does, then the
  51  * existing object is used instead of creating a new one.
  52  *
  53  * #GCache uses keys and values. A #GCache key describes the properties
  54  * of a particular resource. A #GCache value is the actual resource.
  55  **/
  56
  57 typedef struct _GCacheNode  GCacheNode;
  58
  59 struct _GCacheNode
  60 {
  61   /* A reference counted node */
  62   gpointer value;
  63   gint ref_count;
  64 };
  65
  66 /**
  67  * GCache:
  68  *
  69  * The #GCache struct is an opaque data structure containing
  70  * information about a #GCache. It should only be accessed via the
  71  * following functions.
  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  * @Returns: a new #GCache.
 129  *
 130  * Creates a new #GCache.
 131  **/
 132 /**
 133  * GCacheNewFunc:
 134  * @key: a #GCache key.
 135  * @Returns: a new #GCache value corresponding to the key.
 136  *
 137  * Specifies the type of the @value_new_func function passed to
 138  * g_cache_new(). It is passed a #GCache key and should create the
 139  * value corresponding to the key.
 140  **/
 141 /**
 142  * GCacheDestroyFunc:
 143  * @value: the #GCache value to destroy.
 144  *
 145  * Specifies the type of the @value_destroy_func and @key_destroy_func
 146  * functions passed to g_cache_new(). The functions are passed a
 147  * pointer to the #GCache key or #GCache value and should free any
 148  * memory and other resources associated with it.
 149  **/
 150 /**
 151  * GCacheDupFunc:
 152  * @value: the #GCache key to destroy (<emphasis>not</emphasis> a
 153  *         #GCache value as it seems).
 154  * @Returns: a copy of the #GCache key.
 155  *
 156  * Specifies the type of the @key_dup_func function passed to
 157  * g_cache_new(). The function is passed a key
 158  * (<emphasis>not</emphasis> a value as the prototype implies) and
 159  * should return a duplicate of the key.
 160  **/
 161 GCache*
 162 g_cache_new (GCacheNewFunc      value_new_func,
 163              GCacheDestroyFunc  value_destroy_func,
 164              GCacheDupFunc      key_dup_func,
 165              GCacheDestroyFunc  key_destroy_func,
 166              GHashFunc          hash_key_func,
 167              GHashFunc          hash_value_func,
 168              GEqualFunc         key_equal_func)
 169 {
 170   GCache *cache;
 171
 172   g_return_val_if_fail (value_new_func != NULL, NULL);
 173   g_return_val_if_fail (value_destroy_func != NULL, NULL);
 174   g_return_val_if_fail (key_dup_func != NULL, NULL);
 175   g_return_val_if_fail (key_destroy_func != NULL, NULL);
 176   g_return_val_if_fail (hash_key_func != NULL, NULL);
 177   g_return_val_if_fail (hash_value_func != NULL, NULL);
 178   g_return_val_if_fail (key_equal_func != NULL, NULL);
 179
 180   cache = g_slice_new (GCache);
 181   cache->value_new_func = value_new_func;
 182   cache->value_destroy_func = value_destroy_func;
 183   cache->key_dup_func = key_dup_func;
 184   cache->key_destroy_func = key_destroy_func;
 185   cache->key_table = g_hash_table_new (hash_key_func, key_equal_func);
 186   cache->value_table = g_hash_table_new (hash_value_func, NULL);
 187
 188   return cache;
 189 }
 190
 191 /**
 192  * g_cache_destroy:
 193  * @cache: a #GCache.
 194  *
 195  * Frees the memory allocated for the #GCache.
 196  *
 197  * Note that it does not destroy the keys and values which were
 198  * contained in the #GCache.
 199  **/
 200 void
 201 g_cache_destroy (GCache *cache)
 202 {
 203   g_return_if_fail (cache != NULL);
 204
 205   g_hash_table_destroy (cache->key_table);
 206   g_hash_table_destroy (cache->value_table);
 207   g_slice_free (GCache, cache);
 208 }
 209
 210 /**
 211  * g_cache_insert:
 212  * @cache: a #GCache.
 213  * @key: a key describing a #GCache object.
 214  * @Returns: a pointer to a #GCache value.
 215  *
 216  * Gets the value corresponding to the given key, creating it if
 217  * necessary. It first checks if the value already exists in the
 218  * #GCache, by using the @key_equal_func function passed to
 219  * g_cache_new(). If it does already exist it is returned, and its
 220  * reference count is increased by one. If the value does not currently
 221  * exist, if is created by calling the @value_new_func. The key is
 222  * duplicated by calling @key_dup_func and the duplicated key and value
 223  * are inserted into the #GCache.
 224  **/
 225 gpointer
 226 g_cache_insert (GCache   *cache,
 227                 gpointer  key)
 228 {
 229   GCacheNode *node;
 230   gpointer value;
 231
 232   g_return_val_if_fail (cache != NULL, NULL);
 233
 234   node = g_hash_table_lookup (cache->key_table, key);
 235   if (node)
 236     {
 237       node->ref_count += 1;
 238       return node->value;
 239     }
 240
 241   key = (* cache->key_dup_func) (key);
 242   value = (* cache->value_new_func) (key);
 243   node = g_cache_node_new (value);
 244
 245   g_hash_table_insert (cache->key_table, key, node);
 246   g_hash_table_insert (cache->value_table, value, key);
 247
 248   return node->value;
 249 }
 250
 251 /**
 252  * g_cache_remove:
 253  * @cache: a #GCache.
 254  * @value: the value to remove.
 255  *
 256  * Decreases the reference count of the given value. If it drops to 0
 257  * then the value and its corresponding key are destroyed, using the
 258  * @value_destroy_func and @key_destroy_func passed to g_cache_new().
 259  **/
 260 void
 261 g_cache_remove (GCache        *cache,
 262                 gconstpointer  value)
 263 {
 264   GCacheNode *node;
 265   gpointer key;
 266
 267   g_return_if_fail (cache != NULL);
 268
 269   key = g_hash_table_lookup (cache->value_table, value);
 270   node = g_hash_table_lookup (cache->key_table, key);
 271
 272   g_return_if_fail (node != NULL);
 273
 274   node->ref_count -= 1;
 275   if (node->ref_count == 0)
 276     {
 277       g_hash_table_remove (cache->value_table, value);
 278       g_hash_table_remove (cache->key_table, key);
 279
 280       (* cache->key_destroy_func) (key);
 281       (* cache->value_destroy_func) (node->value);
 282       g_cache_node_destroy (node);
 283     }
 284 }
 285
 286 /**
 287  * g_cache_key_foreach:
 288  * @cache: a #GCache.
 289  * @func: the function to call with each #GCache key.
 290  * @user_data: user data to pass to the function.
 291  *
 292  * Calls the given function for each of the keys in the #GCache.
 293  *
 294  * NOTE @func is passed three parameters, the value and key of a cache
 295  * entry and the @user_data. The order of value and key is different
 296  * from the order in which g_hash_table_foreach() passes key-value
 297  * pairs to its callback function !
 298  **/
 299 void
 300 g_cache_key_foreach (GCache   *cache,
 301                      GHFunc    func,
 302                      gpointer  user_data)
 303 {
 304   g_return_if_fail (cache != NULL);
 305   g_return_if_fail (func != NULL);
 306
 307   g_hash_table_foreach (cache->value_table, func, user_data);
 308 }
 309
 310 /**
 311  * g_cache_value_foreach:
 312  * @cache: a #GCache.
 313  * @func: the function to call with each #GCache value.
 314  * @user_data: user data to pass to the function.
 315  *
 316  * Calls the given function for each of the values in the #GCache.
 317  *
 318  * Deprecated:2.10: The reason is that it passes pointers to internal
 319  *                  data structures to @func; use g_cache_key_foreach()
 320  *                  instead
 321  **/
 322 void
 323 g_cache_value_foreach (GCache   *cache,
 324                        GHFunc    func,
 325                        gpointer  user_data)
 326 {
 327   g_return_if_fail (cache != NULL);
 328   g_return_if_fail (func != NULL);
 329
 330   g_hash_table_foreach (cache->key_table, func, user_data);
 331 }