| <!-- ##### SECTION Title ##### --> |
| Caches |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| caches allow sharing of complex data structures to save resources. |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| A #GCache allows sharing of complex data structures, in order to save |
| system resources. |
| </para> |
| <para> |
| GTK+ uses caches for #GtkStyles and #GdkGCs. These consume a lot of |
| resources, so a #GCache is used to see if a #GtkStyle or #GdkGC with the |
| required properties already exists. If it does, then the existing |
| object is used instead of creating a new one. |
| </para> |
| <para> |
| #GCache uses keys and values. |
| A #GCache key describes the properties of a particular resource. |
| A #GCache value is the actual resource. |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### STRUCT GCache ##### --> |
| <para> |
| The #GCache struct is an opaque data structure containing information about |
| a #GCache. It should only be accessed via the following functions. |
| </para> |
| |
| |
| <!-- ##### FUNCTION g_cache_new ##### --> |
| <para> |
| Creates a new #GCache. |
| </para> |
| |
| @value_new_func: a function to create a new object given a key. |
| This is called by g_cache_insert() if an object with the given key |
| does not already exist. |
| @value_destroy_func: a function to destroy an object. It is |
| called by g_cache_remove() when the object is no longer needed (i.e. its |
| reference count drops to 0). |
| @key_dup_func: a function to copy a key. It is called by |
| g_cache_insert() if the key does not already exist in the #GCache. |
| @key_destroy_func: a function to destroy a key. It is |
| called by g_cache_remove() when the object is no longer needed (i.e. its |
| reference count drops to 0). |
| @hash_key_func: a function to create a hash value from a key. |
| @hash_value_func: a function to create a hash value from a value. |
| @key_equal_func: a function to compare two keys. It should return %TRUE if |
| the two keys are equivalent. |
| @Returns: a new #GCache. |
| |
| |
| <!-- ##### FUNCTION g_cache_insert ##### --> |
| <para> |
| Gets the value corresponding to the given key, creating it if necessary. |
| It first checks if the value already exists in the #GCache, by using |
| the @key_equal_func function passed to g_cache_new(). |
| If it does already exist it is returned, and its reference count is increased |
| by one. |
| If the value does not currently exist, if is created by calling the |
| @value_new_func. The key is duplicated by calling |
| @key_dup_func and the duplicated key and value are inserted |
| into the #GCache. |
| </para> |
| |
| @cache: a #GCache. |
| @key: a key describing a #GCache object. |
| @Returns: a pointer to a #GCache value. |
| |
| |
| <!-- ##### FUNCTION g_cache_remove ##### --> |
| <para> |
| Decreases the reference count of the given value. |
| If it drops to 0 then the value and its corresponding key are destroyed, |
| using the @value_destroy_func and @key_destroy_func passed to g_cache_new(). |
| </para> |
| |
| @cache: a #GCache. |
| @value: the value to remove. |
| |
| |
| <!-- ##### FUNCTION g_cache_destroy ##### --> |
| <para> |
| Frees the memory allocated for the #GCache. |
| </para> |
| <para> |
| Note that it does not destroy the keys and values which were contained in the |
| #GCache. |
| </para> |
| |
| @cache: a #GCache. |
| |
| |
| <!-- ##### FUNCTION g_cache_key_foreach ##### --> |
| <para> |
| Calls the given function for each of the keys in the #GCache. |
| </para> |
| <note><para>@func is passed three parameters, the value and key of a |
| cache entry and the @user_data. The order of value and key is different |
| from the order in which g_hash_table_foreach() passes key-value pairs |
| to its callback function ! |
| </para></note> |
| |
| @cache: a #GCache. |
| @func: the function to call with each #GCache key. |
| @user_data: user data to pass to the function. |
| |
| |
| <!-- ##### FUNCTION g_cache_value_foreach ##### --> |
| <para> |
| Calls the given function for each of the values in the #GCache. |
| </para> |
| |
| @cache: a #GCache. |
| @func: the function to call with each #GCache value. |
| @user_data: user data to pass to the function. |
| @Deprecated: 2.10: The reason is that it passes pointers to internal data |
| structures to @func; use g_cache_key_foreach() instead |
| |
| |
| <!-- ##### USER_FUNCTION GCacheDestroyFunc ##### --> |
| <para> |
| Specifies the type of the @value_destroy_func and @key_destroy_func functions |
| passed to g_cache_new(). |
| The functions are passed a pointer to the #GCache key or #GCache value and |
| should free any memory and other resources associated with it. |
| </para> |
| |
| @value: the #GCache value to destroy. |
| |
| |
| <!-- ##### USER_FUNCTION GCacheDupFunc ##### --> |
| <para> |
| Specifies the type of the @key_dup_func function passed to g_cache_new(). |
| The function is passed a key (<emphasis>not</emphasis> a value as the prototype implies) and |
| should return a duplicate of the key. |
| </para> |
| |
| @value: the #GCache key to destroy (<emphasis>not</emphasis> a #GCache value as it seems). |
| @Returns: a copy of the #GCache key. |
| |
| |
| <!-- ##### USER_FUNCTION GCacheNewFunc ##### --> |
| <para> |
| Specifies the type of the @value_new_func function passed to g_cache_new(). |
| It is passed a #GCache key and should create the value corresponding to the |
| key. |
| </para> |
| |
| @key: a #GCache key. |
| @Returns: a new #GCache value corresponding to the key. |
| |
| |