docs/reference/glib/tmpl/memory_slices.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Memory Slices
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 efficient way to allocate groups of equal-sized chunks of memory
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Memory slices provide a space-efficient and multi-processing scalable
  10 way to allocate equal-sized pieces of memory, just like the original
  11 #GMemChunks (from GLib &lt;= 2.8), while avoiding their excessive
  12 memory-waste, scalability and performance problems.
  13 </para>
  14
  15 <para>
  16 To achieve these goals, the slice allocator uses a sophisticated,
  17 layered design that has been inspired by Bonwick's slab allocator
  18 <footnote><para>
  19 <ulink url="http://citeseer.ist.psu.edu/bonwick94slab.html">[Bonwick94]</ulink> Jeff Bonwick, The slab allocator: An object-caching kernel
  20 memory allocator. USENIX 1994, and
  21 <ulink url="http://citeseer.ist.psu.edu/bonwick01magazines.html">[Bonwick01]</ulink> Bonwick and Jonathan Adams, Magazines and vmem: Extending the
  22 slab allocator to many cpu's and arbitrary resources. USENIX 2001
  23 </para></footnote>.
  24 It uses posix_memalign() to optimize allocations of many equally-sized
  25 chunks, and has per-thread free lists (the so-called magazine layer)
  26 to quickly satisfy allocation requests of already known structure sizes.
  27 This is accompanied by extra caching logic to keep freed memory around
  28 for some time before returning it to the system. Memory that is unused
  29 due to alignment constraints is used for cache colorization (random
  30 distribution of chunk addresses) to improve CPU cache utilization. The
  31 caching layer of the slice allocator adapts itself to high lock contention
  32 to improve scalability.
  33 </para>
  34
  35 <para>
  36 The slice allocator can allocate blocks as small as two pointers, and
  37 unlike malloc(), it does not reserve extra space per block. For large block
  38 sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the
  39 system malloc() implementation. For newly written code it is recommended
  40 to use the new <literal>g_slice</literal> API instead of g_malloc() and
  41 friends, as long as objects are not resized during their lifetime and the
  42 object size used at allocation time is still available when freeing.
  43 </para>
  44
  45 <example>
  46 <title>Using the slice allocator</title>
  47 <programlisting>
  48   gchar *mem[10000];
  49   gint i;
  50
  51   /* Allocate 10000 blocks. */
  52   for (i = 0; i &lt; 10000; i++)
  53     {
  54       mem[i] = g_slice_alloc (50);
  55
  56       /* Fill in the memory with some junk. */
  57       for (j = 0; j &lt; 50; j++)
  58         mem[i][j] = i * j;
  59     }
  60
  61   /* Now free all of the blocks. */
  62   for (i = 0; i &lt; 10000; i++)
  63     {
  64       g_slice_free1 (50, mem[i]);
  65     }
  66 </programlisting></example>
  67
  68 <example>
  69 <title>Using the slice allocator with data structures</title>
  70 <programlisting>
  71   GRealArray *array;
  72
  73   /* Allocate one block, using the g_slice_new(<!-- -->) macro. */
  74   array = g_slice_new (GRealArray);
  75
  76   /* We can now use array just like a normal pointer to a structure. */
  77   array->data            = NULL;
  78   array->len             = 0;
  79   array->alloc           = 0;
  80   array->zero_terminated = (zero_terminated ? 1 : 0);
  81   array->clear           = (clear ? 1 : 0);
  82   array->elt_size        = elt_size;
  83
  84   /* We can free the block, so it can be reused. */
  85   g_slice_free (GRealArray, array);
  86 </programlisting></example>
  87
  88 <!-- ##### SECTION See_Also ##### -->
  89 <para>
  90 </para>
  91
  92 <!-- ##### SECTION Stability_Level ##### -->
  93
  94
  95 <!-- ##### SECTION Image ##### -->
  96
  97
  98 <!-- ##### FUNCTION g_slice_alloc ##### -->
  99 <para>
 100 Allocates a block of memory from the slice allocator.
 101 The block adress handed out can be expected to be aligned
 102 to at least <literal>1 * sizeof (void*)</literal>,
 103 though in general slices are 2 * sizeof (void*) bytes aligned,
 104 if a malloc() fallback implementation is used instead,
 105 the alignment may be reduced in a libc dependent fashion.
 106 Note that the underlying slice allocation mechanism can
 107 be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
 108 environment variable.
 109 </para>
 110
 111 @block_size: the number of bytes to allocate
 112 @Returns: a pointer to the allocated memory block
 113 @Since: 2.10
 114
 115
 116 <!-- ##### FUNCTION g_slice_alloc0 ##### -->
 117 <para>
 118 Allocates a block of memory via g_slice_alloc()
 119 and initialize the returned memory to 0.
 120 Note that the underlying slice allocation mechanism can
 121 be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
 122 environment variable.
 123 </para>
 124
 125 @block_size: the number of bytes to allocate
 126 @Returns: a pointer to the allocated block
 127 @Since: 2.10
 128
 129
 130 <!-- ##### FUNCTION g_slice_copy ##### -->
 131 <para>
 132 Allocates a block of memory from the slice allocator and copies
 133 @block_size bytes into it from @mem_block.
 134 </para>
 135
 136 @block_size: the number of bytes to allocate
 137 @mem_block: the memory to copy
 138 @Returns: a pointer to the allocated memory block
 139 @Since: 2.14
 140
 141
 142 <!-- ##### FUNCTION g_slice_free1 ##### -->
 143 <para>
 144 Frees a block of memory. The memory must have been allocated via
 145 g_slice_alloc() or g_slice_alloc0()
 146 and the @block_size has to match the size specified upon allocation.
 147 Note that the exact release behaviour can be changed with the
 148 <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable,
 149 also see <link linkend="G_SLICE">G_SLICE</link> for related debugging options.
 150 </para>
 151
 152 @block_size: the size of the block
 153 @mem_block: a pointer to the block to free
 154 @Since: 2.10
 155
 156
 157 <!-- ##### FUNCTION g_slice_free_chain_with_offset ##### -->
 158 <para>
 159 Frees a linked list of memory blocks of structure type @type.
 160 The memory blocks must be equal-sized, allocated via
 161 g_slice_alloc() or g_slice_alloc0()
 162 and linked together by a @next pointer (similar to #GSList). The offset
 163 of the @next field in each block is passed as third argument.
 164 Note that the exact release behaviour can be changed with the
 165 <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable,
 166 also see <link linkend="G_SLICE">G_SLICE</link> for related debugging options.
 167 </para>
 168
 169 @block_size: the size of the blocks
 170 @mem_chain:  a pointer to the first block of the chain
 171 @next_offset: the offset of the @next field in the blocks
 172 @Since: 2.10
 173
 174
 175 <!-- ##### MACRO g_slice_new ##### -->
 176 <para>
 177 A convenience macro to allocate a block of memory from the slice allocator.
 178 It calls g_slice_alloc() with <literal>sizeof (@type)</literal> and casts
 179 the returned pointer to a pointer of the given type, avoiding a type cast
 180 in the source code.
 181 Note that the underlying slice allocation mechanism can
 182 be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
 183 environment variable.
 184 </para>
 185
 186 @type: the type to allocate, typically a structure name
 187 @Returns: a pointer to the allocated block, cast to a pointer to @type.
 188 @Since: 2.10
 189
 190
 191 <!-- ##### MACRO g_slice_new0 ##### -->
 192 <para>
 193 A convenience macro to allocate a block of memory from the slice allocator
 194 and set the memory to 0. It calls g_slice_alloc0() with
 195 <literal>sizeof (@type)</literal> and casts the returned pointer to a pointer
 196 of the given type, avoiding a type cast in the source code.
 197 Note that the underlying slice allocation mechanism can
 198 be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
 199 environment variable.
 200 </para>
 201
 202 @type: the type to allocate, typically a structure name
 203 @Returns: a pointer to the allocated block, cast to a pointer to @type.
 204 @Since: 2.10
 205
 206
 207 <!-- ##### MACRO g_slice_dup ##### -->
 208 <para>
 209 A convenience macro to duplicate a block of memory using the slice allocator.
 210 It calls g_slice_copy() with <literal>sizeof (@type)</literal> and casts
 211 the returned pointer to a pointer of the given type, avoiding a type cast
 212 in the source code.
 213 Note that the underlying slice allocation mechanism can
 214 be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
 215 environment variable.
 216 </para>
 217
 218 @type: the type to duplicate, typically a structure name
 219 @mem: the memory to copy into the allocated block
 220 @Returns: a pointer to the allocated block, cast to a pointer to @type.
 221 @Since: 2.14
 222
 223
 224 <!-- ##### MACRO g_slice_free ##### -->
 225 <para>
 226 A convenience macro to free a block of memory that has been allocated
 227 from the slice allocator. It calls g_slice_free1() using
 228 <literal>sizeof (type)</literal> as the block size.
 229 Note that the exact release behaviour can be changed with the
 230 <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable,
 231 also see <link linkend="G_SLICE">G_SLICE</link> for related debugging options.
 232 </para>
 233
 234 @type: the type of the block to free, typically a structure name
 235 @mem: a pointer to the block to free
 236 @Since: 2.10
 237
 238
 239 <!-- ##### MACRO g_slice_free_chain ##### -->
 240 <para>
 241 Frees a linked list of memory blocks of structure type @type.
 242 The memory blocks must be equal-sized, allocated via
 243 g_slice_alloc() or g_slice_alloc0() and linked together by a
 244 @next pointer (similar to #GSList). The name of the
 245 @next field in @type is passed as third argument.
 246 Note that the exact release behaviour can be changed with the
 247 <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable,
 248 also see <link linkend="G_SLICE">G_SLICE</link> for related debugging options.
 249 </para>
 250
 251 @type:        the type of the @mem_chain blocks
 252 @mem_chain:   a pointer to the first block of the chain
 253 @next:        the field name of the next pointer in @type
 254 @Since: 2.10
 255
 256