allocators.xml   [plain text]

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

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GAllocator"/>struct GAllocator</title>
<indexterm><primary>GAllocator</primary></indexterm><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>
<indexterm><primary>g_allocator_new</primary></indexterm><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"><type>GAllocator</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara>the name of the <link linkend="GAllocator"><type>GAllocator</type></link>. This name is used to set the name of the
<link linkend="GMemChunk"><type>GMemChunk</type></link> used by the <link linkend="GAllocator"><type>GAllocator</type></link>, and is only used for debugging.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_preallocs</parameter>&nbsp;:</term>
<listitem><simpara>the number of elements in each block of memory allocated.
Larger blocks mean less calls to <link linkend="g-malloc"><function>g_malloc()</function></link>, but some memory may be wasted.
(GLib uses 128 elements per block by default.) The value must be between 1
and 65535.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a new <link linkend="GAllocator"><type>GAllocator</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-allocator-free"/>g_allocator_free ()</title>
<indexterm><primary>g_allocator_free</primary></indexterm><programlisting><link linkend="void">void</link>        g_allocator_free                (<link linkend="GAllocator">GAllocator</link> *allocator);</programlisting>
<para>
Frees all of the memory allocated by the <link linkend="GAllocator"><type>GAllocator</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>allocator</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GAllocator"><type>GAllocator</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>