1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1998 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * SPDX-License-Identifier: LGPL-2.1-or-later
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
21 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
22 * file for a list of people on the GLib Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GLib at ftp://ftp.gtk.org/pub/gtk/.
29 /* we know we are deprecated here, no need for warnings */
30 #ifndef GLIB_DISABLE_DEPRECATION_WARNINGS
31 #define GLIB_DISABLE_DEPRECATION_WARNINGS
34 #include "gtrashstack.h"
38 * @title: Trash Stacks
39 * @short_description: maintain a stack of unused allocated memory chunks
41 * A #GTrashStack is an efficient way to keep a stack of unused allocated
42 * memory chunks. Each memory chunk is required to be large enough to hold
43 * a #gpointer. This allows the stack to be maintained without any space
44 * overhead, since the stack pointers can be stored inside the memory chunks.
46 * There is no function to create a #GTrashStack. A %NULL #GTrashStack*
47 * is a perfectly valid empty stack.
49 * There is no longer any good reason to use #GTrashStack. If you have
50 * extra pieces of memory, free() them and allocate them again later.
52 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
57 * @next: pointer to the previous element of the stack,
58 * gets stored in the first `sizeof (gpointer)`
59 * bytes of the element
61 * Each piece of memory that is pushed onto the stack
62 * is cast to a GTrashStack*.
64 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
69 * @stack_p: a #GTrashStack
70 * @data_p: (not nullable): the piece of memory to push on the stack
72 * Pushes a piece of memory onto a #GTrashStack.
73 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
76 g_trash_stack_push (GTrashStack **stack_p,
79 GTrashStack *data = (GTrashStack *) data_p;
81 data->next = *stack_p;
87 * @stack_p: a #GTrashStack
89 * Pops a piece of memory off a #GTrashStack.
91 * Returns: the element at the top of the stack
92 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
95 g_trash_stack_pop (GTrashStack **stack_p)
102 *stack_p = data->next;
103 /* NULLify private pointer here, most platforms store NULL as
113 * g_trash_stack_peek:
114 * @stack_p: a #GTrashStack
116 * Returns the element at the top of a #GTrashStack
117 * which may be %NULL.
119 * Returns: the element at the top of the stack
120 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
123 g_trash_stack_peek (GTrashStack **stack_p)
133 * g_trash_stack_height:
134 * @stack_p: a #GTrashStack
136 * Returns the height of a #GTrashStack.
138 * Note that execution of this function is of O(N) complexity
139 * where N denotes the number of items on the stack.
141 * Returns: the height of the stack
142 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
145 g_trash_stack_height (GTrashStack **stack_p)
150 for (data = *stack_p; data; data = data->next)