+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-Caches
-
-<!-- ##### SECTION Short_Description ##### -->
-caches allow sharing of complex data structures to save resources
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-A #GCache allows sharing of complex data structures, in order to save
-system resources.
-</para>
-<para>
-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.
-</para>
-<para>
-#GCache uses keys and values.
-A #GCache key describes the properties of a particular resource.
-A #GCache value is the actual resource.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GCache ##### -->
-<para>
-The #GCache struct is an opaque data structure containing information about
-a #GCache. It should only be accessed via the following functions.
-</para>
-
-
-<!-- ##### FUNCTION g_cache_new ##### -->
-<para>
-Creates a new #GCache.
-</para>
-
-@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.
-
-
-<!-- ##### FUNCTION g_cache_insert ##### -->
-<para>
-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.
-</para>
-
-@cache: a #GCache.
-@key: a key describing a #GCache object.
-@Returns: a pointer to a #GCache value.
-
-
-<!-- ##### FUNCTION g_cache_remove ##### -->
-<para>
-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().
-</para>
-
-@cache: a #GCache.
-@value: the value to remove.
-
-
-<!-- ##### FUNCTION g_cache_destroy ##### -->
-<para>
-Frees the memory allocated for the #GCache.
-</para>
-<para>
-Note that it does not destroy the keys and values which were contained in the
-#GCache.
-</para>
-
-@cache: a #GCache.
-
-
-<!-- ##### FUNCTION g_cache_key_foreach ##### -->
-<para>
-Calls the given function for each of the keys in the #GCache.
-</para>
-<note><para>@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 !
-</para></note>
-
-@cache: a #GCache.
-@func: the function to call with each #GCache key.
-@user_data: user data to pass to the function.
-
-
-<!-- ##### FUNCTION g_cache_value_foreach ##### -->
-<para>
-Calls the given function for each of the values in the #GCache.
-</para>
-
-@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
-
-
-<!-- ##### USER_FUNCTION GCacheDestroyFunc ##### -->
-<para>
-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.
-</para>
-
-@value: the #GCache value to destroy.
-
-
-<!-- ##### USER_FUNCTION GCacheDupFunc ##### -->
-<para>
-Specifies the type of the @key_dup_func function passed to g_cache_new().
-The function is passed a key (<emphasis>not</emphasis> a value as the prototype implies) and
-should return a duplicate of the key.
-</para>
-
-@value: the #GCache key to destroy (<emphasis>not</emphasis> a #GCache value as it seems).
-@Returns: a copy of the #GCache key.
-
-
-<!-- ##### USER_FUNCTION GCacheNewFunc ##### -->
-<para>
-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.
-</para>
-
-@key: a #GCache key.
-@Returns: a new #GCache value corresponding to the key.
-
-
#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;
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 */
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 (<emphasis>not</emphasis> 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
+ * (<emphasis>not</emphasis> 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,
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)
{
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)
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)
}
}
+/**
+ * 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,
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,
projects / platform / upstream / glib.git / commitdiff