docs/reference/glib/tmpl/caches.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Caches
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 caches allow sharing of complex data structures to save resources.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GCache allows sharing of complex data structures, in order to save
  10 system resources.
  11 </para>
  12 <para>
  13 GTK+ uses caches for #GtkStyles and #GdkGCs. These consume a lot of
  14 resources, so a #GCache is used to see if a #GtkStyle or #GdkGC with the
  15 required properties already exists. If it does, then the existing
  16 object is used instead of creating a new one.
  17 </para>
  18 <para>
  19 #GCache uses keys and values.
  20 A #GCache key describes the properties of a particular resource.
  21 A #GCache value is the actual resource.
  22 </para>
  23
  24 <!-- ##### SECTION See_Also ##### -->
  25 <para>
  26
  27 </para>
  28
  29 <!-- ##### SECTION Stability_Level ##### -->
  30
  31
  32 <!-- ##### STRUCT GCache ##### -->
  33 <para>
  34 The #GCache struct is an opaque data structure containing information about
  35 a #GCache. It should only be accessed via the following functions.
  36 </para>
  37
  38
  39 <!-- ##### FUNCTION g_cache_new ##### -->
  40 <para>
  41 Creates a new #GCache.
  42 </para>
  43
  44 @value_new_func: a function to create a new object given a key.
  45 This is called by g_cache_insert() if an object with the given key
  46 does not already exist.
  47 @value_destroy_func: a function to destroy an object. It is
  48 called by g_cache_remove() when the object is no longer needed (i.e. its
  49 reference count drops to 0).
  50 @key_dup_func: a function to copy a key. It is called by
  51 g_cache_insert() if the key does not already exist in the #GCache.
  52 @key_destroy_func: a function to destroy a key. It is
  53 called by g_cache_remove() when the object is no longer needed (i.e. its
  54 reference count drops to 0).
  55 @hash_key_func: a function to create a hash value from a key.
  56 @hash_value_func: a function to create a hash value from a value.
  57 @key_equal_func: a function to compare two keys. It should return %TRUE if
  58 the two keys are equivalent.
  59 @Returns: a new #GCache.
  60
  61
  62 <!-- ##### FUNCTION g_cache_insert ##### -->
  63 <para>
  64 Gets the value corresponding to the given key, creating it if necessary.
  65 It first checks if the value already exists in the #GCache, by using
  66 the @key_equal_func function passed to g_cache_new().
  67 If it does already exist it is returned, and its reference count is increased
  68 by one.
  69 If the value does not currently exist, if is created by calling the
  70 @value_new_func. The key is duplicated by calling
  71 @key_dup_func and the duplicated key and value are inserted
  72 into the #GCache.
  73 </para>
  74
  75 @cache: a #GCache.
  76 @key: a key describing a #GCache object.
  77 @Returns: a pointer to a #GCache value.
  78
  79
  80 <!-- ##### FUNCTION g_cache_remove ##### -->
  81 <para>
  82 Decreases the reference count of the given value.
  83 If it drops to 0 then the value and its corresponding key are destroyed,
  84 using the @value_destroy_func and @key_destroy_func passed to g_cache_new().
  85 </para>
  86
  87 @cache: a #GCache.
  88 @value: the value to remove.
  89
  90
  91 <!-- ##### FUNCTION g_cache_destroy ##### -->
  92 <para>
  93 Frees the memory allocated for the #GCache.
  94 </para>
  95 <para>
  96 Note that it does not destroy the keys and values which were contained in the
  97 #GCache.
  98 </para>
  99
 100 @cache: a #GCache.
 101
 102
 103 <!-- ##### FUNCTION g_cache_key_foreach ##### -->
 104 <para>
 105 Calls the given function for each of the keys in the #GCache.
 106 </para>
 107
 108 @cache: a #GCache.
 109 @func: the function to call with each #GCache key.
 110 @user_data: user data to pass to the function.
 111
 112
 113 <!-- ##### FUNCTION g_cache_value_foreach ##### -->
 114 <para>
 115 Calls the given function for each of the values in the #GCache.
 116 </para>
 117
 118 @cache: a #GCache.
 119 @func: the function to call with each #GCache value.
 120 @user_data: user data to pass to the function.
 121
 122
 123 <!-- ##### USER_FUNCTION GCacheDestroyFunc ##### -->
 124 <para>
 125 Specifies the type of the @value_destroy_func and @key_destroy_func functions
 126 passed to g_cache_new().
 127 The functions are passed a pointer to the #GCache key or #GCache value and
 128 should free any memory and other resources associated with it.
 129 </para>
 130
 131 @value: the #GCache value to destroy.
 132
 133
 134 <!-- ##### USER_FUNCTION GCacheDupFunc ##### -->
 135 <para>
 136 Specifies the type of the @key_dup_func function passed to g_cache_new().
 137 The function is passed a key (<emphasis>not</emphasis> a value as the prototype implies) and
 138 should return a duplicate of the key.
 139 </para>
 140
 141 @value: the #GCache key to destroy (<emphasis>not</emphasis> a #GCache value as it seems).
 142 @Returns: a copy of the #GCache key.
 143
 144
 145 <!-- ##### USER_FUNCTION GCacheNewFunc ##### -->
 146 <para>
 147 Specifies the type of the @value_new_func function passed to g_cache_new().
 148 It is passed a #GCache key and should create the value corresponding to the
 149 key.
 150 </para>
 151
 152 @key: a #GCache key.
 153 @Returns: a new #GCache value corresponding to the key.
 154
 155