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 |
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 |
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 |
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 |
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 | |