include/heap.h

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