00001 #ifndef LIBNAGIOS_dkhash_h__ 00002 #define LIBNAGIOS_dkhash_h__ 00003 #include <errno.h> 00004 00005 /** 00006 * @file dkhash.h 00007 * @brief Dual-key hash functions for Nagios 00008 * 00009 * Having a dual-key hash function is pretty unusual, but since so 00010 * much data in Nagios pertains to services (which are uniquely 00011 * identified based on both host_name and service_description), it 00012 * makes sense here. 00013 * 00014 * @{ 00015 */ 00016 00017 /** return flags usable from the callback function of dkhash_walk_data() */ 00018 #define DKHASH_WALK_REMOVE 1 /**< Remove the most recently visited object */ 00019 #define DKHASH_WALK_STOP 2 /**< Cause walking to stop */ 00020 00021 /** return values for dkhash_insert() */ 00022 #define DKHASH_OK 0 /**< Success */ 00023 #define DKHASH_EDUPE (-EPERM) /**< duplicate insert attempted */ 00024 #define DKHASH_EPERM (-EPERM) /**< duplicate insert attempted */ 00025 #define DKHASH_EINVAL (-EINVAL) /**< Invalid parameters passed */ 00026 #define DKHASH_ENOMEM (-ENOMEM) /**< Memory allocation failed */ 00027 00028 struct dkhash_table; 00029 /** opaque type */ 00030 typedef struct dkhash_table dkhash_table; 00031 00032 /** 00033 * Create a dual-keyed hash-table of the given size 00034 * Note that it's generally useful to make the table 25-30% larger 00035 * than the number of items you intend to store, and also note that 00036 * the 'size' arguments gets rounded up to the nearest power of 2. 00037 * @param size The desired size of the hash-table. 00038 */ 00039 extern dkhash_table *dkhash_create(unsigned int size); 00040 00041 /** 00042 * Destroy a dual-keyed hash table 00043 * @param t The table to destroy 00044 * @return 0 on success, -1 on errors 00045 */ 00046 extern int dkhash_destroy(dkhash_table *t); 00047 00048 /** 00049 * Fetch the data associated with a particular key 00050 * @param t The table to get the data from 00051 * @param k1 The first key 00052 * @param k2 The second key 00053 * @return The data on success, NULL on errors or if data isn't found 00054 */ 00055 extern void *dkhash_get(dkhash_table *t, const char *k1, const char *k2); 00056 00057 /** 00058 * Insert a new entry into the hash table 00059 * @param t The hash table 00060 * @param k1 The first key 00061 * @param k2 The second key (may be null) 00062 * @param data The data to insert 00063 * @return 0 on success, < 0 on errors 00064 */ 00065 extern int dkhash_insert(dkhash_table *t, const char *k1, const char *k2, void *data); 00066 00067 /** 00068 * Remove data from the hash table 00069 * Note that this does not free() the pointer to the data stored in the 00070 * table. It just destroys containers for that data in the hash table. 00071 * @param t The hash table 00072 * @param k1 The first key 00073 * @param k2 The second key 00074 * @return The removed data on success, or NULL on errors 00075 */ 00076 extern void *dkhash_remove(dkhash_table *t, const char *k1, const char *k2); 00077 00078 /** 00079 * Call a function once for each item in the hash-table 00080 * The callback function can return DKHASH_WALK_{REMOVE,STOP} or any 00081 * OR'ed combination thereof to control the walking procedure, and 00082 * should return 0 on the normal case. 00083 * @param t The hash table 00084 * @param walker The callback function to send the data to 00085 */ 00086 extern void dkhash_walk_data(dkhash_table *t, int (*walker)(void *data)); 00087 00088 00089 /** 00090 * Get number of collisions in hash table 00091 * Many collisions is a sign of a too small hash table or 00092 * poor hash-function. 00093 * @param t The hash table to report on 00094 * @return The total number of collisions (not duplicates) from inserts 00095 */ 00096 extern unsigned int dkhash_collisions(dkhash_table *t); 00097 00098 /** 00099 * Get number of items in the hash table 00100 * @param t The hash table 00101 * @return Number of items currently in the hash-table 00102 */ 00103 extern unsigned int dkhash_num_entries(dkhash_table *t); 00104 00105 /** 00106 * Get max number of items stored in the hash table 00107 * @param t The hash table 00108 * @return Max number of items stored in hash-table 00109 */ 00110 extern unsigned int dkhash_num_entries_max(dkhash_table *t); 00111 00112 /** 00113 * Get number of entries added to hash table 00114 * Note that some of them may have been removed. 00115 * @param t The hash table 00116 * @return The number of items added to the table 00117 */ 00118 extern unsigned int dkhash_num_entries_added(dkhash_table *t); 00119 00120 /** 00121 * Get number of removed items from hash table 00122 * @param t The hash table 00123 * @return Number of items removed from hash table 00124 */ 00125 extern unsigned int dkhash_num_entries_removed(dkhash_table *t); 00126 00127 /** 00128 * Get actual table size (in number of buckets) 00129 * @param t The hash table 00130 * @return Number of bucket-slots in hash table 00131 */ 00132 extern unsigned int dkhash_table_size(dkhash_table *t); 00133 /** @} */ 00134 #endif /* LIBNAGIOS_dkhash_h__ */