docs/reference/glib/tmpl/allocators.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Memory Allocators
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 allocates chunks of memory for #GList, #GSList and #GNode.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GAllocator is used as an efficient way to allocate small pieces of
  10 memory for use with the #GList, #GSList and #GNode data structures.
  11 It uses a #GMemChunk so elements are allocated in groups, rather than
  12 individually.
  13 </para>
  14 <para>
  15 The #GList, #GSList and #GNode implementations create default #GAllocator
  16 objects, which are probably sufficient for most purposes. These default
  17 allocators use blocks of 128 elements.
  18 </para>
  19 <para>
  20 To use your own #GAllocator, create it with g_allocator_new(). Then
  21 use g_list_push_allocator(), g_slist_push_allocator() or
  22 g_node_push_allocator() before any code which allocates new #GList, #GSList
  23 or #GNode elements respectively. After allocating the new elements, you must
  24 use g_list_pop_allocator(), g_slist_pop_allocator() or g_node_pop_allocator()
  25 to restore the previous allocators.
  26 </para>
  27 <para>
  28 Note that you cannot use the same allocator for #GList, #GSList and #GNode
  29 elements. Each must use separate allocators.
  30 </para>
  31
  32 <!-- ##### SECTION See_Also ##### -->
  33 <para>
  34
  35 </para>
  36
  37 <!-- ##### STRUCT GAllocator ##### -->
  38 <para>
  39 The <structname>GAllocator</structname> struct contains private data. and should only be accessed
  40 using the following functions.
  41 </para>
  42
  43
  44 <!-- ##### FUNCTION g_allocator_new ##### -->
  45 <para>
  46 Creates a new #GAllocator.
  47 </para>
  48
  49 @name: the name of the #GAllocator. This name is used to set the name of the
  50 #GMemChunk used by the #GAllocator, and is only used for debugging.
  51 @n_preallocs: the number of elements in each block of memory allocated.
  52 Larger blocks mean less calls to g_malloc(), but some memory may be wasted.
  53 (GLib uses 128 elements per block by default.) The value must be between 1
  54 and 65535.
  55 @Returns: a new #GAllocator.
  56
  57
  58 <!-- ##### FUNCTION g_allocator_free ##### -->
  59 <para>
  60 Frees all of the memory allocated by the #GAllocator.
  61 </para>
  62
  63 @allocator: a #GAllocator.
  64
  65