00001 #ifndef LIBNAGIOS_FANOUT_H_INCLUDED 00002 #define LIBNAGIOS_FANOUT_H_INCLUDED 00003 #include "lnag-utils.h" 00004 00005 /** 00006 * @file fanout.h 00007 * @brief Simple fanout table implementation 00008 * 00009 * Fanouts are useful to hold short-lived integer-indexed data where 00010 * the keyspan between smallest and largest key can be too large and 00011 * change too often for it to be practical to maintain a growing array. 00012 * If you think of it as a hash-table optimized for unsigned longs you've 00013 * got the right idea. 00014 * 00015 * @{ 00016 */ 00017 00018 NAGIOS_BEGIN_DECL 00019 00020 /** Primary (opaque) type for this api */ 00021 typedef struct fanout_table fanout_table; 00022 00023 /** 00024 * Create a fanout table 00025 * @param[in] size The size of the table. Preferably a power of 2 00026 * @return Pointer to a newly created table 00027 */ 00028 extern fanout_table *fanout_create(unsigned long size); 00029 00030 /** 00031 * Destroy a fanout table, with optional destructor. 00032 * This function will iterate over all the entries in the fanout 00033 * table and remove them, one by one. If 'destructor' is not NULL, 00034 * it will be called on each and every object in the table. Note that 00035 * 'free' is a valid destructor. 00036 * 00037 * @param[in] t The fanout table to destroy 00038 * @param[in] destructor Function to call on data pointers in table 00039 */ 00040 extern void fanout_destroy(fanout_table *t, void (*destructor)(void *)); 00041 00042 /** 00043 * Return a pointer from the fanout table t 00044 * 00045 * @param[in] t table to fetch from 00046 * @param[in] key key to fetch 00047 * @return NULL on errors; Pointer to data on success 00048 */ 00049 extern void *fanout_get(fanout_table *t, unsigned long key); 00050 00051 /** 00052 * Add an entry to the fanout table. 00053 * Note that we don't check if the key is unique. If it isn't, 00054 * fanout_remove() will remove the latest added first. 00055 * 00056 * @param[in] t fanout table to add to 00057 * @param[in] key Key for this entry 00058 * @param[in] data Data to add. Must not be NULL 00059 * @return 0 on success, -1 on errors 00060 */ 00061 extern int fanout_add(fanout_table *t, unsigned long key, void *data); 00062 00063 /** 00064 * Remove an entry from the fanout table and return its data. 00065 * 00066 * @param[in] t fanout table to look in 00067 * @param[in] key The key whose data we should locate 00068 * @return Pointer to the data stored on success; NULL on errors 00069 */ 00070 extern void *fanout_remove(fanout_table *t, unsigned long key); 00071 NAGIOS_END_DECL 00072 /** @} */ 00073 #endif