allocators.sgml

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

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

<refnamediv>
<refname>Memory Allocators</refname><refpurpose>allocates chunks of memory for <link linkend="GList">GList</link>, <link linkend="GSList">GSList</link> and <link linkend="GNode">GNode</link>.</refpurpose>
</refnamediv>

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

#include &lt;glib.h&gt;


struct      <link linkend="GAllocator">GAllocator</link>;
<link linkend="GAllocator">GAllocator</link>* <link linkend="g-allocator-new">g_allocator_new</link>                 (const <link linkend="gchar">gchar</link> *name,
                                             <link linkend="guint">guint</link> n_preallocs);
void        <link linkend="g-allocator-free">g_allocator_free</link>                (<link linkend="GAllocator">GAllocator</link> *allocator);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The <link linkend="GAllocator">GAllocator</link> is used as an efficient way to allocate small pieces of
memory for use with the <link linkend="GList">GList</link>, <link linkend="GSList">GSList</link> and <link linkend="GNode">GNode</link> data structures.
It uses a <link linkend="GMemChunk">GMemChunk</link> so elements are allocated in groups, rather than
individually.
</para>
<para>
The <link linkend="GList">GList</link>, <link linkend="GSList">GSList</link> and <link linkend="GNode">GNode</link> implementations create default <link linkend="GAllocator">GAllocator</link>
objects, which are probably sufficient for most purposes. These default
allocators use blocks of 128 elements.
</para>
<para>
To use your own <link linkend="GAllocator">GAllocator</link>, create it with <link linkend="g-allocator-new">g_allocator_new</link>(). Then
use <link linkend="g-list-push-allocator">g_list_push_allocator</link>(), <link linkend="g-slist-push-allocator">g_slist_push_allocator</link>() or
<link linkend="g-node-push-allocator">g_node_push_allocator</link>() before any code which allocates new <link linkend="GList">GList</link>, <link linkend="GSList">GSList</link>
or <link linkend="GNode">GNode</link> elements respectively. After allocating the new elements, you must
use <link linkend="g-list-pop-allocator">g_list_pop_allocator</link>(), <link linkend="g-slist-pop-allocator">g_slist_pop_allocator</link>() or <link linkend="g-node-pop-allocator">g_node_pop_allocator</link>()
to restore the previous allocators.
</para>
<para>
Note that you cannot use the same allocator for <link linkend="GList">GList</link>, <link linkend="GSList">GSList</link> and <link linkend="GNode">GNode</link>
elements. Each must use separate allocators.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GAllocator">struct GAllocator</title>
<programlisting>struct GAllocator;</programlisting>
<para>
The <structname>GAllocator</structname> struct contains private data. and should only be accessed
using the following functions.
</para></refsect2>
<refsect2>
<title><anchor id="g-allocator-new">g_allocator_new ()</title>
<programlisting><link linkend="GAllocator">GAllocator</link>* g_allocator_new                 (const <link linkend="gchar">gchar</link> *name,
                                             <link linkend="guint">guint</link> n_preallocs);</programlisting>
<para>
Creates a new <link linkend="GAllocator">GAllocator</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry>the name of the <link linkend="GAllocator">GAllocator</link>. This name is used to set the name of the
<link linkend="GMemChunk">GMemChunk</link> used by the <link linkend="GAllocator">GAllocator</link>, and is only used for debugging.
</entry></row>
<row><entry align="right"><parameter>n_preallocs</parameter>&nbsp;:</entry>
<entry>the number of elements in each block of memory allocated.
Larger blocks mean less calls to <link linkend="g-malloc">g_malloc</link>(), but some memory may be wasted.
(GLib uses 128 elements per block by default.) The value must be between 1
and 65535.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new <link linkend="GAllocator">GAllocator</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-allocator-free">g_allocator_free ()</title>
<programlisting>void        g_allocator_free                (<link linkend="GAllocator">GAllocator</link> *allocator);</programlisting>
<para>
Frees all of the memory allocated by the <link linkend="GAllocator">GAllocator</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>allocator</parameter>&nbsp;:</entry>
<entry>a <link linkend="GAllocator">GAllocator</link>.


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

</refsect1>




</refentry>