/src/wrappers/glib/library/data_types/glib_caches.e
Specman e | 141 lines | 7 code | 33 blank | 101 comment | 0 complexity | b97745d49b822a531aadf0853c78b81b MD5 | raw file
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