Bump version to 4.9.5; Update ChangeLog.
[collectd.git] / 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 : */