src/utils_heap.h

   1 /**
   2  * collectd - src/utils_heap.h
   3  * Copyright (C) 2009       Florian octo Forster
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining a
   6  * copy of this software and associated documentation files (the "Software"),
   7  * to deal in the Software without restriction, including without limitation
   8  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   9  * and/or sell copies of the Software, and to permit persons to whom the
  10  * Software is furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be included in
  13  * all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  21  * DEALINGS IN THE SOFTWARE.
  22  *
  23  * Authors:
  24  *   Florian octo Forster <octo at collectd.org>
  25  **/
  26
  27 #ifndef UTILS_HEAP_H
  28 #define UTILS_HEAP_H 1
  29
  30 struct c_heap_s;
  31 typedef struct c_heap_s c_heap_t;
  32
  33 /*
  34  * NAME
  35  *   c_heap_create
  36  *
  37  * DESCRIPTION
  38  *   Allocates a new heap.
  39  *
  40  * PARAMETERS
  41  *   `compare'  The function-pointer `compare' is used to compare two keys. It
  42  *              has to return less than zero if it's first argument is smaller
  43  *              then the second argument, more than zero if the first argument
  44  *              is bigger than the second argument and zero if they are equal.
  45  *              If your keys are char-pointers, you can use the `strcmp'
  46  *              function from the libc here.
  47  *
  48  * RETURN VALUE
  49  *   A c_heap_t-pointer upon success or NULL upon failure.
  50  */
  51 c_heap_t *c_heap_create (int (*compare) (const void *, const void *));
  52
  53 /*
  54  * NAME
  55  *   c_heap_destroy
  56  *
  57  * DESCRIPTION
  58  *   Deallocates a heap. Stored value- and key-pointer are lost, but of course
  59  *   not freed.
  60  */
  61 void c_heap_destroy (c_heap_t *h);
  62
  63 /*
  64  * NAME
  65  *   c_heap_insert
  66  *
  67  * DESCRIPTION
  68  *   Stores the key-value-pair in the heap pointed to by `h'.
  69  *
  70  * PARAMETERS
  71  *   `h'        Heap to store the data in.
  72  *   `ptr'      Value to be stored. This is typically a pointer to a data
  73  *              structure. The data structure is of course *not* copied and may
  74  *              not be free'd before the pointer has been removed from the heap
  75  *              again.
  76  *
  77  * RETURN VALUE
  78  *   Zero upon success, non-zero otherwise. It's less than zero if an error
  79  *   occurred or greater than zero if the key is already stored in the tree.
  80  */
  81 int c_heap_insert (c_heap_t *h, void *ptr);
  82
  83 /*
  84  * NAME
  85  *   c_heap_get_root
  86  *
  87  * DESCRIPTION
  88  *   Removes the value at the root of the heap and returns both, key and value.
  89  *
  90  * PARAMETERS
  91  *   `h'           Heap to remove key-value-pair from.
  92  *
  93  * RETURN VALUE
  94  *   The pointer passed to `c_heap_insert' or NULL if there are no more
  95  *   elements in the heap (or an error occurred).
  96  */
  97 void *c_heap_get_root (c_heap_t *h);
  98
  99 #endif /* UTILS_HEAP_H */
 100 /* vim: set sw=2 sts=2 et : */