memory.sgml

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

<refsect2>
<title><anchor id="g-alloca">g_alloca()</title>
<programlisting>#define     g_alloca(size)</programlisting>
<para>
Allocates <parameter>size</parameter> bytes on the stack; these bytes will be freed when the current
stack frame is cleaned up. This macro essentially just wraps the 
<function><link linkend="alloca">alloca</link>()</function> function present on most UNIX variants. 
Thus it provides the same advantages and pitfalls as <function><link linkend="alloca">alloca</link>()</function>:
<msgtext><variablelist>
  <varlistentry><term></term><listitem><para>
    + <function><link linkend="alloca">alloca</link>()</function> is very fast, as on most systems it's implemented by just adjusting
    the stack pointer register.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
    + It doesn't cause any memory fragmentation, within its scope, separate <function><link linkend="alloca">alloca</link>()</function>
    blocks just build up and are released together at function end.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
    - Allocation sizes have to fit into the current stack frame. For instance in a
      threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
      so be sparse with <function><link linkend="alloca">alloca</link>()</function> uses.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
    - Allocation failure due to insufficient stack space is not indicated with a <literal>NULL</literal>
      return like e.g. with <function><link linkend="malloc">malloc</link>()</function>. Instead, most systems probably handle it the same
      way as out of stack space situations from infinite function recursion, i.e.
      with a segmentation fault.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
    - Special care has to be taken when mixing <function><link linkend="alloca">alloca</link>()</function> with GNU C variable sized arrays.
      Stack space allocated with <function><link linkend="alloca">alloca</link>()</function> in the same scope as a variable sized array
      will be freed together with the variable sized array upon exit of that scope, and
      not upon exit of the enclosing function scope.
  </para></listitem></varlistentry>
</variablelist></msgtext>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>size</parameter>&nbsp;:</entry>
<entry>   number of bytes to allocate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>space for <parameter>size</parameter> bytes, allocated on the stack


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-newa">g_newa()</title>
<programlisting>#define     g_newa(struct_type, n_structs)</programlisting>
<para>
Wraps <link linkend="g-alloca">g_alloca</link>() in a more typesafe manner.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>struct_type</parameter>&nbsp;:</entry>
<entry>Type of memory chunks to be allocated
</entry></row>
<row><entry align="right"><parameter>n_structs</parameter>&nbsp;:</entry>
<entry>  Number of chunks to be allocated
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>    Pointer to stack space for <parameter>n_structs</parameter> chunks of type <parameter>struct_type</parameter>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-memmove">g_memmove()</title>
<programlisting>#define     g_memmove(d,s,n)</programlisting>
<para>
Copies a block of memory <parameter>n</parameter> bytes long, from <parameter>s</parameter> to <parameter>d</parameter>.
The source and destination areas may overlap.
</para>
<para>
In order to use this function, you must include <filename>string.h</filename>
yourself, because this macro will typically simply resolve
to <function><link linkend="memmove">memmove</link>()</function> and GLib does not include <filename>string.h</filename> for you.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>d</parameter>&nbsp;:</entry>
<entry>the destination address to copy the bytes to.
</entry></row>
<row><entry align="right"><parameter>s</parameter>&nbsp;:</entry>
<entry>the source address to copy the bytes from.
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry>the number of bytes to copy.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-memdup">g_memdup ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_memdup                        (<link linkend="gconstpointer">gconstpointer</link> mem,
                                             <link linkend="guint">guint</link> byte_size);</programlisting>
<para>
Allocates <parameter>byte_size</parameter> bytes of memory, and copies <parameter>byte_size</parameter> bytes into it
from <parameter>mem</parameter>. If <parameter>mem</parameter> is <literal>NULL</literal> it returns <literal>NULL</literal>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mem</parameter>&nbsp;:</entry>
<entry>the memory to copy.
</entry></row>
<row><entry align="right"><parameter>byte_size</parameter>&nbsp;:</entry>
<entry>the number of bytes to copy.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to the newly-allocated copy of the memory, or <literal>NULL</literal> if <parameter>mem</parameter>
is <literal>NULL</literal>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GMemVTable">struct GMemVTable</title>
<programlisting>struct GMemVTable
{
  gpointer (*malloc)      (gsize    n_bytes);
  gpointer (*realloc)     (gpointer mem,
			   gsize    n_bytes);
  void     (*free)        (gpointer mem);
  /* optional */
  gpointer (*calloc)      (gsize    n_blocks,
			   gsize    n_block_bytes);
  gpointer (*try_malloc)  (gsize    n_bytes);
  gpointer (*try_realloc) (gpointer mem,
			   gsize    n_bytes);
};
</programlisting>
<para>
A set of functions used to perform memory allocation. The same <link linkend="GMemVTable">GMemVTable</link> must
be used for all allocations in the same program; a call to <link linkend="g-mem-set-vtable">g_mem_set_vtable</link>(),
if it exists, should be prior to any use of GLib.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="gpointer">gpointer</link> (*<structfield>malloc</structfield>) (gsize    n_bytes)</entry>
<entry>function to use for allocating memory.
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> (*<structfield>realloc</structfield>) (gpointer mem,
			   gsize    n_bytes)</entry>
