docs/reference/glib/tmpl/trash_stack.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Trash Stacks
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 maintain a stack of unused allocated memory chunks.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GTrashStack is an efficient way to keep a stack of unused allocated
  10 memory chunks. Each memory chunk is required to be large enough to hold
  11 a #gpointer. This allows the stack to be maintained without any space
  12 overhead, since the stack pointers can be stored inside the memory chunks.
  13 </para>
  14 <para>
  15 There is no function to create a #GTrashStack. A %NULL #GTrashStack*
  16 is a perfectly valid empty stack.
  17 </para>
  18
  19 <!-- ##### SECTION See_Also ##### -->
  20 <para>
  21
  22 </para>
  23
  24 <!-- ##### STRUCT GTrashStack ##### -->
  25 <para>
  26 Each piece of memory that is pushed onto the stack
  27 is cast to a <structname>GTrashStack*</structname>.
  28 </para>
  29
  30 @next: pointer to the previous element of the stack,
  31 gets stored in the first <literal>sizeof (gpointer)</literal>
  32 bytes of the element.
  33
  34 <!-- ##### FUNCTION g_trash_stack_push ##### -->
  35 <para>
  36 Pushes a piece of memory onto a #GTrashStack.
  37 </para>
  38
  39 @stack_p: a pointer to a #GTrashStack.
  40 @data_p: the piece of memory to push on the stack.
  41
  42
  43 <!-- ##### FUNCTION g_trash_stack_pop ##### -->
  44 <para>
  45 Pops a piece of memory off a #GTrashStack.
  46 </para>
  47
  48 @stack_p: a pointer to a #GTrashStack.
  49 @Returns: the element at the top of the stack.
  50
  51
  52 <!-- ##### FUNCTION g_trash_stack_peek ##### -->
  53 <para>
  54 Returns the element at the top of a #GTrashStack.
  55 </para>
  56
  57 @stack_p: a pointer to a #GTrashStack.
  58 @Returns: the element at the top of the stack.
  59
  60
  61 <!-- ##### FUNCTION g_trash_stack_height ##### -->
  62 <para>
  63 Returns the height of a #GTrashStack.
  64 </para>
  65
  66 @stack_p: a pointer to a #GTrashStack.
  67 @Returns: the height of the stack.
  68
  69