memory_chunks.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Memory-Chunks">
<refmeta>
<refentrytitle>Memory Chunks</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Memory Chunks</refname><refpurpose>efficient way to allocate groups of equal-sized chunks of memory.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GMemChunk">GMemChunk</link>;
#define     <link linkend="G-ALLOC-AND-FREE-CAPS">G_ALLOC_AND_FREE</link>
#define     <link linkend="G-ALLOC-ONLY-CAPS">G_ALLOC_ONLY</link>

<link linkend="GMemChunk">GMemChunk</link>*  <link linkend="g-mem-chunk-new">g_mem_chunk_new</link>                 (const <link linkend="gchar">gchar</link> *name,
                                             <link linkend="gint">gint</link> atom_size,
                                             <link linkend="gulong">gulong</link> area_size,
                                             <link linkend="gint">gint</link> type);
<link linkend="gpointer">gpointer</link>    <link linkend="g-mem-chunk-alloc">g_mem_chunk_alloc</link>               (<link linkend="GMemChunk">GMemChunk</link> *mem_chunk);
<link linkend="gpointer">gpointer</link>    <link linkend="g-mem-chunk-alloc0">g_mem_chunk_alloc0</link>              (<link linkend="GMemChunk">GMemChunk</link> *mem_chunk);
void        <link linkend="g-mem-chunk-free">g_mem_chunk_free</link>                (<link linkend="GMemChunk">GMemChunk</link> *mem_chunk,
                                             <link linkend="gpointer">gpointer</link> mem);
void        <link linkend="g-mem-chunk-destroy">g_mem_chunk_destroy</link>             (<link linkend="GMemChunk">GMemChunk</link> *mem_chunk);

#define     <link linkend="g-mem-chunk-create">g_mem_chunk_create</link>              (type, pre_alloc, alloc_type)
#define     <link linkend="g-chunk-new">g_chunk_new</link>                     (type, chunk)
#define     <link linkend="g-chunk-new0">g_chunk_new0</link>                    (type, chunk)
#define     <link linkend="g-chunk-free">g_chunk_free</link>                    (mem, mem_chunk)

void        <link linkend="g-mem-chunk-reset">g_mem_chunk_reset</link>               (<link linkend="GMemChunk">GMemChunk</link> *mem_chunk);
void        <link linkend="g-mem-chunk-clean">g_mem_chunk_clean</link>               (<link linkend="GMemChunk">GMemChunk</link> *mem_chunk);
void        <link linkend="g-blow-chunks">g_blow_chunks</link>                   (void);

void        <link linkend="g-mem-chunk-info">g_mem_chunk_info</link>                (void);
void        <link linkend="g-mem-chunk-print">g_mem_chunk_print</link>               (<link linkend="GMemChunk">GMemChunk</link> *mem_chunk);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
Memory chunks provide an efficient way to allocate equal-sized pieces of
memory, called atoms. They are used extensively within GLib itself.
For example, the
<link linkend="glib-Doubly-Linked-lists">Doubly Linked Lists</link>
use memory chunks to allocate space for elements of the lists.
</para>
<para>
There are two types of memory chunks, <link linkend="G-ALLOC-ONLY-CAPS">G_ALLOC_ONLY</link>, and <link linkend="G-ALLOC-AND-FREE-CAPS">G_ALLOC_AND_FREE</link>.
<itemizedlist>
<listitem><para>
<link linkend="G-ALLOC-ONLY-CAPS">G_ALLOC_ONLY</link> 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>
<link linkend="G-ALLOC-AND-FREE-CAPS">G_ALLOC_AND_FREE</link> 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 <link linkend="g-mem-chunk-new">g_mem_chunk_new</link>() or the convenience macro
<link linkend="g-mem-chunk-create">g_mem_chunk_create</link>().
</para>
<para>
To allocate a new atom use <link linkend="g-mem-chunk-alloc">g_mem_chunk_alloc</link>(), <link linkend="g-mem-chunk-alloc0">g_mem_chunk_alloc0</link>(),
or the convenience macros <link linkend="g-chunk-new">g_chunk_new</link>() or <link linkend="g-chunk-new0">g_chunk_new0</link>(). 
</para>
<para>
To free an atom use <link linkend="g-mem-chunk-free">g_mem_chunk_free</link>(), or the convenience macro
<link linkend="g-chunk-free">g_chunk_free</link>(). (Atoms can only be freed if the memory chunk is created
with the type set to <link linkend="G-ALLOC-AND-FREE-CAPS">G_ALLOC_AND_FREE</link>.)
</para>
<para>
To free any blocks of memory which are no longer being used, use
<link linkend="g-mem-chunk-clean">g_mem_chunk_clean</link>(). To clean all memory chunks, use <link linkend="g-blow-chunks">g_blow_chunks</link>().
</para>
<para>
To reset the memory chunk, freeing all of the atoms, use <link linkend="g-mem-chunk-reset">g_mem_chunk_reset</link>().
</para>
<para>
To destroy a memory chunk, use <link linkend="g-mem-chunk-destroy">g_mem_chunk_destroy</link>().
</para>
<para>
To help debug memory chunks, use <link linkend="g-mem-chunk-info">g_mem_chunk_info</link>() and <link linkend="g-mem-chunk-print">g_mem_chunk_print</link>().
</para>

