1  /* GLIB - Library of useful routines for C programming
       2   * Copyright (C) 1995-1998  Peter Mattis, Spencer Kimball and Josh MacDonald
       3   *
       4   * SPDX-License-Identifier: LGPL-2.1-or-later
       5   *
       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.
      10   *
      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.
      15   *
      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/>.
      18   */
      19  
      20  /*
      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/. 
      25   */
      26  
      27  #include "config.h"
      28  
      29  /* we know we are deprecated here, no need for warnings */
      30  #ifndef GLIB_DISABLE_DEPRECATION_WARNINGS
      31  #define GLIB_DISABLE_DEPRECATION_WARNINGS
      32  #endif
      33  
      34  #include "gtrashstack.h"
      35  
      36  /**
      37   * GTrashStack:
      38   * @next: pointer to the previous element of the stack,
      39   *     gets stored in the first `sizeof (gpointer)`
      40   *     bytes of the element
      41   *
      42   * A `GTrashStack` is an efficient way to keep a stack of unused allocated
      43   * memory chunks. Each memory chunk is required to be large enough to hold
      44   * a `gpointer`. This allows the stack to be maintained without any space
      45   * overhead, since the stack pointers can be stored inside the memory chunks.
      46   *
      47   * There is no function to create a `GTrashStack`. A `NULL` `GTrashStack*`
      48   * is a perfectly valid empty stack.
      49   *
      50   * Each piece of memory that is pushed onto the stack is cast to a
      51   * `GTrashStack*`.
      52   *
      53   * There is no longer any good reason to use `GTrashStack`.  If you have
      54   * extra pieces of memory, `free()` them and allocate them again later.
      55   *
      56   * Deprecated: 2.48: `GTrashStack` is deprecated without replacement
      57   */
      58  
      59  /**
      60   * g_trash_stack_push:
      61   * @stack_p: a #GTrashStack
      62   * @data_p: (not nullable): the piece of memory to push on the stack
      63   *
      64   * Pushes a piece of memory onto a #GTrashStack.
      65   * Deprecated: 2.48: #GTrashStack is deprecated without replacement
      66   */
      67  void
      68  g_trash_stack_push (GTrashStack **stack_p,
      69                      gpointer      data_p)
      70  {
      71    GTrashStack *data = (GTrashStack *) data_p;
      72  
      73    data->next = *stack_p;
      74    *stack_p = data;
      75  }
      76  
      77  /**
      78   * g_trash_stack_pop:
      79   * @stack_p: a #GTrashStack
      80   *
      81   * Pops a piece of memory off a #GTrashStack.
      82   *
      83   * Returns: the element at the top of the stack
      84   * Deprecated: 2.48: #GTrashStack is deprecated without replacement
      85   */
      86  gpointer
      87  g_trash_stack_pop (GTrashStack **stack_p)
      88  {
      89    GTrashStack *data;
      90  
      91    data = *stack_p;
      92    if (data)
      93      {
      94        *stack_p = data->next;
      95        /* NULLify private pointer here, most platforms store NULL as
      96         * subsequent 0 bytes
      97         */
      98        data->next = NULL;
      99      }
     100  
     101    return data;
     102  }
     103  
     104  /**
     105   * g_trash_stack_peek:
     106   * @stack_p: a #GTrashStack
     107   *
     108   * Returns the element at the top of a #GTrashStack
     109   * which may be %NULL.
     110   *
     111   * Returns: the element at the top of the stack
     112   * Deprecated: 2.48: #GTrashStack is deprecated without replacement
     113   */
     114  gpointer
     115  g_trash_stack_peek (GTrashStack **stack_p)
     116  {
     117    GTrashStack *data;
     118  
     119    data = *stack_p;
     120  
     121    return data;
     122  }
     123  
     124  /**
     125   * g_trash_stack_height:
     126   * @stack_p: a #GTrashStack
     127   *
     128   * Returns the height of a #GTrashStack.
     129   *
     130   * Note that execution of this function is of O(N) complexity
     131   * where N denotes the number of items on the stack.
     132   *
     133   * Returns: the height of the stack
     134   * Deprecated: 2.48: #GTrashStack is deprecated without replacement
     135   */
     136  guint
     137  g_trash_stack_height (GTrashStack **stack_p)
     138  {
     139    GTrashStack *data;
     140    guint i = 0;
     141  
     142    for (data = *stack_p; data; data = data->next)
     143      i++;
     144  
     145    return i;
     146  }