From 21a6b69f4fe85948e6e97650ccdd6e280098a790 Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Sun, 31 Jan 2010 00:10:58 -0500 Subject: [PATCH] GCache: move docs from tmpl to .c --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/caches.sgml | 162 ----------------------------------- glib/gcache.c | 134 +++++++++++++++++++++++++++++ 3 files changed, 135 insertions(+), 162 deletions(-) delete mode 100644 docs/reference/glib/tmpl/caches.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index 3dcf262..da42f15 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -1,5 +1,6 @@ allocators.sgml base64.sgml +caches.sgml checksum.sgml completion.sgml datasets.sgml diff --git a/docs/reference/glib/tmpl/caches.sgml b/docs/reference/glib/tmpl/caches.sgml deleted file mode 100644 index 1636234..0000000 --- a/docs/reference/glib/tmpl/caches.sgml +++ /dev/null @@ -1,162 +0,0 @@ - -Caches - - -caches allow sharing of complex data structures to save resources - - - -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. - - - - - - - - - - - - -The #GCache struct is an opaque data structure containing information about -a #GCache. It should only be accessed via the following functions. - - - - - -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 %TRUE if -the two keys are equivalent. -@Returns: a new #GCache. - - - - -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. - - -@cache: a #GCache. -@key: a key describing a #GCache object. -@Returns: a pointer to a #GCache 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. - - - - -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. - - - - -Calls the given function for each of the keys in the #GCache. - -@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 ! - - -@cache: a #GCache. -@func: the function to call with each #GCache key. -@user_data: user data to pass to the function. - - - - -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. -@Deprecated: 2.10: The reason is that it passes pointers to internal data -structures to @func; use g_cache_key_foreach() instead - - - - -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. - - - - -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. - - - - -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. - - diff --git a/glib/gcache.c b/glib/gcache.c index a5b0297..9c69122 100644 --- a/glib/gcache.c +++ b/glib/gcache.c @@ -33,6 +33,23 @@ #include "glib.h" #include "galias.h" +/** + * SECTION: caches + * @title: Caches + * @short_description: caches allow sharing of complex data structures + * to save resources + * + * 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 _GCacheNode GCacheNode; @@ -43,6 +60,13 @@ struct _GCacheNode gint ref_count; }; +/** + * GCache: + * + * The #GCache struct is an opaque data structure containing + * information about a #GCache. It should only be accessed via the + * following functions. + **/ struct _GCache { /* Called to create a value from a key */ @@ -79,6 +103,58 @@ g_cache_node_destroy (GCacheNode *node) g_slice_free (GCacheNode, node); } +/** + * g_cache_new: + * @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 + * %TRUE if the two keys are equivalent. + * @Returns: a new #GCache. + * + * Creates a new #GCache. + **/ +/** + * GCacheNewFunc: + * @key: a #GCache key. + * @Returns: a new #GCache value corresponding to the 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. + **/ +/** + * GCacheDestroyFunc: + * @value: the #GCache value to destroy. + * + * 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. + **/ +/** + * GCacheDupFunc: + * @value: the #GCache key to destroy (not a + * #GCache value as it seems). + * @Returns: a copy of the #GCache key. + * + * 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. + **/ GCache* g_cache_new (GCacheNewFunc value_new_func, GCacheDestroyFunc value_destroy_func, @@ -109,6 +185,15 @@ g_cache_new (GCacheNewFunc value_new_func, return cache; } +/** + * g_cache_destroy: + * @cache: a #GCache. + * + * Frees the memory allocated for the #GCache. + * + * Note that it does not destroy the keys and values which were + * contained in the #GCache. + **/ void g_cache_destroy (GCache *cache) { @@ -119,6 +204,21 @@ g_cache_destroy (GCache *cache) g_slice_free (GCache, cache); } +/** + * g_cache_insert: + * @cache: a #GCache. + * @key: a key describing a #GCache object. + * @Returns: a pointer to a #GCache value. + * + * 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. + **/ gpointer g_cache_insert (GCache *cache, gpointer key) @@ -145,6 +245,15 @@ g_cache_insert (GCache *cache, return node->value; } +/** + * g_cache_remove: + * @cache: a #GCache. + * @value: the value to remove. + * + * 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(). + **/ void g_cache_remove (GCache *cache, gconstpointer value) @@ -171,6 +280,19 @@ g_cache_remove (GCache *cache, } } +/** + * g_cache_key_foreach: + * @cache: a #GCache. + * @func: the function to call with each #GCache key. + * @user_data: user data to pass to the function. + * + * 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_key_foreach (GCache *cache, GHFunc func, @@ -182,6 +304,18 @@ g_cache_key_foreach (GCache *cache, g_hash_table_foreach (cache->value_table, func, user_data); } +/** + * g_cache_value_foreach: + * @cache: a #GCache. + * @func: the function to call with each #GCache value. + * @user_data: user data to pass to the function. + * + * Calls the given function for each of the values in the #GCache. + * + * Deprecated:2.10: The reason is that it passes pointers to internal + * data structures to @func; use g_cache_key_foreach() + * instead + **/ void g_cache_value_foreach (GCache *cache, GHFunc func, -- 2.7.4