src/utils_heap.h

   1 /**
   2  * collectd - src/utils_heap.h
   3  * Copyright (C) 2009  Florian octo Forster
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  18  *
  19  * Authors:
  20  *   Florian octo Forster <octo at verplant.org>
  21  **/
  22
  23 #ifndef UTILS_HEAP_H
  24 #define UTILS_HEAP_H 1
  25
  26 struct c_heap_s;
  27 typedef struct c_heap_s c_heap_t;
  28
  29 /*
  30  * NAME
  31  *   c_heap_create
  32  *
  33  * DESCRIPTION
  34  *   Allocates a new heap.
  35  *
  36  * PARAMETERS
  37  *   `compare'  The function-pointer `compare' is used to compare two keys. It
  38  *              has to return less than zero if it's first argument is smaller
  39  *              then the second argument, more than zero if the first argument
  40  *              is bigger than the second argument and zero if they are equal.
  41  *              If your keys are char-pointers, you can use the `strcmp'
  42  *              function from the libc here.
  43  *
  44  * RETURN VALUE
  45  *   A c_heap_t-pointer upon success or NULL upon failure.
  46  */
  47 c_heap_t *c_heap_create (int (*compare) (const void *, const void *));
  48
  49 /*
  50  * NAME
  51  *   c_heap_destroy
  52  *
  53  * DESCRIPTION
  54  *   Deallocates a heap. Stored value- and key-pointer are lost, but of course
  55  *   not freed.
  56  */
  57 void c_heap_destroy (c_heap_t *h);
  58
  59 /*
  60  * NAME
  61  *   c_heap_insert
  62  *
  63  * DESCRIPTION
  64  *   Stores the key-value-pair in the heap pointed to by `h'.
  65  *
  66  * PARAMETERS
  67  *   `h'        Heap to store the data in.
  68  *   `ptr'      Value to be stored. This is typically a pointer to a data
  69  *              structure. The data structure is of course *not* copied and may
  70  *              not be free'd before the pointer has been removed from the heap
  71  *              again.
  72  *
  73  * RETURN VALUE
  74  *   Zero upon success, non-zero otherwise. It's less than zero if an error
  75  *   occurred or greater than zero if the key is already stored in the tree.
  76  */
  77 int c_heap_insert (c_heap_t *h, void *ptr);
  78
  79 /*
  80  * NAME
  81  *   c_heap_get_root
  82  *
  83  * DESCRIPTION
  84  *   Removes the value at the root of the heap and returns both, key and value.
  85  *
  86  * PARAMETERS
  87  *   `h'           Heap to remove key-value-pair from.
  88  *
  89  * RETURN VALUE
  90  *   The pointer passed to `c_heap_insert' or NULL if there are no more
  91  *   elements in the heap (or an error occurred).
  92  */
  93 void *c_heap_get_root (c_heap_t *h);
  94
  95 #endif /* UTILS_HEAP_H */
  96 /* vim: set sw=2 sts=2 et : */