<entry>function to use for reallocating memory.
</entry>
</row>
<row>
<entry>void (*<structfield>free</structfield>) (gpointer mem)</entry>
<entry>function to use to free memory.
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> (*<structfield>calloc</structfield>) (gsize    n_blocks,
			   gsize    n_block_bytes)</entry>
<entry>function to use for allocating zero-filled memory.
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> (*<structfield>try_malloc</structfield>) (gsize    n_bytes)</entry>
<entry>function to use for allocating memory without a default error handler.
</entry>
</row>
<row>
<entry><link linkend="gpointer">gpointer</link> (*<structfield>try_realloc</structfield>) (gpointer mem,
			   gsize    n_bytes)</entry>
<entry>function to use for reallocating memory without a default error handler.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-mem-set-vtable">g_mem_set_vtable ()</title>
<programlisting>void        g_mem_set_vtable                (<link linkend="GMemVTable">GMemVTable</link> *vtable);</programlisting>
<para>
Sets the <link linkend="GMemVTable">GMemVTable</link> to use for memory allocation. You can use this to provide
custom memory allocation routines. <emphasis>This function must be called before using any other GLib functions.</emphasis> The <parameter>vtable</parameter> only needs to provide <function><link linkend="malloc">malloc</link>()</function>, <function><link linkend="realloc">realloc</link>()</function>, and <function><link linkend="free">free</link>()</function>
functions; GLib can provide default implementations of the others.  The <function><link linkend="malloc">malloc</link>()</function>
and <function><link linkend="realloc">realloc</link>()</function> implementations should return <literal>NULL</literal> on failure, GLib will handle
error-checking for you. <parameter>vtable</parameter> is copied, so need not persist after this 
function has been called.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>vtable</parameter>&nbsp;:</entry>
<entry>table of memory allocation routines.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-mem-is-system-malloc">g_mem_is_system_malloc ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_mem_is_system_malloc          (void);</programlisting>
<para>
Checks whether the allocator used by <link linkend="g-malloc">g_malloc</link>() is the system's
malloc implementation. If it returns <literal>TRUE</literal> memory allocated with
<function><link linkend="malloc">malloc</link>()</function> can be used interchangeable with 
memory allocated using <link linkend="g-malloc">g_malloc</link>(). This function is useful for 
avoiding an extra copy of allocated memory returned by a 
non-GLib-based API.
</para>
<para>
A different allocator can be set using <link linkend="g-mem-set-vtable">g_mem_set_vtable</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> if <literal>TRUE</literal>, <function><link linkend="malloc">malloc</link>()</function> and <link linkend="g-malloc">g_malloc</link>() can be mixed.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="glib-mem-profiler-table">glib_mem_profiler_table</title>
<programlisting>extern GMemVTable	*glib_mem_profiler_table;
</programlisting>
<para>
A <link linkend="GMemVTable">GMemVTable</link> containing profiling variants of the memory
allocation functions. Use them together with <link linkend="g-mem-profile">g_mem_profile</link>()
in order to get information about the memory allocation pattern
of your program.
</para></refsect2>
<refsect2>
<title><anchor id="g-mem-profile">g_mem_profile ()</title>
<programlisting>void        g_mem_profile                   (void);</programlisting>
<para>
Outputs a summary of memory usage.
</para>
<para>
It outputs the frequency of allocations of different sizes,
the total number of bytes which have been allocated,
the total number of bytes which have been freed,
and the difference between the previous two values, i.e. the number of bytes
still in use.
</para>
<para>
Note that this function will not output anything unless you have
previously installed the <link linkend="glib-mem-profiler-table">glib_mem_profiler_table</link> with <link linkend="g-mem-set-vtable">g_mem_set_vtable</link>().
</para></refsect2>

</refsect1>




</refentry>