docs/reference/glib/tmpl/allocators.sgml

<!-- ##### SECTION Title ##### -->
Memory Allocators

<!-- ##### SECTION Short_Description ##### -->
allocates chunks of memory for #GList, #GSList and #GNode.

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

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GAllocator ##### -->
<para>
The <structname>GAllocator</structname> struct contains private data. and should only be accessed
using the following functions.
</para>


<!-- ##### FUNCTION g_allocator_new ##### -->
<para>
Creates a new #GAllocator.
</para>

@name: the name of the #GAllocator. This name is used to set the name of the
#GMemChunk used by the #GAllocator, and is only used for debugging.
@n_preallocs: the number of elements in each block of memory allocated.
Larger blocks mean less calls to g_malloc(), but some memory may be wasted.
(GLib uses 128 elements per block by default.) The value must be between 1
and 65535.
@Returns: a new #GAllocator.


<!-- ##### FUNCTION g_allocator_free ##### -->
<para>
Frees all of the memory allocated by the #GAllocator.
</para>

@allocator: a #GAllocator.