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 <!-- ##### SECTION Stability_Level ##### -->
  25
  26
  27 <!-- ##### STRUCT GTrashStack ##### -->
  28 <para>
  29 Each piece of memory that is pushed onto the stack
  30 is cast to a <structname>GTrashStack*</structname>.
  31 </para>
  32
  33 @next: pointer to the previous element of the stack,
  34 gets stored in the first <literal>sizeof (gpointer)</literal>
  35 bytes of the element.
  36
  37 <!-- ##### FUNCTION g_trash_stack_push ##### -->
  38 <para>
  39 Pushes a piece of memory onto a #GTrashStack.
  40 </para>
  41
  42 @stack_p: a pointer to a #GTrashStack.
  43 @data_p: the piece of memory to push on the stack.
  44
  45
  46 <!-- ##### FUNCTION g_trash_stack_pop ##### -->
  47 <para>
  48 Pops a piece of memory off a #GTrashStack.
  49 </para>
  50
  51 @stack_p: a pointer to a #GTrashStack.
  52 @Returns: the element at the top of the stack.
  53
  54
  55 <!-- ##### FUNCTION g_trash_stack_peek ##### -->
  56 <para>
  57 Returns the element at the top of a #GTrashStack.
  58 </para>
  59
  60 @stack_p: a pointer to a #GTrashStack.
  61 @Returns: the element at the top of the stack.
  62
  63
  64 <!-- ##### FUNCTION g_trash_stack_height ##### -->
  65 <para>
  66 Returns the height of a #GTrashStack.
  67 </para>
  68
  69 @stack_p: a pointer to a #GTrashStack.
  70 @Returns: the height of the stack.
  71
  72