1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 caches allow sharing of complex data structures to save resources.
7 <!-- ##### SECTION Long_Description ##### -->
9 A #GCache allows sharing of complex data structures, in order to save
13 GTK+ uses a #GCache for both 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 GtkStyle or GdkGC is used instead of creating a new one.
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.
24 <!-- ##### SECTION See_Also ##### -->
29 <!-- ##### STRUCT GCache ##### -->
31 The #GCache struct is an opaque data structure containing information about
32 a #GCache. It should only be accesssed via the following functions.
36 <!-- ##### FUNCTION g_cache_new ##### -->
38 Creates a new #GCache.
41 @value_new_func: a function to create a new object given a key.
42 This is called by g_cache_insert() if an object with the given key
43 does not already exist.
44 @value_destroy_func: a function to destroy an object. It is
45 called by g_cache_remove() when the object is no longer needed (i.e. its
46 reference count drops to 0).
47 @key_dup_func: a function to copy a key. It is called by
48 g_cache_insert() if the key does not already exist in the #GCache.
49 @key_destroy_func: a function to destroy a key. It is
50 called by g_cache_remove() when the object is no longer needed (i.e. its
51 reference count drops to 0).
52 @hash_key_func: a function to create a hash value from a key.
53 @hash_value_func: a function to create a hash value from a value.
54 @key_equal_func: a function to compare two keys. It should return %TRUE if
55 the two keys are equivalent.
56 @Returns: a new #GCache.
59 <!-- ##### FUNCTION g_cache_insert ##### -->
61 Gets the value corresponding to the given key, creating it if necessary.
62 It first checks if the value already exists in the #GCache, by using
63 the @key_equal_func function passed to g_cache_new().
64 If it does already exist it is returned, and its reference count is increased
66 If the value does not currently exist, if is created by calling the
67 @value_new_func. The key is duplicated by calling
68 @key_dup_func and the duplicated key and value are inserted
73 @key: a key describing a #GCache object.
74 @Returns: a pointer to a #GCache value.
77 <!-- ##### FUNCTION g_cache_remove ##### -->
79 Decreases the reference count of the given value.
80 If it drops to 0 then the value and its corresponding key are destroyed,
81 using the @value_destroy_func and @key_destroy_func passed to g_cache_new().
85 @value: the value to remove.
88 <!-- ##### FUNCTION g_cache_destroy ##### -->
90 Frees the memory allocated for the GCache.
93 Note that it does not destroy the keys and values which were contained in the
100 <!-- ##### FUNCTION g_cache_key_foreach ##### -->
102 Calls the given function for each of the keys in the #GCache.
106 @func: the function to call with each #GCache key.
107 @user_data: user data to pass to the function.
110 <!-- ##### FUNCTION g_cache_value_foreach ##### -->
112 Calls the given function for each of the values in the #GCache.
116 @func: the function to call with each #GCache value.
117 @user_data: user data to pass to the function.
120 <!-- ##### USER_FUNCTION GCacheDestroyFunc ##### -->
122 Specifies the type of the @value_destroy_func and @key_destroy_func functions
123 passed to g_cache_new().
124 The functions are passed a pointer to the #GCache key or #GCache value and
125 should free any memory and other resources associated with it.
128 @value: the #GCache value to destroy.
131 <!-- ##### USER_FUNCTION GCacheDupFunc ##### -->
133 Specifies the type of the @key_dup_func function passed to g_cache_new().
134 The function is passed a key (<emphasis>not</emphasis> a value as the prototype implies) and
135 should return a duplicate of the key.
138 @value: the #GCache key to destroy (<emphasis>not</emphasis> a #GCache value as it seems).
139 @Returns: a copy of the #GCache key.
142 <!-- ##### USER_FUNCTION GCacheNewFunc ##### -->
144 Specifies the type of the @value_new_func function passed to g_cache_new().
145 It is passed a #GCache key and should create the value corresponding to the
150 @Returns: a new #GCache value corresponding to the key.