All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_hashmap.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2017 Aerospike, Inc.
3  *
4  * Portions may be licensed to Aerospike, Inc. under one or more contributor
5  * license agreements.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
8  * use this file except in compliance with the License. You may obtain a copy of
9  * the License at http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14  * License for the specific language governing permissions and limitations under
15  * the License.
16  */
17 
18 #pragma once
19 
20 #include <aerospike/as_map.h>
21 
22 #include <stdbool.h>
23 #include <stdint.h>
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 /******************************************************************************
30  * TYPES
31  ******************************************************************************/
32 
33 /**
34  * Internal structure only for use by as_hashmap and as_hashmap_iterator.
35  */
36 typedef struct as_hashmap_element_s {
39  uint32_t next;
41 
42 /**
43  * A hashtable based implementation of `as_map`.
44  *
45  * To use the map, you can either initialize a stack allocated map,
46  * using `as_hashmap_init()`:
47  *
48  * ~~~~~~~~~~{.c}
49  * as_hashmap map;
50  * as_hashmap_init(&map, 32);
51  * ~~~~~~~~~~
52  *
53  * Or you can create a new heap allocated map using
54  * `as_hashmap_new()`:
55  *
56  * ~~~~~~~~~~{.c}
57  * as_hashmap * map = as_hashmap_new(32);
58  * ~~~~~~~~~~
59  *
60  * When you are finished using the map, then you should release the
61  * map and associated resources, using `as_hashmap_destroy()`:
62  *
63  * ~~~~~~~~~~{.c}
64  * as_hashmap_destroy(map);
65  * ~~~~~~~~~~
66  *
67  *
68  * The `as_hashmap` is a subtype of `as_map`. This allows you to alternatively
69  * use `as_map` functions, by typecasting `as_hashmap` to `as_map`.
70  *
71  * ~~~~~~~~~~{.c}
72  * as_hashmap map;
73  * as_map * l = (as_map*) as_hashmap_init(&map, 32);
74  * as_stringmap_set_int64(l, "a", 1);
75  * as_stringmap_set_int64(l, "b", 2);
76  * as_stringmap_set_int64(l, "c", 3);
77  * as_map_destroy(l);
78  * ~~~~~~~~~~
79  *
80  * The `as_stringmap` functions are simplified functions for using string key.
81  *
82  * Each of the `as_map` functions proxy to the `as_hashmap` functions.
83  * So, calling `as_map_destroy()` is equivalent to calling
84  * `as_hashmap_destroy()`.
85  *
86  * Notes:
87  *
88  * This hashmap implementation is NOT threadsafe.
89  *
90  * Internally, the hashmap stores keys' and values' pointers - it does NOT copy
91  * the keys or values, so the caller must ensure these keys and values are not
92  * destroyed while the hashmap is still in use.
93  *
94  * Further, the hashmap does not increment ref-counts of the keys or values.
95  * However when an element is removed from the hashmap, the hashmap will call
96  * as_val_destroy() on both the key and value. And when the hashmap is cleared
97  * or destroyed, as_val_destroy() will be called for all keys and values.
98  * Therefore if the caller inserts keys and values in the hashmap without extra
99  * ref-counts, the caller is effectively handing off ownership of these objects
100  * to the hashmap.
101  *
102  * @extends as_map
103  * @ingroup aerospike_t
104  */
105 typedef struct as_hashmap_s {
106 
107  /**
108  * @private
109  * as_hashmap is an as_map.
110  * You can cast as_hashmap to as_map.
111  */
112  as_map _;
113 
114  /**
115  * Number of elements in the map.
116  */
117  uint32_t count;
118 
119  /**
120  * The "main" table - elements go here unless their key hash collides with
121  * that of an existing element's key.
122  */
123  uint32_t table_capacity;
125 
126  /**
127  * The "extra" slots - elements go here when their key hash collides with
128  * that of an existing element's key.
129  */
130  uint32_t capacity_step;
131  uint32_t extra_capacity;
133  uint32_t insert_at;
134  uint32_t free_q;
135 
136 } as_hashmap;
137 
138 /*******************************************************************************
139  * INSTANCE FUNCTIONS
140  ******************************************************************************/
141 
142 /**
143  * Initialize a stack allocated hashmap.
144  *
145  * @param map The map to initialize.
146  * @param buckets The number of hash buckets to allocate.
147  *
148  * @return On success, the initialized map. Otherwise NULL.
149  *
150  * @relatesalso as_hashmap
151  */
152 as_hashmap * as_hashmap_init(as_hashmap * map, uint32_t buckets);
153 
154 /**
155  * Creates a new map as a hashmap.
156  *
157  * @param buckets The number of hash buckets to allocate.
158  *
159  * @return On success, the new map. Otherwise NULL.
160  *
161  * @relatesalso as_hashmap
162  */
163 as_hashmap * as_hashmap_new(uint32_t buckets);
164 
165 /**
166  * Free the map and associated resources.
167  *
168  * @param map The map to destroy.
169  *
170  * @relatesalso as_hashmap
171  */
172 void as_hashmap_destroy(as_hashmap * map);
173 
174 /*******************************************************************************
175  * INFO FUNCTIONS
176  ******************************************************************************/
177 
178 /**
179  * The hash value of the map.
180  *
181  * @param map The map.
182  *
183  * @return The hash value of the map.
184  *
185  * @relatesalso as_hashmap
186  */
187 uint32_t as_hashmap_hashcode(const as_hashmap * map);
188 
189 /**
190  * Get the number of entries in the map.
191  *
192  * @param map The map.
193  *
194  * @return The number of entries in the map.
195  *
196  * @relatesalso as_hashmap
197  */
198 uint32_t as_hashmap_size(const as_hashmap * map);
199 
200 /*******************************************************************************
201  * ACCESSOR AND MODIFIER FUNCTIONS
202  ******************************************************************************/
203 
204 /**
205  * Get the value for specified key.
206  *
207  * @param map The map.
208  * @param key The key.
209  *
210  * @return The value for the specified key. Otherwise NULL.
211  *
212  * @relatesalso as_hashmap
213  */
214 as_val * as_hashmap_get(const as_hashmap * map, const as_val * key);
215 
216 /**
217  * Set the value for specified key.
218  *
219  * @param map The map.
220  * @param key The key.
221  * @param val The value for the given key.
222  *
223  * @return 0 on success. Otherwise an error occurred.
224  *
225  * @relatesalso as_hashmap
226  */
227 int as_hashmap_set(as_hashmap * map, const as_val * key, const as_val * val);
228 
229 /**
230  * Remove all entries from the map.
231  *
232  * @param map The map.
233  *
234  * @return 0 on success. Otherwise an error occurred.
235  *
236  * @relatesalso as_hashmap
237  */
238 int as_hashmap_clear(as_hashmap * map);
239 
240 /**
241  * Remove the entry specified by the key.
242  *
243  * @param map The map to remove the entry from.
244  * @param key The key of the entry to be removed.
245  *
246  * @return 0 on success. Otherwise an error occurred.
247  *
248  * @relatesalso as_hashmap
249  */
250 int as_hashmap_remove(as_hashmap * map, const as_val * key);
251 
252 /******************************************************************************
253  * ITERATION FUNCTIONS
254  *****************************************************************************/
255 
256 /**
257  * Call the callback function for each entry in the map.
258  *
259  * @param map The map.
260  * @param callback The function to call for each entry.
261  * @param udata User-data to be passed to the callback.
262  *
263  * @return true if iteration completes fully. false if iteration was aborted.
264  *
265  * @relatesalso as_hashmap
266  */
267 bool as_hashmap_foreach(const as_hashmap * map, as_map_foreach_callback callback, void * udata);
268 
269 #ifdef __cplusplus
270 } // end extern "C"
271 #endif
bool as_hashmap_foreach(const as_hashmap *map, as_map_foreach_callback callback, void *udata)
int as_hashmap_remove(as_hashmap *map, const as_val *key)
uint32_t table_capacity
Definition: as_hashmap.h:123
Definition: as_map.h:61
uint32_t as_hashmap_hashcode(const as_hashmap *map)
uint32_t count
Definition: as_hashmap.h:117
Definition: as_val.h:57
uint32_t insert_at
Definition: as_hashmap.h:133
as_hashmap_element * table
Definition: as_hashmap.h:124
uint32_t free_q
Definition: as_hashmap.h:134
int as_hashmap_set(as_hashmap *map, const as_val *key, const as_val *val)
as_hashmap * as_hashmap_new(uint32_t buckets)
as_hashmap * as_hashmap_init(as_hashmap *map, uint32_t buckets)
uint32_t extra_capacity
Definition: as_hashmap.h:131
as_hashmap_element * extras
Definition: as_hashmap.h:132
void as_hashmap_destroy(as_hashmap *map)
uint32_t capacity_step
Definition: as_hashmap.h:130
uint32_t as_hashmap_size(const as_hashmap *map)
bool(* as_map_foreach_callback)(const as_val *key, const as_val *value, void *udata)
Definition: as_map.h:50
as_val * as_hashmap_get(const as_hashmap *map, const as_val *key)
int as_hashmap_clear(as_hashmap *map)