<refentry id="glib-Trash-Stacks">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Trash-Stacks.top_of_page">Trash Stacks</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Trash Stacks</refname>
<refpurpose>maintain a stack of unused allocated memory chunks</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Trash-Stacks.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <link linkend="GTrashStack">GTrashStack</link>;
<link linkend="void">void</link>                <link linkend="g-trash-stack-push">g_trash_stack_push</link>                  (<link linkend="GTrashStack">GTrashStack</link> **stack_p,
                                                         <link linkend="gpointer">gpointer</link> data_p);
<link linkend="gpointer">gpointer</link>            <link linkend="g-trash-stack-pop">g_trash_stack_pop</link>                   (<link linkend="GTrashStack">GTrashStack</link> **stack_p);
<link linkend="gpointer">gpointer</link>            <link linkend="g-trash-stack-peek">g_trash_stack_peek</link>                  (<link linkend="GTrashStack">GTrashStack</link> **stack_p);
<link linkend="guint">guint</link>               <link linkend="g-trash-stack-height">g_trash_stack_height</link>                (<link linkend="GTrashStack">GTrashStack</link> **stack_p);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Trash-Stacks.description" role="desc">
<title role="desc.title">Description</title>
<para>
A <link linkend="GTrashStack"><type>GTrashStack</type></link> is an efficient way to keep a stack of unused allocated
memory chunks. Each memory chunk is required to be large enough to hold
a <link linkend="gpointer"><type>gpointer</type></link>. This allows the stack to be maintained without any space
overhead, since the stack pointers can be stored inside the memory chunks.
</para>
<para>
There is no function to create a <link linkend="GTrashStack"><type>GTrashStack</type></link>. A <link linkend="NULL--CAPS"><literal>NULL</literal></link> <link linkend="GTrashStack"><type>GTrashStack</type></link>*
is a perfectly valid empty stack.
</para>
</refsect1>

<refsect1 id="glib-Trash-Stacks.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GTrashStack" role="struct">
<title>GTrashStack</title>
<indexterm zone="GTrashStack"><primary sortas="TrashStack">GTrashStack</primary></indexterm><programlisting>typedef struct {
  GTrashStack *next;
} GTrashStack;
</programlisting>
<para>
Each piece of memory that is pushed onto the stack
is cast to a <structname>GTrashStack*</structname>.
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="GTrashStack">GTrashStack</link>&#160;*<structfield>next</structfield>;</term>
<listitem><simpara>pointer to the previous element of the stack,
gets stored in the first <literal>sizeof (gpointer)</literal>
bytes of the element.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-trash-stack-push" role="function">
<title>g_trash_stack_push ()</title>
<indexterm zone="g-trash-stack-push"><primary sortas="trash_stack_push">g_trash_stack_push</primary></indexterm><programlisting><link linkend="void">void</link>                g_trash_stack_push                  (<link linkend="GTrashStack">GTrashStack</link> **stack_p,
                                                         <link linkend="gpointer">gpointer</link> data_p);</programlisting>
<para>
Pushes a piece of memory onto a <link linkend="GTrashStack"><type>GTrashStack</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>stack_p</parameter>&#160;:</term>
<listitem><simpara>a pointer to a <link linkend="GTrashStack"><type>GTrashStack</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data_p</parameter>&#160;:</term>
<listitem><simpara>the piece of memory to push on the stack.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-trash-stack-pop" role="function">
<title>g_trash_stack_pop ()</title>
<indexterm zone="g-trash-stack-pop"><primary sortas="trash_stack_pop">g_trash_stack_pop</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_trash_stack_pop                   (<link linkend="GTrashStack">GTrashStack</link> **stack_p);</programlisting>
<para>
Pops a piece of memory off a <link linkend="GTrashStack"><type>GTrashStack</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>stack_p</parameter>&#160;:</term>
<listitem><simpara>a pointer to a <link linkend="GTrashStack"><type>GTrashStack</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the element at the top of the stack.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-trash-stack-peek" role="function">
<title>g_trash_stack_peek ()</title>
<indexterm zone="g-trash-stack-peek"><primary sortas="trash_stack_peek">g_trash_stack_peek</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_trash_stack_peek                  (<link linkend="GTrashStack">GTrashStack</link> **stack_p);</programlisting>
<para>
Returns the element at the top of a <link linkend="GTrashStack"><type>GTrashStack</type></link> which may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>stack_p</parameter>&#160;:</term>
<listitem><simpara>a pointer to a <link linkend="GTrashStack"><type>GTrashStack</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the element at the top of the stack.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-trash-stack-height" role="function">
<title>g_trash_stack_height ()</title>
<indexterm zone="g-trash-stack-height"><primary sortas="trash_stack_height">g_trash_stack_height</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_trash_stack_height                (<link linkend="GTrashStack">GTrashStack</link> **stack_p);</programlisting>
<para>
Returns the height of a <link linkend="GTrashStack"><type>GTrashStack</type></link>.
Note that execution of this function is of O(N) complexity
where N denotes the number of items on the stack.
</para><variablelist role="params">
<varlistentry><term><parameter>stack_p</parameter>&#160;:</term>
<listitem><simpara>a pointer to a <link linkend="GTrashStack"><type>GTrashStack</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the height of the stack.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
