mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-14 21:36:13 +01:00
332 lines
10 KiB
Plaintext
332 lines
10 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Memory Chunks
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
deprecated way to allocate groups of equal-sized chunks of memory.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
Memory chunks provide an space-efficient way to allocate equal-sized
|
|
pieces of memory, called atoms. However, due to the administrative
|
|
overhead (in particular for #G_ALLOC_AND_FREE, and when used from multiple
|
|
threads), they are in practise often slower than direct use of g_malloc().
|
|
Therefore, memory chunks have been deprecated in favor of the
|
|
<link linkend="glib-Memory-Slices">slice allocator</link>,
|
|
which has been added in 2.10. All internal uses of memory chunks in
|
|
GLib have been converted to the <literal>g_slice</literal> API.
|
|
</para>
|
|
<para>
|
|
There are two types of memory chunks, #G_ALLOC_ONLY, and #G_ALLOC_AND_FREE.
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
#G_ALLOC_ONLY chunks only allow allocation of atoms. The atoms can never
|
|
be freed individually. The memory chunk can only be free in its entirety.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
#G_ALLOC_AND_FREE chunks do allow atoms to be freed individually.
|
|
The disadvantage of this is that the memory chunk has to keep track of which
|
|
atoms have been freed. This results in more memory being used and a slight
|
|
degradation in performance.
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
To create a memory chunk use g_mem_chunk_new() or the convenience macro
|
|
g_mem_chunk_create().
|
|
</para>
|
|
<para>
|
|
To allocate a new atom use g_mem_chunk_alloc(), g_mem_chunk_alloc0(),
|
|
or the convenience macros g_chunk_new() or g_chunk_new0().
|
|
</para>
|
|
<para>
|
|
To free an atom use g_mem_chunk_free(), or the convenience macro
|
|
g_chunk_free(). (Atoms can only be freed if the memory chunk is created
|
|
with the type set to #G_ALLOC_AND_FREE.)
|
|
</para>
|
|
<para>
|
|
To free any blocks of memory which are no longer being used, use
|
|
g_mem_chunk_clean(). To clean all memory chunks, use g_blow_chunks().
|
|
</para>
|
|
<para>
|
|
To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset().
|
|
</para>
|
|
<para>
|
|
To destroy a memory chunk, use g_mem_chunk_destroy().
|
|
</para>
|
|
<para>
|
|
To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print().
|
|
</para>
|
|
|
|
<example>
|
|
<title>Using a <structname>GMemChunk</structname></title>
|
|
<programlisting>
|
|
GMemChunk *mem_chunk;
|
|
gchar *mem[10000];
|
|
gint i;
|
|
|
|
/* Create a GMemChunk with atoms 50 bytes long, and memory blocks holding
|
|
100 bytes. Note that this means that only 2 atoms fit into each memory
|
|
block and so isn't very efficient. */
|
|
mem_chunk = g_mem_chunk_new ("test mem chunk", 50, 100, G_ALLOC_AND_FREE);
|
|
|
|
/* Now allocate 10000 atoms. */
|
|
for (i = 0; i < 10000; i++)
|
|
{
|
|
mem[i] = g_chunk_new (gchar, mem_chunk);
|
|
|
|
/* Fill in the atom memory with some junk. */
|
|
for (j = 0; j < 50; j++)
|
|
mem[i][j] = i * j;
|
|
}
|
|
|
|
/* Now free all of the atoms. Note that since we are going to destroy the
|
|
GMemChunk, this wouldn't normally be used. */
|
|
for (i = 0; i < 10000; i++)
|
|
{
|
|
g_mem_chunk_free (mem_chunk, mem[i]);
|
|
}
|
|
|
|
/* We are finished with the GMemChunk, so we destroy it. */
|
|
g_mem_chunk_destroy (mem_chunk);
|
|
</programlisting></example>
|
|
|
|
<example>
|
|
<title>Using a <structname>GMemChunk</structname> with data structures</title>
|
|
<programlisting>
|
|
GMemChunk *array_mem_chunk;
|
|
GRealArray *array;
|
|
|
|
/* Create a GMemChunk to hold GRealArray structures, using the
|
|
g_mem_chunk_create(<!-- -->) convenience macro. We want 1024 atoms in each
|
|
memory block, and we want to be able to free individual atoms. */
|
|
array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE);
|
|
|
|
/* Allocate one atom, using the g_chunk_new(<!-- -->) convenience macro. */
|
|
array = g_chunk_new (GRealArray, array_mem_chunk);
|
|
|
|
/* We can now use array just like a normal pointer to a structure. */
|
|
array->data = NULL;
|
|
array->len = 0;
|
|
array->alloc = 0;
|
|
array->zero_terminated = (zero_terminated ? 1 : 0);
|
|
array->clear = (clear ? 1 : 0);
|
|
array->elt_size = elt_size;
|
|
|
|
/* We can free the element, so it can be reused. */
|
|
g_chunk_free (array, array_mem_chunk);
|
|
|
|
/* We destroy the GMemChunk when we are finished with it. */
|
|
g_mem_chunk_destroy (array_mem_chunk);
|
|
</programlisting></example>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### STRUCT GMemChunk ##### -->
|
|
<para>
|
|
The #GMemChunk struct is an opaque data structure representing a memory
|
|
chunk. It should be accessed only through the use of the following functions.
|
|
</para>
|
|
|
|
|
|
<!-- ##### MACRO G_ALLOC_AND_FREE ##### -->
|
|
<para>
|
|
Specifies the type of a #GMemChunk.
|
|
Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms
|
|
will be freed individually.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_ALLOC_ONLY ##### -->
|
|
<para>
|
|
Specifies the type of a #GMemChunk.
|
|
Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms
|
|
will never be freed individually.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_chunk_new ##### -->
|
|
<para>
|
|
Creates a new #GMemChunk.
|
|
</para>
|
|
|
|
@name: a string to identify the #GMemChunk. It is not copied so it
|
|
should be valid for the lifetime of the #GMemChunk. It is only used in
|
|
g_mem_chunk_print(), which is used for debugging.
|
|
@atom_size: the size, in bytes, of each element in the #GMemChunk.
|
|
@area_size: the size, in bytes, of each block of memory allocated to contain
|
|
the atoms.
|
|
@type: the type of the #GMemChunk.
|
|
#G_ALLOC_AND_FREE is used if the atoms will be freed individually.
|
|
#G_ALLOC_ONLY should be used if atoms will never be freed individually.
|
|
#G_ALLOC_ONLY is quicker, since it does not need to track free atoms,
|
|
but it obviously wastes memory if you no longer need many of the atoms.
|
|
@Returns: the new #GMemChunk.
|
|
@Deprecated: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
instead
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_chunk_alloc ##### -->
|
|
<para>
|
|
Allocates an atom of memory from a #GMemChunk.
|
|
</para>
|
|
|
|
@mem_chunk: a #GMemChunk.
|
|
@Returns: a pointer to the allocated atom.
|
|
@Deprecated: Use g_slice_alloc() instead
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_chunk_alloc0 ##### -->
|
|
<para>
|
|
Allocates an atom of memory from a #GMemChunk, setting the memory to 0.
|
|
</para>
|
|
|
|
@mem_chunk: a #GMemChunk.
|
|
@Returns: a pointer to the allocated atom.
|
|
@Deprecated: Use g_slice_alloc0() instead
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_chunk_free ##### -->
|
|
<para>
|
|
Frees an atom in a #GMemChunk.
|
|
This should only be called if the #GMemChunk was created with
|
|
#G_ALLOC_AND_FREE. Otherwise it will simply return.
|
|
</para>
|
|
|
|
@mem_chunk: a #GMemChunk.
|
|
@mem: a pointer to the atom to free.
|
|
@Deprecated: Use g_slice_free1() instead
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_chunk_destroy ##### -->
|
|
<para>
|
|
Frees all of the memory allocated for a #GMemChunk.
|
|
</para>
|
|
|
|
@mem_chunk: a #GMemChunk.
|
|
@Deprecated: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
instead
|
|
|
|
|
|
<!-- ##### MACRO g_mem_chunk_create ##### -->
|
|
<para>
|
|
A convenience macro for creating a new #GMemChunk.
|
|
It calls g_mem_chunk_new(), using the given type to create the #GMemChunk
|
|
name. The atom size is determined using <function>sizeof()</function>, and the
|
|
area size is calculated by multiplying the @pre_alloc parameter with
|
|
the atom size.
|
|
</para>
|
|
|
|
@type: the type of the atoms, typically a structure name.
|
|
@pre_alloc: the number of atoms to store in each block of memory.
|
|
@alloc_type: the type of the #GMemChunk.
|
|
#G_ALLOC_AND_FREE is used if the atoms will be freed individually.
|
|
#G_ALLOC_ONLY should be used if atoms will never be freed individually.
|
|
#G_ALLOC_ONLY is quicker, since it does not need to track free atoms,
|
|
but it obviously wastes memory if you no longer need many of the atoms.
|
|
@Returns: the new #GMemChunk.
|
|
@Deprecated: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
instead
|
|
|
|
|
|
<!-- ##### MACRO g_chunk_new ##### -->
|
|
<para>
|
|
A convenience macro to allocate an atom of memory from a #GMemChunk.
|
|
It calls g_mem_chunk_alloc() and casts the returned atom to a pointer to
|
|
the given type, avoiding a type cast in the source code.
|
|
</para>
|
|
|
|
@type: the type of the #GMemChunk atoms, typically a structure name.
|
|
@chunk: a #GMemChunk.
|
|
@Returns: a pointer to the allocated atom, cast to a pointer to @type.
|
|
@Deprecated: Use g_slice_new() instead
|
|
|
|
|
|
<!-- ##### MACRO g_chunk_new0 ##### -->
|
|
<para>
|
|
A convenience macro to allocate an atom of memory from a #GMemChunk.
|
|
It calls g_mem_chunk_alloc0() and casts the returned atom to a pointer to
|
|
the given type, avoiding a type cast in the source code.
|
|
</para>
|
|
|
|
@type: the type of the #GMemChunk atoms, typically a structure name.
|
|
@chunk: a #GMemChunk.
|
|
@Returns: a pointer to the allocated atom, cast to a pointer to @type.
|
|
@Deprecated: Use g_slice_new0() instead
|
|
|
|
|
|
<!-- ##### MACRO g_chunk_free ##### -->
|
|
<para>
|
|
A convenience macro to free an atom of memory from a #GMemChunk.
|
|
It simply switches the arguments and calls g_mem_chunk_free()
|
|
It is included simply to complement the other convenience macros, g_chunk_new()
|
|
and g_chunk_new0().
|
|
</para>
|
|
|
|
@mem: a pointer to the atom to be freed.
|
|
@mem_chunk: a #GMemChunk.
|
|
@Deprecated: Use g_slice_free() instead
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_chunk_reset ##### -->
|
|
<para>
|
|
Resets a GMemChunk to its initial state.
|
|
It frees all of the currently allocated blocks of memory.
|
|
</para>
|
|
|
|
@mem_chunk: a #GMemChunk.
|
|
@Deprecated: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
instead
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_chunk_clean ##### -->
|
|
<para>
|
|
Frees any blocks in a #GMemChunk which are no longer being used.
|
|
</para>
|
|
|
|
@mem_chunk: a #GMemChunk.
|
|
@Deprecated: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
instead
|
|
|
|
|
|
<!-- ##### FUNCTION g_blow_chunks ##### -->
|
|
<para>
|
|
Calls g_mem_chunk_clean() on all #GMemChunk objects.
|
|
</para>
|
|
|
|
@Deprecated: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
instead
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_chunk_info ##### -->
|
|
<para>
|
|
Outputs debugging information for all #GMemChunk objects currently in use.
|
|
It outputs the number of #GMemChunk objects currently allocated,
|
|
and calls g_mem_chunk_print() to output information on each one.
|
|
</para>
|
|
|
|
@Deprecated: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
instead
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_chunk_print ##### -->
|
|
<para>
|
|
Outputs debugging information for a #GMemChunk.
|
|
It outputs the name of the #GMemChunk (set with g_mem_chunk_new()),
|
|
the number of bytes used, and the number of blocks of memory allocated.
|
|
</para>
|
|
|
|
@mem_chunk: a #GMemChunk.
|
|
@Deprecated: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
instead
|
|
|
|
|