GLib Reference Manual
<<< Previous PageHomeUpNext Page >>>

Caches

Name

Caches -- allows sharing of complex data structures to save resources.

Synopsis


#include <glib.h>


struct      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,
                                             GCompareFunc key_compare_func);
gpointer    g_cache_insert                  (GCache *cache,
                                             gpointer key);
void        g_cache_remove                  (GCache *cache,
                                             gpointer 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);

Description

A GCache allows sharing of complex data structures, in order to save system resources.

GTK uses a GCache for both GtkStyles and GdkGCs. These consume a lot of resouces, so a GCache is used to see if a GtkStyle or GdkGC with the required properties already exists. If it does, then the existing GtkStyle or GdkGC 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.

Details

struct GCache

struct GCache;

The GCache struct is an opaque data structure containing information about a GCache. It should only be accesssed via the following functions.

g_cache_new ()

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,
                                             GCompareFunc key_compare_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_compare_func :a function to compare two keys. It should return TRUE if the two keys are equivalent.
Returns :a new GCache.

g_cache_insert ()

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_compare_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.

cache :a GCache.
key :a key describing a GCache object.
Returns :a pointer to a GCache value.

g_cache_remove ()

void        g_cache_remove                  (GCache *cache,
                                             gpointer 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.

g_cache_destroy ()

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 : 

g_cache_key_foreach ()

void        g_cache_key_foreach             (GCache *cache,
                                             GHFunc func,
                                             gpointer user_data);

Calls the given function for each of the keys in the GCache.

cache :a GCache.
func :the function to call with each GCache key.
user_data :user data to pass to the function.

g_cache_value_foreach ()

void        g_cache_value_foreach           (GCache *cache,
                                             GHFunc func,
                                             gpointer user_data);

Calls the given function for each of the values in the GCache.

cache :a GCache.
func :the function to call with each GCache value.
user_data :user data to pass to the function.

GCacheDestroyFunc ()

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.

GCacheDupFunc ()

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.

value :the GCache key to destroy (NOT a GCache value as it seems).
Returns :a copy of the GCache key.

GCacheNewFunc ()

gpointer    (*GCacheNewFunc)                (gpointer key);

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.

key :a GCache key.
Returns :a new GCache value corresponding to the key.



<<< Previous PageHomeUpNext Page >>>
Relations and TuplesMemory Allocators