caches.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Caches">
<refmeta>
<refentrytitle>Caches</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Caches</refname><refpurpose>caches allow sharing of complex data structures to save resources.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GCache">GCache</link>;
<link linkend="GCache">GCache</link>*     <link linkend="g-cache-new">g_cache_new</link>                     (<link linkend="GCacheNewFunc">GCacheNewFunc</link> value_new_func,
                                             <link linkend="GCacheDestroyFunc">GCacheDestroyFunc</link> value_destroy_func,
                                             <link linkend="GCacheDupFunc">GCacheDupFunc</link> key_dup_func,
                                             <link linkend="GCacheDestroyFunc">GCacheDestroyFunc</link> key_destroy_func,
                                             <link linkend="GHashFunc">GHashFunc</link> hash_key_func,
                                             <link linkend="GHashFunc">GHashFunc</link> hash_value_func,
                                             <link linkend="GEqualFunc">GEqualFunc</link> key_equal_func);
<link linkend="gpointer">gpointer</link>    <link linkend="g-cache-insert">g_cache_insert</link>                  (<link linkend="GCache">GCache</link> *cache,
                                             <link linkend="gpointer">gpointer</link> key);
void        <link linkend="g-cache-remove">g_cache_remove</link>                  (<link linkend="GCache">GCache</link> *cache,
                                             <link linkend="gconstpointer">gconstpointer</link> value);
void        <link linkend="g-cache-destroy">g_cache_destroy</link>                 (<link linkend="GCache">GCache</link> *cache);

void        <link linkend="g-cache-key-foreach">g_cache_key_foreach</link>             (<link linkend="GCache">GCache</link> *cache,
                                             <link linkend="GHFunc">GHFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data);
void        <link linkend="g-cache-value-foreach">g_cache_value_foreach</link>           (<link linkend="GCache">GCache</link> *cache,
                                             <link linkend="GHFunc">GHFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data);

void        (<link linkend="GCacheDestroyFunc">*GCacheDestroyFunc</link>)            (<link linkend="gpointer">gpointer</link> value);
<link linkend="gpointer">gpointer</link>    (<link linkend="GCacheDupFunc">*GCacheDupFunc</link>)                (<link linkend="gpointer">gpointer</link> value);
<link linkend="gpointer">gpointer</link>    (<link linkend="GCacheNewFunc">*GCacheNewFunc</link>)                (<link linkend="gpointer">gpointer</link> key);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
A <link linkend="GCache">GCache</link> allows sharing of complex data structures, in order to save
system resources.
</para>
<para>
GTK+ uses caches for <link linkend="GtkStyles">GtkStyles</link> and <link linkend="GdkGCs">GdkGCs</link>. These consume a lot of
resources, so a <link linkend="GCache">GCache</link> is used to see if a <link linkend="GtkStyle">GtkStyle</link> or <link linkend="GdkGC">GdkGC</link> with the
required properties already exists. If it does, then the existing
object is used instead of creating a new one.
</para>
<para>
<link linkend="GCache">GCache</link> uses keys and values.
A <link linkend="GCache">GCache</link> key describes the properties of a particular resource.
A <link linkend="GCache">GCache</link> value is the actual resource.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GCache">struct GCache</title>
<programlisting>struct GCache;</programlisting>
<para>
The <link linkend="GCache">GCache</link> struct is an opaque data structure containing information about
a <link linkend="GCache">GCache</link>. It should only be accessed via the following functions.
</para></refsect2>
<refsect2>
<title><anchor id="g-cache-new">g_cache_new ()</title>
<programlisting><link linkend="GCache">GCache</link>*     g_cache_new                     (<link linkend="GCacheNewFunc">GCacheNewFunc</link> value_new_func,
                                             <link linkend="GCacheDestroyFunc">GCacheDestroyFunc</link> value_destroy_func,
                                             <link linkend="GCacheDupFunc">GCacheDupFunc</link> key_dup_func,
                                             <link linkend="GCacheDestroyFunc">GCacheDestroyFunc</link> key_destroy_func,
                                             <link linkend="GHashFunc">GHashFunc</link> hash_key_func,
                                             <link linkend="GHashFunc">GHashFunc</link> hash_value_func,
                                             <link linkend="GEqualFunc">GEqualFunc</link> key_equal_func);</programlisting>
<para>
Creates a new <link linkend="GCache">GCache</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>value_new_func</parameter>&nbsp;:</entry>
<entry>a function to create a new object given a key.
This is called by <link linkend="g-cache-insert">g_cache_insert</link>() if an object with the given key
does not already exist.
</entry></row>
<row><entry align="right"><parameter>value_destroy_func</parameter>&nbsp;:</entry>
<entry>a function to destroy an object. It is
called by <link linkend="g-cache-remove">g_cache_remove</link>() when the object is no longer needed (i.e. its
reference count drops to 0).
</entry></row>
<row><entry align="right"><parameter>key_dup_func</parameter>&nbsp;:</entry>
<entry>a function to copy a key. It is called by
<link linkend="g-cache-insert">g_cache_insert</link>() if the key does not already exist in the <link linkend="GCache">GCache</link>.
</entry></row>
<row><entry align="right"><parameter>key_destroy_func</parameter>&nbsp;:</entry>
<entry>a function to destroy a key. It is
called by <link linkend="g-cache-remove">g_cache_remove</link>() when the object is no longer needed (i.e. its
reference count drops to 0).
</entry></row>
<row><entry align="right"><parameter>hash_key_func</parameter>&nbsp;:</entry>
<entry>a function to create a hash value from a key.
</entry></row>
<row><entry align="right"><parameter>hash_value_func</parameter>&nbsp;:</entry>
<entry>a function to create a hash value from a value.
</entry></row>
<row><entry align="right"><parameter>key_equal_func</parameter>&nbsp;:</entry>
<entry>a function to compare two keys. It should return <literal>TRUE</literal> if
the two keys are equivalent.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new <link linkend="GCache">GCache</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-cache-insert">g_cache_insert ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_cache_insert                  (<link linkend="GCache">GCache</link> *cache,
                                             <link linkend="gpointer">gpointer</link> key);</programlisting>
<para>
Gets the value corresponding to the given key, creating it if necessary.
It first checks if the value already exists in the <link linkend="GCache">GCache</link>, by using
the <parameter>key_equal_func</parameter> function passed to <link linkend="g-cache-new">g_cache_new</link>().
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
<parameter>value_new_func</parameter>. The key is duplicated by calling
<parameter>key_dup_func</parameter> and the duplicated key and value are inserted
into the <link linkend="GCache">GCache</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>cache</parameter>&nbsp;:</entry>
<entry>a <link linkend="GCache">GCache</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry>a key describing a <link linkend="GCache">GCache</link> object.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to a <link linkend="GCache">GCache</link> value.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>