Mercurial > hg > webserver / file comparison

comparison: src/ucx/cx/hash_map.h

src/ucx/cx/hash_map.h

changeset 579
e10457d74fe1
parent 504
c094afcdfb27
equal deleted inserted replaced
578:eb48f716b31c 579:e10457d74fe1
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE. 26 * POSSIBILITY OF SUCH DAMAGE.
27 */ 27 */
28 /** 28 /**
29 * \file hash_map.h 29 * @file hash_map.h
30 * \brief Hash map implementation. 30 * @brief Hash map implementation.
31 * \author Mike Becker 31 * @author Mike Becker
32 * \author Olaf Wintermann 32 * @author Olaf Wintermann
33 * \version 3.0 33 * @copyright 2-Clause BSD License
34 * \copyright 2-Clause BSD License
35 */ 34 */
36 35
37 #ifndef UCX_HASH_MAP_H 36 #ifndef UCX_HASH_MAP_H
38 #define UCX_HASH_MAP_H 37 #define UCX_HASH_MAP_H
39 38
66 65
67 66
68 /** 67 /**
69 * Creates a new hash map with the specified number of buckets. 68 * Creates a new hash map with the specified number of buckets.
70 * 69 *
71 * If \p buckets is zero, an implementation defined default will be used. 70 * If @p buckets is zero, an implementation defined default will be used.
72 * 71 *
73 * If \p item_size is CX_STORE_POINTERS, the created map will be created as if 72 * If @p elem_size is #CX_STORE_POINTERS, the created map stores pointers instead of
74 * cxMapStorePointers() was called immediately after creation. 73 * copies of the added elements.
75 * 74 *
76 * @note Iterators provided by this hash map implementation provide the remove operation. 75 * @note Iterators provided by this hash map implementation provide the remove operation.
77 * The index value of an iterator is incremented when the iterator advanced without removal. 76 * The index value of an iterator is incremented when the iterator advanced without removal.
78 * In other words, when the iterator is finished, \c index==size . 77 * In other words, when the iterator is finished, @c index==size .
79 * 78 *
80 * @param allocator the allocator to use 79 * @param allocator the allocator to use
80 * (if @c NULL, a default stdlib allocator will be used)
81 * @param itemsize the size of one element 81 * @param itemsize the size of one element
82 * @param buckets the initial number of buckets in this hash map 82 * @param buckets the initial number of buckets in this hash map
83 * @return a pointer to the new hash map 83 * @return a pointer to the new hash map
84 */ 84 */
85 __attribute__((__nonnull__, __warn_unused_result__)) 85 cx_attr_nodiscard
86 cx_attr_malloc
87 cx_attr_dealloc(cxMapFree, 1)
88 cx_attr_export
86 CxMap *cxHashMapCreate( 89 CxMap *cxHashMapCreate(
87 CxAllocator const *allocator, 90 const CxAllocator *allocator,
88 size_t itemsize, 91 size_t itemsize,
89 size_t buckets 92 size_t buckets
90 ); 93 );
91 94
92 /** 95 /**
93 * Creates a new hash map with a default number of buckets. 96 * Creates a new hash map with a default number of buckets.
94 * 97 *
95 * If \p item_size is CX_STORE_POINTERS, the created map will be created as if 98 * If @p elem_size is #CX_STORE_POINTERS, the created map stores pointers instead of
96 * cxMapStorePointers() was called immediately after creation. 99 * copies of the added elements.
97 * 100 *
98 * @note Iterators provided by this hash map implementation provide the remove operation. 101 * @note Iterators provided by this hash map implementation provide the remove operation.
99 * The index value of an iterator is incremented when the iterator advanced without removal. 102 * The index value of an iterator is incremented when the iterator advanced without removal.
100 * In other words, when the iterator is finished, \c index==size . 103 * In other words, when the iterator is finished, @c index==size .
101 * 104 *
102 * @param itemsize the size of one element 105 * @param itemsize (@c size_t) the size of one element
103 * @return a pointer to the new hash map 106 * @return (@c CxMap*) a pointer to the new hash map
104 */ 107 */
105 #define cxHashMapCreateSimple(itemsize) \ 108 #define cxHashMapCreateSimple(itemsize) cxHashMapCreate(NULL, itemsize, 0)
106 cxHashMapCreate(cxDefaultAllocator, itemsize, 0)
107 109
108 /** 110 /**
109 * Increases the number of buckets, if necessary. 111 * Increases the number of buckets, if necessary.
110 * 112 *
111 * The load threshold is \c 0.75*buckets. If the element count exceeds the load 113 * The load threshold is @c 0.75*buckets. If the element count exceeds the load
112 * threshold, the map will be rehashed. Otherwise, no action is performed and 114 * threshold, the map will be rehashed. Otherwise, no action is performed and
113 * this function simply returns 0. 115 * this function simply returns 0.
114 * 116 *
115 * The rehashing process ensures, that the number of buckets is at least 117 * The rehashing process ensures, that the number of buckets is at least
116 * 2.5 times the element count. So there is enough room for additional 118 * 2.5 times the element count. So there is enough room for additional
119 * You can use this function after filling a map to increase access performance. 121 * You can use this function after filling a map to increase access performance.
120 * 122 *
121 * @note If the specified map is not a hash map, the behavior is undefined. 123 * @note If the specified map is not a hash map, the behavior is undefined.
122 * 124 *
123 * @param map the map to rehash 125 * @param map the map to rehash
124 * @return zero on success, non-zero if a memory allocation error occurred 126 * @retval zero success
127 * @retval non-zero if a memory allocation error occurred
125 */ 128 */
126 __attribute__((__nonnull__)) 129 cx_attr_nonnull
130 cx_attr_export
127 int cxMapRehash(CxMap *map); 131 int cxMapRehash(CxMap *map);
128 132
129 133
130 #ifdef __cplusplus 134 #ifdef __cplusplus
131 } // extern "C" 135 } // extern "C"

Mercurial Repository: webserver

mercurial