mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-08-01 23:13:40 +02:00
3fa33317b7
* glib/gconvert.c, glib/grand.c, glib/ghash.c,
glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
* glib/tmpl/allocators.sgml, glib/tmpl/arrays.sgml,
glib/tmpl/arrays_byte.sgml, glib/tmpl/arrays_pointer.sgml,
glib/tmpl/caches.sgml, glib/tmpl/completion.sgml,
glib/tmpl/conversions.sgml,
glib/tmpl/datalist.sgml, glib/tmpl/date.sgml,
glib/tmpl/error_reporting.sgml, glib/tmpl/fileutils.sgml,
glib/tmpl/hash_tables.sgml,
glib/tmpl/hooks.sgml, glib/tmpl/macros.sgml,
glib/tmpl/macros_misc.sgml, glib/tmpl/main.sgml, glib/tmpl/markup.sgml,
glib/tmpl/memory.sgml, glib/tmpl/memory_chunks.sgml,
glib/tmpl/messages.sgml, glib/tmpl/misc_utils.sgml,
glib/tmpl/modules.sgml, glib/tmpl/numerical.sgml,
glib/tmpl/patterns.sgml, glib/tmpl/queue.sgml,
glib/tmpl/shell.sgml, glib/tmpl/spawn.sgml,
glib/tmpl/string_utils.sgml, glib/tmpl/thread_pools.sgml,
glib/tmpl/threads.sgml, glib/tmpl/timers.sgml,
glib/tmpl/trees-binary.sgml, glib/tmpl/trees-nary.sgml,
glib/tmpl/type_conversion.sgml, glib/tmpl/unicode.sgml,
glib/tmpl/warnings.sgml, glib/tmpl/windows.sgml:
Improve markup of examples, general consistency improvements.
153 lines
4.6 KiB
Plaintext
153 lines
4.6 KiB
Plaintext
<!-- ##### 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 a #GCache for #GtkStyles; GDK uses one for #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>
|
|
|
|
<!-- ##### 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>
|
|
|
|
@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.
|
|
|
|
|
|
<!-- ##### 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.
|
|
|
|
|