|  |  |  | GLib Reference Manual |  | 
|---|
| CachesCaches — caches allow sharing of complex data structures to save resources. | 
#include <glib.h>
            GCache;
GCache*     g_cache_new                     (GCacheNewFunc value_new_func,
                                             GCacheDestroyFunc value_destroy_func,
                                             GCacheDupFunc key_dup_func,
                                             GCacheDestroyFunc key_destroy_func,
                                             GHashFunc hash_key_func,
                                             GHashFunc hash_value_func,
                                             GEqualFunc key_equal_func);
gpointer    g_cache_insert                  (GCache *cache,
                                             gpointer key);
void        g_cache_remove                  (GCache *cache,
                                             gconstpointer value);
void        g_cache_destroy                 (GCache *cache);
void        g_cache_key_foreach             (GCache *cache,
                                             GHFunc func,
                                             gpointer user_data);
void        g_cache_value_foreach           (GCache *cache,
                                             GHFunc func,
                                             gpointer user_data);
void        (*GCacheDestroyFunc)            (gpointer value);
gpointer    (*GCacheDupFunc)                (gpointer value);
gpointer    (*GCacheNewFunc)                (gpointer key);
A GCache allows sharing of complex data structures, in order to save system resources.
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.
GCache uses keys and values. A GCache key describes the properties of a particular resource. A GCache value is the actual resource.
typedef struct _GCache GCache;
The GCache struct is an opaque data structure containing information about a GCache. It should only be accessed via the following functions.
GCache* g_cache_new (GCacheNewFunc value_new_func, GCacheDestroyFunc value_destroy_func, GCacheDupFunc key_dup_func, GCacheDestroyFunc key_destroy_func, GHashFunc hash_key_func, GHashFunc hash_value_func, GEqualFunc key_equal_func);
Creates a new GCache.
| 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 TRUEif
the two keys are equivalent. | 
| Returns : | a new GCache. | 
gpointer g_cache_insert (GCache *cache, gpointer key);
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.
void g_cache_remove (GCache *cache, gconstpointer value);
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().
| cache: | a GCache. | 
| value: | the value to remove. | 
void g_cache_destroy (GCache *cache);
Frees the memory allocated for the GCache.
Note that it does not destroy the keys and values which were contained in the GCache.
| cache: | a GCache. | 
void g_cache_key_foreach (GCache *cache, GHFunc func, gpointer user_data);
Calls the given function for each of the keys in the GCache.
void g_cache_value_foreach (GCache *cache, GHFunc func, gpointer user_data);
Calls the given function for each of the values in the GCache.
void (*GCacheDestroyFunc) (gpointer value);
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.
| value: | the GCache value to destroy. | 
gpointer (*GCacheDupFunc) (gpointer value);
Specifies the type of the key_dup_func function passed to g_cache_new().
The function is passed a key (not a value as the prototype implies) and
should return a duplicate of the key.
| << Relations and Tuples | Memory Allocators >> |