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 which may be %NULL. 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 Note that execution of this function is of O(N) complexity 68 where N denotes the number of items on the stack. 69 </para> 70 71 @stack_p: a pointer to a #GTrashStack. 72 @Returns: the height of the stack. 73 74 75
