X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=mware%2Fhashtable.h;h=727bca68d3d71e6f86f7694840fa134cb201842b;hb=4bf15025c3fe95a226686b793e39a44f5f08d7da;hp=931917a64befa149a90d0b260c9cd01736c6d2f2;hpb=277b540c0764dd376dcf583acdc97a2b2fd3d8e6;p=bertos.git diff --git a/mware/hashtable.h b/mware/hashtable.h index 931917a6..727bca68 100755 --- a/mware/hashtable.h +++ b/mware/hashtable.h @@ -1,8 +1,8 @@ -/*! +/** * \file * * @@ -31,93 +31,71 @@ /*#* *#* $Log$ - *#* Revision 1.4 2004/08/25 14:12:09 rasky - *#* Aggiornato il comment block dei log RCS + *#* Revision 1.8 2006/07/19 12:56:27 bernie + *#* Convert to new Doxygen style. *#* - *#* Revision 1.3 2004/08/14 19:37:57 rasky - *#* Merge da SC: macros.h, pool.h, BIT_CHANGE, nome dei processi, etc. - *#* - *#* Revision 1.2 2004/08/04 15:52:54 rasky - *#* Merge da SC: fixato namespace dell'include guard - *#* - *#* Revision 1.1 2004/07/14 14:08:16 rasky - *#* Implementazione di una tabella hash - *#* - *#* Revision 1.10 2004/06/14 15:17:15 rasky - *#* Qualche fix alla documentazione Doxygen - *#* - *#* Revision 1.9 2004/06/14 15:15:24 rasky - *#* Cambiato key_data in un union invece di castare - *#* Aggiunto un ASSERT sull'indice calcolata nella key_internal_get_ptr - *#* - *#* Revision 1.8 2004/06/14 14:59:40 rasky - *#* Rinominanta la macro di configurazione per rispettare il namespace, e aggiunta in un punto in cui mancava - *#* - *#* Revision 1.7 2004/06/12 15:18:05 rasky - *#* Nuova hashtable con chiave esterna o interna a scelta, come discusso - *#* - *#* Revision 1.6 2004/05/26 16:33:31 rasky - *#* Aggiunta interfaccia per visita della hashtable tramite iteratori - *#* - *#* Revision 1.5 2004/05/24 18:42:23 rasky - *#* Fixato un commento doxygen - *#* - *#* Revision 1.4 2004/05/24 15:28:20 rasky - *#* Sistemata la documentazione, rimossa keycmp in favore della memcmp + *#* Revision 1.7 2006/06/01 12:27:39 marco + *#* Added utilities for protocols *#* *#*/ - #ifndef MWARE_HASHTABLE_H #define MWARE_HASHTABLE_H -#include -#include -#include +#include +#include +#include -/*! Enable/disable support to declare special hash tables which maintain a copy of - * the key internally instead of relying on the hook to extract it from the data. +/** + * Enable/disable support to declare special hash tables which maintain a copy of + * the key internally instead of relying on the hook to extract it from the data. */ #define CONFIG_HT_OPTIONAL_INTERNAL_KEY 1 -//! Maximum length of the internal key (use (2^n)-1 for slight speedup) +/// Maximum length of the internal key (use (2^n)-1 for slight speedup) #define INTERNAL_KEY_MAX_LENGTH 15 -/*! Hook to get the key from \a data, which is an element of the hash table. The - * key must be returned together with \a key_length (in words). +/** + * Hook to get the key from \a data, which is an element of the hash table. The + * key must be returned together with \a key_length (in words). */ -typedef const void* (*hook_get_key)(const void* data, uint8_t* key_length); +typedef const void *(*hook_get_key)(const void *data, uint8_t *key_length); -/*! Hash table description + +/** + * Hash table description * * \note This structures MUST NOT be accessed directly. Its definition is * provided in the header file only for optimization purposes (see the rationale * in hashtable.c). * - * \note If new elements must be added to this list, please double check + * \note If new elements must be added to this list, please double check * \c DECLARE_HASHTABLE, which requires the existing elements to be at the top. */ struct HashTable { - const void** mem; //!< Buckets of data - uint16_t max_elts_log2; //!< Log2 of the size of the table + const void **mem; ///< Buckets of data + uint16_t max_elts_log2; ///< Log2 of the size of the table struct { - bool key_internal : 1; //!< true if the key is copied internally + bool key_internal : 1; ///< true if the key is copied internally } flags; union { - hook_get_key hook; //!< Hook to get the key - uint8_t* mem; //!< Pointer to the key memory + hook_get_key hook; ///< Hook to get the key + uint8_t *mem; ///< Pointer to the key memory } key_data; }; -//! Iterator to walk the hash table + +/// Iterator to walk the hash table typedef struct { const void** pos; const void** end; } HashIterator; -/*! Declare a hash table in the current scope + +/** + * Declare a hash table in the current scope * * \param name Variable name * \param size Number of elements @@ -131,13 +109,13 @@ typedef struct static const void* name##_nodes[1 << UINT32_LOG2(size)]; \ struct HashTable name = { name##_nodes, UINT32_LOG2(size), { false }, hook_gk } -/*! Exactly like \c DECLARE_HASHTABLE, but the variable will be declared as static. */ +/** Exactly like \c DECLARE_HASHTABLE, but the variable will be declared as static. */ #define DECLARE_HASHTABLE_STATIC(name, size, hook_gk) \ static const void* name##_nodes[1 << UINT32_LOG2(size)]; \ - static struct HashTable name = { name##_nodes, UINT32_LOG2(size), { false }, hook_gk } + static struct HashTable name = { name##_nodes, UINT32_LOG2(size), { false }, { hook_gk } } #if CONFIG_HT_OPTIONAL_INTERNAL_KEY - /*! Declare a hash table with internal copies of the keys. This version does not + /** Declare a hash table with internal copies of the keys. This version does not * require a hook, nor it requires the user to allocate static memory for the keys. * It is mostly suggested for tables whose keys are computed on the fly and need * to be stored somewhere. @@ -147,14 +125,15 @@ typedef struct static const void* name##_nodes[1 << UINT32_LOG2(size)]; \ struct HashTable name = { name##_nodes, UINT32_LOG2(size), { true }, name##_keys } - /*! Exactly like \c DECLARE_HASHTABLE_INTERNALKEY, but the variable will be declared as static. */ + /** Exactly like \c DECLARE_HASHTABLE_INTERNALKEY, but the variable will be declared as static. */ #define DECLARE_HASHTABLE_INTERNALKEY_STATIC(name, size) \ static uint8_t name##_keys[(1 << UINT32_LOG2(size)) * (INTERNAL_KEY_MAX_LENGTH + 1)]; \ static const void* name##_nodes[1 << UINT32_LOG2(size)]; \ static struct HashTable name = { name##_nodes, UINT32_LOG2(size), { true }, name##_keys } #endif -/*! Initialize (and clear) a hash table in a memory buffer. +/** + * Initialize (and clear) a hash table in a memory buffer. * * \param ht Hash table declared with \c DECLARE_HASHTABLE * @@ -164,7 +143,8 @@ typedef struct */ void ht_init(struct HashTable* ht); -/*! Insert an element into the hash table +/** + * Insert an element into the hash table * * \param ht Handle of the hash table * \param data Data to be inserted into the table @@ -182,7 +162,8 @@ void ht_init(struct HashTable* ht); */ bool ht_insert(struct HashTable* ht, const void* data); -/*! Insert an element into the hash table +/** + * Insert an element into the hash table * * \param ht Handle of the hash table * \param key Key of the element @@ -202,7 +183,8 @@ bool ht_insert(struct HashTable* ht, const void* data); */ bool ht_insert_with_key(struct HashTable* ht, const void* key, uint8_t key_length, const void* data); -/*! Find an element in the hash table +/** + * Find an element in the hash table * * \param ht Handle of the hash table * \param key Key of the element @@ -211,13 +193,13 @@ bool ht_insert_with_key(struct HashTable* ht, const void* key, uint8_t key_lengt */ const void* ht_find(struct HashTable* ht, const void* key, uint8_t key_length); -/*! Similar to \c ht_insert_with_key() but \a key is an ASCIIZ string */ +/** Similar to \c ht_insert_with_key() but \a key is an ASCIIZ string */ #define ht_insert_str(ht, key, data) ht_insert_with_key(ht, key, strlen(key), data) -/*! Similar to \c ht_find() but \a key is an ASCIIZ string */ +/** Similar to \c ht_find() but \a key is an ASCIIZ string */ #define ht_find_str(ht, key) ht_find(ht, key, strlen(key)) -//! Get an iterator to the begin of the hash table \a ht +/// Get an iterator to the begin of the hash table \a ht INLINE HashIterator ht_iter_begin(struct HashTable* ht) { HashIterator h; @@ -231,11 +213,12 @@ INLINE HashIterator ht_iter_begin(struct HashTable* ht) return h; } -/*! Get an iterator to the (exclusive) end of the hash table \a ht +/** + * Get an iterator to the (exclusive) end of the hash table \a ht * - * \note Like in STL, the end iterator is not a valid iterator (you - * cannot call \c ht_iter_get() on it), and it must be used only to - * detect if we reached the end of the iteration (through \c ht_iter_cmp()). + * \note Like in STL, the end iterator is not a valid iterator (you + * cannot call \c ht_iter_get() on it), and it must be used only to + * detect if we reached the end of the iteration (through \c ht_iter_cmp()). */ INLINE HashIterator ht_iter_end(struct HashTable* ht) { @@ -246,18 +229,18 @@ INLINE HashIterator ht_iter_end(struct HashTable* ht) return h; } -//! Compare \a it1 and \a it2 for equality +/// Compare \a it1 and \a it2 for equality INLINE bool ht_iter_cmp(HashIterator it1, HashIterator it2) { ASSERT(it1.end == it2.end); return it1.pos == it2.pos; } -//! Get the element within the hash table \a ht pointed by the iterator \a iter +/// Get the element within the hash table \a ht pointed by the iterator \a iter INLINE const void* ht_iter_get(HashIterator iter) { return *iter.pos; } -/*! Return an iterator pointing to the element following \a h +/** Return an iterator pointing to the element following \a h * * \note The order of the elements visited during the iteration is casual, * and depends on the implementation.