luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-07-31 06:13:29 +02:00
Code Issues Packages Projects Releases Wiki Activity

GCache: move docs from tmpl to .c

Browse Source
This commit is contained in:
Ryan Lortie
2010-01-31 00:10:58 -05:00
parent fa7cafae5c
commit 21a6b69f4f
3 changed files with 135 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@@ -1,5 +1,6 @@
allocators.sgml
base64.sgml
caches.sgml
checksum.sgml
completion.sgml
datasets.sgml

162
docs/reference/glib/tmpl/caches.sgml
View File

@@ -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.