Nagios  4.4.3
Dev docs for Nagios core and neb-module hackers
dkhash.h
Go to the documentation of this file.
1 #ifndef LIBNAGIOS_DKHASH_H_INCLUDED
2 #define LIBNAGIOS_DKHASH_H_INCLUDED
3 #include <errno.h>
4 
5 /**
6  * @file dkhash.h
7  * @brief Dual-key hash functions for Nagios
8  *
9  * Having a dual-key hash function is pretty unusual, but since so
10  * much data in Nagios pertains to services (which are uniquely
11  * identified based on both host_name and service_description), it
12  * makes sense here.
13  *
14  * @{
15  */
16 
17 /** return flags usable from the callback function of dkhash_walk_data() */
18 #define DKHASH_WALK_REMOVE 1 /**< Remove the most recently visited object */
19 #define DKHASH_WALK_STOP 2 /**< Cause walking to stop */
20 
21 /** return values for dkhash_insert() */
22 #define DKHASH_OK 0 /**< Success */
23 #define DKHASH_EDUPE (-EPERM) /**< duplicate insert attempted */
24 #define DKHASH_EPERM (-EPERM) /**< duplicate insert attempted */
25 #define DKHASH_EINVAL (-EINVAL) /**< Invalid parameters passed */
26 #define DKHASH_ENOMEM (-ENOMEM) /**< Memory allocation failed */
27 
28 struct dkhash_table;
29 /** opaque type */
30 typedef struct dkhash_table dkhash_table;
31 
32 /**
33  * Create a dual-keyed hash-table of the given size
34  * Note that it's generally useful to make the table 25-30% larger
35  * than the number of items you intend to store, and also note that
36  * the 'size' arguments gets rounded up to the nearest power of 2.
37  * @param size The desired size of the hash-table.
38  */
39 extern dkhash_table *dkhash_create(unsigned int size);
40 
41 /**
42  * Destroy a dual-keyed hash table
43  * @param t The table to destroy
44  * @return 0 on success, -1 on errors
45  */
46 extern int dkhash_destroy(dkhash_table *t);
47 
48 /**
49  * Fetch the data associated with a particular key
50  * @param t The table to get the data from
51  * @param k1 The first key
52  * @param k2 The second key
53  * @return The data on success, NULL on errors or if data isn't found
54  */
55 extern void *dkhash_get(dkhash_table *t, const char *k1, const char *k2);
56 
57 /**
58  * Insert a new entry into the hash table
59  * @param t The hash table
60  * @param k1 The first key
61  * @param k2 The second key (may be null)
62  * @param data The data to insert
63  * @return 0 on success, < 0 on errors
64  */
65 extern int dkhash_insert(dkhash_table *t, const char *k1, const char *k2, void *data);
66 
67 /**
68  * Remove data from the hash table
69  * Note that this does not free() the pointer to the data stored in the
70  * table. It just destroys containers for that data in the hash table.
71  * @param t The hash table
72  * @param k1 The first key
73  * @param k2 The second key
74  * @return The removed data on success, or NULL on errors
75  */
76 extern void *dkhash_remove(dkhash_table *t, const char *k1, const char *k2);
77 
78 /**
79  * Call a function once for each item in the hash-table
80  * The callback function can return DKHASH_WALK_{REMOVE,STOP} or any
81  * OR'ed combination thereof to control the walking procedure, and
82  * should return 0 on the normal case.
83  * @param t The hash table
84  * @param walker The callback function to send the data to
85  */
86 extern void dkhash_walk_data(dkhash_table *t, int (*walker)(void *data));
87 
88 
89 /**
90  * Get number of collisions in hash table
91  * Many collisions is a sign of a too small hash table or
92  * poor hash-function.
93  * @param t The hash table to report on
94  * @return The total number of collisions (not duplicates) from inserts
95  */
96 extern unsigned int dkhash_collisions(dkhash_table *t);
97 
98 /**
99  * Get number of items in the hash table
100  * @param t The hash table
101  * @return Number of items currently in the hash-table
102  */
103 extern unsigned int dkhash_num_entries(dkhash_table *t);
104 
105 /**
106  * Get max number of items stored in the hash table
107  * @param t The hash table
108  * @return Max number of items stored in hash-table
109  */
110 extern unsigned int dkhash_num_entries_max(dkhash_table *t);
111 
112 /**
113  * Get number of entries added to hash table
114  * Note that some of them may have been removed.
115  * @param t The hash table
116  * @return The number of items added to the table
117  */
118 extern unsigned int dkhash_num_entries_added(dkhash_table *t);
119 
120 /**
121  * Get number of removed items from hash table
122  * @param t The hash table
123  * @return Number of items removed from hash table
124  */
125 extern unsigned int dkhash_num_entries_removed(dkhash_table *t);
126 
127 /**
128  * Get actual table size (in number of buckets)
129  * @param t The hash table
130  * @return Number of bucket-slots in hash table
131  */
132 extern unsigned int dkhash_table_size(dkhash_table *t);
133 /** @} */
134 #endif /* LIBNAGIOS_DKHASH_H_INCLUDED */
dkhash_table
struct dkhash_table dkhash_table
opaque type
Definition: dkhash.h:30
dkhash_num_entries_max
unsigned int dkhash_num_entries_max(dkhash_table *t)
Get max number of items stored in the hash table.
dkhash_num_entries_added
unsigned int dkhash_num_entries_added(dkhash_table *t)
Get number of entries added to hash table Note that some of them may have been removed.
dkhash_destroy
int dkhash_destroy(dkhash_table *t)
Destroy a dual-keyed hash table.
dkhash_walk_data
void dkhash_walk_data(dkhash_table *t, int(*walker)(void *data))
Call a function once for each item in the hash-table The callback function can return DKHASH_WALK_{RE...
dkhash_insert
int dkhash_insert(dkhash_table *t, const char *k1, const char *k2, void *data)
Insert a new entry into the hash table.
dkhash_collisions
unsigned int dkhash_collisions(dkhash_table *t)
Get number of collisions in hash table Many collisions is a sign of a too small hash table or poor ha...
dkhash_remove
void * dkhash_remove(dkhash_table *t, const char *k1, const char *k2)
Remove data from the hash table Note that this does not free() the pointer to the data stored in the ...
dkhash_num_entries_removed
unsigned int dkhash_num_entries_removed(dkhash_table *t)
Get number of removed items from hash table.
dkhash_create
dkhash_table * dkhash_create(unsigned int size)
Create a dual-keyed hash-table of the given size Note that it's generally useful to make the table 25...
dkhash_get
void * dkhash_get(dkhash_table *t, const char *k1, const char *k2)
Fetch the data associated with a particular key.
dkhash_num_entries
unsigned int dkhash_num_entries(dkhash_table *t)
Get number of items in the hash table.
dkhash_table_size
unsigned int dkhash_table_size(dkhash_table *t)
Get actual table size (in number of buckets)