include/heap.h

   1 /*
   2  * $Id: heap.h,v 1.3 2001/01/12 00:37:12 wessels Exp $
   3  *
   4  * AUTHOR: John Dilley, Hewlett Packard
   5  *
   6  * SQUID Web Proxy Cache          http://www.squid-cache.org/
   7  * ----------------------------------------------------------
   8  *
   9  *  Squid is the result of efforts by numerous individuals from
  10  *  the Internet community; see the CONTRIBUTORS file for full
  11  *  details.   Many organizations have provided support for Squid's
  12  *  development; see the SPONSORS file for full details.  Squid is
  13  *  Copyrighted (C) 2001 by the Regents of the University of
  14  *  California; see the COPYRIGHT file for full details.  Squid
  15  *  incorporates software developed and/or copyrighted by other
  16  *  sources; see the CREDITS file for full details.
  17  *
  18  *  This program is free software; you can redistribute it and/or modify
  19  *  it under the terms of the GNU General Public License as published by
  20  *  the Free Software Foundation; either version 2 of the License, or
  21  *  (at your option) any later version.
  22  *
  23  *  This program is distributed in the hope that it will be useful,
  24  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  25  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  26  *  GNU General Public License for more details.
  27  *
  28  *  You should have received a copy of the GNU General Public License
  29  *  along with this program; if not, write to the Free Software
  30  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  31  *
  32  */
  33
  34 /****************************************************************************
  35  * Copyright (C) 1999 by Hewlett Packard
  36  *
  37  * Heap data structure.  Used to store objects for cache replacement.  The
  38  * heap is implemented as a contiguous array in memory.  Heap sort and heap
  39  * update are done in-place.  The heap is ordered with the smallest value at
  40  * the top of the heap (as in the smallest object key value).  Child nodes
  41  * are larger than their parent.
  42  ****************************************************************************/
  43
  44 #ifndef _heap_h_INCLUDED
  45 #define _heap_h_INCLUDED
  46
  47 /*
  48  * Function for generating heap keys.  The first argument will typically be
  49  * a dws_md_p passed in as a void *.  Should find a way to get type safety
  50  * without having heap know all about metadata objects...  The second arg is
  51  * the current aging factor for the heap.
  52  */
  53 typedef unsigned long heap_mutex_t;
  54 typedef void *heap_t;
  55 typedef double heap_key;
  56 typedef heap_key heap_key_func(heap_t, heap_key);
  57
  58
  59 /*
  60  * Heap node.  Has a key value generated by a key_func, id (array index) so
  61  * it can be quickly found in its heap, and a pointer to a data object that
  62  * key_func can generate a key from.
  63  */
  64 typedef struct _heap_node {
  65     heap_key key;
  66     unsigned long id;
  67     heap_t data;
  68 } heap_node;
  69
  70
  71 /*
  72  * Heap object.  Holds an array of heap_node objects along with a heap size
  73  * (array length), the index of the last heap element, and a key generation
  74  * function.  Also stores aging factor for this heap.
  75  */
  76 typedef struct _heap {
  77     heap_mutex_t lock;
  78     unsigned long size;
  79     unsigned long last;
  80     heap_key_func *gen_key;     /* key generator for heap */
  81     heap_key age;               /* aging factor for heap */
  82     heap_node **nodes;
  83 } heap;
  84
  85 /****************************************************************************
  86  * Public functions
  87  ****************************************************************************/
  88
  89 /*
  90  * Create and initialize a new heap.
  91  */
  92 extern heap *new_heap(int init_size, heap_key_func gen_key);
  93
  94 /*
  95  * Delete a heap and clean up its memory.  Does not delete what the heap
  96  * nodes are pointing to!
  97  */
  98 extern void delete_heap(heap *);
  99
 100 /*
 101  * Insert a new node into a heap, returning a pointer to it.  The heap_node
 102  * object returned is used to update or delete a heap object.  Nothing else
 103  * should be done with this data structure (especially modifying it!)  The
 104  * heap does not assume ownership of the data passed to it.
 105  */
 106 extern heap_node *heap_insert(heap *, heap_t dat);
 107
 108 /*
 109  * Delete a node out of a heap.  Returns the heap data from the deleted
 110  * node.  The caller is responsible for freeing this data.
 111  */
 112 extern heap_t heap_delete(heap *, heap_node * elm);
 113
 114 /*
 115  * The semantics of this routine is the same as the followings:
 116  *        heap_delete(hp, elm);
 117  *        heap_insert(hp, dat);
 118  * Returns the old data object from elm (the one being replaced).  The
 119  * caller must free this as necessary.
 120  */
 121 extern heap_t heap_update(heap *, heap_node * elm, heap_t dat);
 122
 123 /*
 124  * Generate a heap key for a given data object.  Alternative macro form:
 125  */
 126 #ifdef  MACRO_DEBUG
 127 extern heap_key heap_gen_key(heap * hp, heap_t dat);
 128 #else
 129 #define heap_gen_key(hp,md)     ((hp)->gen_key((md),(hp)->age))
 130 #endif /* MACRO_DEBUG */
 131
 132
 133 /*
 134  * Extract the minimum (root) element and maintain the heap property.
 135  * Returns the data pointed to by the root node, which the caller must
 136  * free as necessary.
 137  */
 138 extern heap_t heap_extractmin(heap *);
 139
 140 /*
 141  * Extract the last leaf node (does not change the heap property).
 142  * Returns the data that had been in the heap which the caller must free if
 143  * necessary.  Note that the last node is guaranteed to be less than its
 144  * parent, but may not be less than any of the other (leaf or parent) notes
 145  * in the tree.  This operation is fast but imprecise.
 146  */
 147 extern heap_t heap_extractlast(heap * hp);
 148
 149 /*
 150  * Get the root key, the nth key, the root (smallest) element, or the nth
 151  * element.  None of these operations modify the heap.
 152  */
 153 extern heap_key heap_peepminkey(heap *);
 154 extern heap_key heap_peepkey(heap *, int n);
 155
 156 extern heap_t heap_peepmin(heap *);
 157 extern heap_t heap_peep(heap *, int n);
 158
 159 /*
 160  * Is the heap empty?  How many nodes (data objects) are in it?
 161  */
 162 #ifdef  MACRO_DEBUG
 163 extern int heap_empty(heap *);
 164 extern int heap_nodes(heap *);
 165 #else /* MACRO_DEBUG */
 166 #define heap_nodes(heap)        ((heap)->last)
 167 #define heap_empty(heap)        (((heap)->last <= 0) ? 1 : 0)
 168 #endif /* MACRO_DEBUG */
 169
 170 /*
 171  * Print the heap or a node in the heap.
 172  */
 173 extern void heap_print(heap *);
 174 extern void heap_printnode(char *msg, heap_node * elm);
 175
 176 extern int verify_heap_property(heap *);
 177
 178 #endif /* _heap_h_INCLUDED */