<example>
<title>Using a GMemChunk.</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 GMemChunk 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>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GMemChunk">struct GMemChunk</title>
<programlisting>struct GMemChunk;</programlisting>
<para>
The <link linkend="GMemChunk">GMemChunk</link> struct is an opaque data structure representing a memory
chunk. It should be accessed only through the use of the following functions.
</para></refsect2>
<refsect2>
<title><anchor id="G-ALLOC-AND-FREE-CAPS">G_ALLOC_AND_FREE</title>
<programlisting>#define G_ALLOC_AND_FREE  2
</programlisting>
<para>
Specifies the type of a <link linkend="GMemChunk">GMemChunk</link>.
Used in <link linkend="g-mem-chunk-new">g_mem_chunk_new</link>() and <link linkend="g-mem-chunk-create">g_mem_chunk_create</link>() to specify that atoms
will be freed individually.
</para></refsect2>
<refsect2>
<title><anchor id="G-ALLOC-ONLY-CAPS">G_ALLOC_ONLY</title>
<programlisting>#define G_ALLOC_ONLY	  1
</programlisting>
<para>
Specifies the type of a <link linkend="GMemChunk">GMemChunk</link>.
Used in <link linkend="g-mem-chunk-new">g_mem_chunk_new</link>() and <link linkend="g-mem-chunk-create">g_mem_chunk_create</link>() to specify that atoms
will never be freed individually.
</para></refsect2>
<refsect2>
<title><anchor id="g-mem-chunk-new">g_mem_chunk_new ()</title>
<programlisting><link linkend="GMemChunk">GMemChunk</link>*  g_mem_chunk_new                 (const <link linkend="gchar">gchar</link> *name,
                                             <link linkend="gint">gint</link> atom_size,
                                             <link linkend="gulong">gulong</link> area_size,
                                             <link linkend="gint">gint</link> type);</programlisting>
<para>
Creates a new <link linkend="GMemChunk">GMemChunk</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>name</parameter>&nbsp;:</entry>
<entry>a string to identify the <link linkend="GMemChunk">GMemChunk</link>. It is not copied so it
should be valid for the lifetime of the <link linkend="GMemChunk">GMemChunk</link>. It is only used in
<link linkend="g-mem-chunk-print">g_mem_chunk_print</link>(), which is used for debugging.
</entry></row>
<row><entry align="right"><parameter>atom_size</parameter>&nbsp;:</entry>
<entry>the size, in bytes, of each element in the <link linkend="GMemChunk">GMemChunk</link>.
</entry></row>
<row><entry align="right"><parameter>area_size</parameter>&nbsp;:</entry>
<entry>the size, in bytes, of each block of memory allocated to contain
the atoms.
</entry></row>
<row><entry align="right"><parameter>type</parameter>&nbsp;:</entry>
<entry>the type of the <link linkend="GMemChunk">GMemChunk</link>.
<link linkend="G-ALLOC-AND-FREE-CAPS">G_ALLOC_AND_FREE</link> is used if the atoms will be freed individually.
<link linkend="G-ALLOC-ONLY-CAPS">G_ALLOC_ONLY</link> should be used if atoms will never be freed individually.
<link linkend="G-ALLOC-ONLY-CAPS">G_ALLOC_ONLY</link> 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.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GMemChunk">GMemChunk</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-mem-chunk-alloc">g_mem_chunk_alloc ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_mem_chunk_alloc               (<link linkend="GMemChunk">GMemChunk</link> *mem_chunk);</programlisting>
<para>
Allocates an atom of memory from a <link linkend="GMemChunk">GMemChunk</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>