/src/wrappers/glib/library/data_types/glib_caches.e

  1indexing
  2	copyright: "(C) 2005 Paolo Redaelli "
  3	license: "LGPL v2 or later"
  4	date: "$Date:$"
  5	revision: "$REvision:$"
  6
  7class GLIB_CACHES
  8-- 	Prev 	Up 	Home 	GLib Reference Manual 	Next
  9-- Top  |  Description
 10-- Caches
 11
 12-- Caches %G —%@ caches allow sharing of complex data structures to save resources.
 13	
 14-- Synopsis
 15
 16-- #include <glib.h>
 17
 18
 19--             GCache;
 20-- GCache*     g_cache_new                     (GCacheNewFunc value_new_func,
 21--                                              GCacheDestroyFunc value_destroy_func,
 22--                                              GCacheDupFunc key_dup_func,
 23--                                              GCacheDestroyFunc key_destroy_func,
 24--                                              GHashFunc hash_key_func,
 25--                                              GHashFunc hash_value_func,
 26--                                              GEqualFunc key_equal_func);
 27-- gpointer    g_cache_insert                  (GCache *cache,
 28--                                              gpointer key);
 29-- void        g_cache_remove                  (GCache *cache,
 30--                                              gconstpointer value);
 31-- void        g_cache_destroy                 (GCache *cache);
 32
 33-- void        g_cache_key_foreach             (GCache *cache,
 34--                                              GHFunc func,
 35--                                              gpointer user_data);
 36-- void        g_cache_value_foreach           (GCache *cache,
 37--                                              GHFunc func,
 38--                                              gpointer user_data);
 39
 40-- void        (*GCacheDestroyFunc)            (gpointer value);
 41-- gpointer    (*GCacheDupFunc)                (gpointer value);
 42-- gpointer    (*GCacheNewFunc)                (gpointer key);
 43
 44-- Description
 45
 46-- A GCache allows sharing of complex data structures, in order to save system resources.
 47
 48-- 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.
 49
 50-- GCache uses keys and values. A GCache key describes the properties of a particular resource. A GCache value is the actual resource.
 51-- Details
 52-- GCache
 53
 54-- typedef struct _GCache GCache;
 55
 56-- The GCache struct is an opaque data structure containing information about a GCache. It should only be accessed via the following functions.
 57-- g_cache_new ()
 58
 59-- GCache*     g_cache_new                     (GCacheNewFunc value_new_func,
 60--                                              GCacheDestroyFunc value_destroy_func,
 61--                                              GCacheDupFunc key_dup_func,
 62--                                              GCacheDestroyFunc key_destroy_func,
 63--                                              GHashFunc hash_key_func,
 64--                                              GHashFunc hash_value_func,
 65--                                              GEqualFunc key_equal_func);
 66
 67-- Creates a new GCache.
 68-- 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.
 69-- 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).
 70-- 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.
 71-- 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).
 72-- hash_key_func : 	a function to create a hash value from a key.
 73-- hash_value_func : 	a function to create a hash value from a value.
 74-- key_equal_func : 	a function to compare two keys. It should return TRUE if the two keys are equivalent.
 75-- Returns : 	a new GCache.
 76-- g_cache_insert ()
 77
 78-- gpointer    g_cache_insert                  (GCache *cache,
 79--                                              gpointer key);
 80
 81-- 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.
 82-- cache : 	a GCache.
 83-- key : 	a key describing a GCache object.
 84-- Returns : 	a pointer to a GCache value.
 85-- g_cache_remove ()
 86
 87-- void        g_cache_remove                  (GCache *cache,
 88--                                              gconstpointer value);
 89
 90-- 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().
 91-- cache : 	a GCache.
 92-- value : 	the value to remove.
 93-- g_cache_destroy ()
 94
 95-- void        g_cache_destroy                 (GCache *cache);
 96
 97-- Frees the memory allocated for the GCache.
 98
 99-- Note that it does not destroy the keys and values which were contained in the GCache.
100-- cache : 	a GCache.
101-- g_cache_key_foreach ()
102
103-- void        g_cache_key_foreach             (GCache *cache,
104--                                              GHFunc func,
105--                                              gpointer user_data);
106
107-- Calls the given function for each of the keys in the GCache.
108-- cache : 	a GCache.
109-- func : 	the function to call with each GCache key.
110-- user_data : 	user data to pass to the function.
111-- g_cache_value_foreach ()
112
113-- void        g_cache_value_foreach           (GCache *cache,
114--                                              GHFunc func,
115--                                              gpointer user_data);
116
117-- Calls the given function for each of the values in the GCache.
118-- cache : 	a GCache.
119-- func : 	the function to call with each GCache value.
120-- user_data : 	user data to pass to the function.
121-- GCacheDestroyFunc ()
122
123-- void        (*GCacheDestroyFunc)            (gpointer value);
124
125-- 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.
126-- value : 	the GCache value to destroy.
127-- GCacheDupFunc ()
128
129-- gpointer    (*GCacheDupFunc)                (gpointer value);
130
131-- 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.
132-- value : 	the GCache key to destroy (not a GCache value as it seems).
133-- Returns : 	a copy of the GCache key.
134-- GCacheNewFunc ()
135
136-- gpointer    (*GCacheNewFunc)                (gpointer key);
137
138-- 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.
139-- key : 	a GCache key.
140-- Returns : 	a new GCache value corresponding to the key.
141end