Nagios 4.5.4
Dev docs for Nagios core and neb-module hackers
Loading...
Searching...
No Matches
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
28struct dkhash_table;
29/** opaque type */
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 */
39extern 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 */
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 */
55extern 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 */
65extern 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 */
76extern 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 */
86extern 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 */
96extern 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 */
103extern 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 */
110extern 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 */
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 */
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 */
132extern unsigned int dkhash_table_size(dkhash_table *t);
133/** @} */
134#endif /* LIBNAGIOS_DKHASH_H_INCLUDED */
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 ...
int dkhash_insert(dkhash_table *t, const char *k1, const char *k2, void *data)
Insert a new entry into the hash table.
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...
struct dkhash_table dkhash_table
opaque type
Definition dkhash.h:30
unsigned int dkhash_num_entries_removed(dkhash_table *t)
Get number of removed items from hash table.
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...
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...
unsigned int dkhash_num_entries(dkhash_table *t)
Get number of items in the hash table.
unsigned int dkhash_num_entries_max(dkhash_table *t)
Get max number of items stored in the hash table.
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.
int dkhash_destroy(dkhash_table *t)
Destroy a dual-keyed hash table.
unsigned int dkhash_table_size(dkhash_table *t)
Get actual table size (in number of buckets)
void * dkhash_get(dkhash_table *t, const char *k1, const char *k2)
Fetch the data associated with a particular key.