Merge pull request #1545 from mfournier/contributing
[collectd.git] / src / daemon / 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 : */