<!-- ##### 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 savesystem resources.</para><para>GTK+ uses caches for #GtkStyles and #GdkGCs. These consume a lot ofresources, so a #GCache is used to see if a #GtkStyle or #GdkGC with therequired properties already exists. If it does, then the existingobject 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 abouta #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 keydoes not already exist.@value_destroy_func: a function to destroy an object. It iscalled by g_cache_remove() when the object is no longer needed (i.e. itsreference count drops to 0).@key_dup_func: a function to copy a key. It is called byg_cache_insert() if the key does not already exist in the #GCache.@key_destroy_func: a function to destroy a key. It iscalled by g_cache_remove() when the object is no longer needed (i.e. itsreference 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 ifthe 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 usingthe @key_equal_func function passed to g_cache_new().If it does already exist it is returned, and its reference count is increasedby 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 insertedinto 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 acache entry and the @user_data. The order of value and key is differentfrom the order in which g_hash_table_foreach() passes key-value pairsto 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 functionspassed to g_cache_new().The functions are passed a pointer to the #GCache key or #GCache value andshould 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) andshould 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 thekey.</para>@key: a #GCache key.@Returns: a new #GCache value corresponding to the key.