|  |  |  | GLib Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | ||||
#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.
| 
 | 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. | 
| 
 | 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). | 
| 
 | a function to copy a key. It is called by g_cache_insert()if the key does not already exist in
the GCache. | 
| 
 | 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). | 
| 
 | a function to create a hash value from a key. | 
| 
 | a function to create a hash value from a value. | 
| 
 | 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().
| 
 | a GCache. | 
| 
 | 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.
| 
 | 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.
NOTE 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 !
void g_cache_value_foreach (GCache *cache,GHFunc func,gpointer user_data);
g_cache_value_foreach has been deprecated since version 2.10 and should not be used in newly-written code. The reason is that it passes pointers to internal
                 data structures to func; use g_cache_key_foreach()
                 instead
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.
| 
 | 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.