mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-10 03:16:17 +01:00
GCache: move docs from tmpl to .c
This commit is contained in:
Ryan Lortie
parent
fa7cafae5c
commit
21a6b69f4f
1
docs/reference/glib/tmpl/.gitignore
vendored
1
docs/reference/glib/tmpl/.gitignore
vendored
@ -1,5 +1,6 @@
|
||||
allocators.sgml
|
||||
base64.sgml
|
||||
caches.sgml
|
||||
checksum.sgml
|
||||
completion.sgml
|
||||
datasets.sgml
|
||||
|
||||
@ -1,162 +0,0 @@
|
||||
<!-- ##### 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.
|
||||
|
||||
|
||||
134
glib/gcache.c
134
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 (<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,
|
||||
@ -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,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user