1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1998 Peter Mattis, Spencer Kimball and Josh MacDonald
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 */
17
18 /*
19 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
20 * file for a list of people on the GLib Team. See the ChangeLog
21 * files for a list of changes. These files are distributed with
22 * GLib at ftp://ftp.gtk.org/pub/gtk/.
23 */
24
25 #include "config.h"
26
27 /* we know we are deprecated here, no need for warnings */
28 #ifndef GLIB_DISABLE_DEPRECATION_WARNINGS
29 #define GLIB_DISABLE_DEPRECATION_WARNINGS
30 #endif
31
32 #include "gtrashstack.h"
33
34 /**
35 * SECTION:trash_stack
36 * @title: Trash Stacks
37 * @short_description: maintain a stack of unused allocated memory chunks
38 *
39 * A #GTrashStack is an efficient way to keep a stack of unused allocated
40 * memory chunks. Each memory chunk is required to be large enough to hold
41 * a #gpointer. This allows the stack to be maintained without any space
42 * overhead, since the stack pointers can be stored inside the memory chunks.
43 *
44 * There is no function to create a #GTrashStack. A %NULL #GTrashStack*
45 * is a perfectly valid empty stack.
46 *
47 * There is no longer any good reason to use #GTrashStack. If you have
48 * extra pieces of memory, free() them and allocate them again later.
49 *
50 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
51 */
52
53 /**
54 * GTrashStack:
55 * @next: pointer to the previous element of the stack,
56 * gets stored in the first `sizeof (gpointer)`
57 * bytes of the element
58 *
59 * Each piece of memory that is pushed onto the stack
60 * is cast to a GTrashStack*.
61 *
62 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
63 */
64
65 /**
66 * g_trash_stack_push:
67 * @stack_p: a #GTrashStack
68 * @data_p: (not nullable): the piece of memory to push on the stack
69 *
70 * Pushes a piece of memory onto a #GTrashStack.
71 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
72 */
73 void
g_trash_stack_push(GTrashStack ** stack_p,gpointer data_p)74 g_trash_stack_push (GTrashStack **stack_p,
75 gpointer data_p)
76 {
77 GTrashStack *data = (GTrashStack *) data_p;
78
79 data->next = *stack_p;
80 *stack_p = data;
81 }
82
83 /**
84 * g_trash_stack_pop:
85 * @stack_p: a #GTrashStack
86 *
87 * Pops a piece of memory off a #GTrashStack.
88 *
89 * Returns: the element at the top of the stack
90 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
91 */
92 gpointer
g_trash_stack_pop(GTrashStack ** stack_p)93 g_trash_stack_pop (GTrashStack **stack_p)
94 {
95 GTrashStack *data;
96
97 data = *stack_p;
98 if (data)
99 {
100 *stack_p = data->next;
101 /* NULLify private pointer here, most platforms store NULL as
102 * subsequent 0 bytes
103 */
104 data->next = NULL;
105 }
106
107 return data;
108 }
109
110 /**
111 * g_trash_stack_peek:
112 * @stack_p: a #GTrashStack
113 *
114 * Returns the element at the top of a #GTrashStack
115 * which may be %NULL.
116 *
117 * Returns: the element at the top of the stack
118 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
119 */
120 gpointer
g_trash_stack_peek(GTrashStack ** stack_p)121 g_trash_stack_peek (GTrashStack **stack_p)
122 {
123 GTrashStack *data;
124
125 data = *stack_p;
126
127 return data;
128 }
129
130 /**
131 * g_trash_stack_height:
132 * @stack_p: a #GTrashStack
133 *
134 * Returns the height of a #GTrashStack.
135 *
136 * Note that execution of this function is of O(N) complexity
137 * where N denotes the number of items on the stack.
138 *
139 * Returns: the height of the stack
140 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
141 */
142 guint
g_trash_stack_height(GTrashStack ** stack_p)143 g_trash_stack_height (GTrashStack **stack_p)
144 {
145 GTrashStack *data;
146 guint i = 0;
147
148 for (data = *stack_p; data; data = data->next)
149 i++;
150
151 return i;
152 }
153