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-2014 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 /******************************************************************************
26  * TYPES
27  ******************************************************************************/
28 
29 /**
30  * Internal structure only for use by as_hashmap and as_hashmap_iterator.
31  */
32 typedef struct as_hashmap_element_s {
35  uint32_t next;
37 
38 /**
39  * A hashtable based implementation of `as_map`.
40  *
41  * To use the map, you can either initialize a stack allocated map,
42  * using `as_hashmap_init()`:
43  *
44  * ~~~~~~~~~~{.c}
45  * as_hashmap map;
46  * as_hashmap_init(&map, 32);
47  * ~~~~~~~~~~
48  *
49  * Or you can create a new heap allocated map using
50  * `as_hashmap_new()`:
51  *
52  * ~~~~~~~~~~{.c}
53  * as_hashmap * map = as_hashmap_new(32);
54  * ~~~~~~~~~~
55  *
56  * When you are finished using the map, then you should release the
57  * map and associated resources, using `as_hashmap_destroy()`:
58  *
59  * ~~~~~~~~~~{.c}
60  * as_hashmap_destroy(map);
61  * ~~~~~~~~~~
62  *
63  *
64  * The `as_hashmap` is a subtype of `as_map`. This allows you to alternatively
65  * use `as_map` functions, by typecasting `as_hashmap` to `as_map`.
66  *
67  * ~~~~~~~~~~{.c}
68  * as_hashmap map;
69  * as_map * l = (as_map*) as_hashmap_init(&map, 32);
70  * as_stringmap_set_int64(l, "a", 1);
71  * as_stringmap_set_int64(l, "b", 2);
72  * as_stringmap_set_int64(l, "c", 3);
73  * as_map_destroy(l);
74  * ~~~~~~~~~~
75  *
76  * The `as_stringmap` functions are simplified functions for using string key.
77  *
78  * Each of the `as_map` functions proxy to the `as_hashmap` functions.
79  * So, calling `as_map_destroy()` is equivalent to calling
80  * `as_hashmap_destroy()`.
81  *
82  * Notes:
83  *
84  * This hashmap implementation is NOT threadsafe.
85  *
86  * Internally, the hashmap stores keys' and values' pointers - it does NOT copy
87  * the keys or values, so the caller must ensure these keys and values are not
88  * destroyed while the hashmap is still in use.
89  *
90  * Further, the hashmap does not increment ref-counts of the keys or values.
91  * However when an element is removed from the hashmap, the hashmap will call
92  * as_val_destroy() on both the key and value. And when the hashmap is cleared
93  * or destroyed, as_val_destroy() will be called for all keys and values.
94  * Therefore if the caller inserts keys and values in the hashmap without extra
95  * ref-counts, the caller is effectively handing off ownership of these objects
96  * to the hashmap.
97  *
98  * @extends as_map
99  * @ingroup aerospike_t
100  */
101 typedef struct as_hashmap_s {
102 
103  /**
104  * @private
105  * as_hashmap is an as_map.
106  * You can cast as_hashmap to as_map.
107  */
109 
110  /**
111  * Number of elements in the map.
112  */
113  uint32_t count;
114 
115  /**
116  * The "main" table - elements go here unless their key hash collides with
117  * that of an existing element's key.
118  */
119  uint32_t table_capacity;
121 
122  /**
123  * The "extra" slots - elements go here when their key hash collides with
124  * that of an existing element's key.
125  */
126  uint32_t capacity_step;
127  uint32_t extra_capacity;
129  uint32_t insert_at;
130  uint32_t free_q;
131 
132 } as_hashmap;
133 
134 /*******************************************************************************
135  * INSTANCE FUNCTIONS
136  ******************************************************************************/
137 
138 /**
139  * Initialize a stack allocated hashmap.
140  *
141  * @param map The map to initialize.
142  * @param buckets The number of hash buckets to allocate.
143  *
144  * @return On success, the initialized map. Otherwise NULL.
145  *
146  * @relatesalso as_hashmap
147  */
148 as_hashmap * as_hashmap_init(as_hashmap * map, uint32_t buckets);
149 
150 /**
151  * Creates a new map as a hashmap.
152  *
153  * @param buckets The number of hash buckets to allocate.
154  *
155  * @return On success, the new map. Otherwise NULL.
156  *
157  * @relatesalso as_hashmap
158  */
159 as_hashmap * as_hashmap_new(uint32_t buckets);
160 
161 /**
162  * Free the map and associated resources.
163  *
164  * @param map The map to destroy.
165  *
166  * @relatesalso as_hashmap
167  */
168 void as_hashmap_destroy(as_hashmap * map);
169 
170 /*******************************************************************************
171  * INFO FUNCTIONS
172  ******************************************************************************/
173 
174 /**
175  * The hash value of the map.
176  *
177  * @param map The map.
178  *
179  * @return The hash value of the map.
180  *
181  * @relatesalso as_hashmap
182  */
183 uint32_t as_hashmap_hashcode(const as_hashmap * map);
184 
185 /**
186  * Get the number of entries in the map.
187  *
188  * @param map The map.
189  *
190  * @return The number of entries in the map.
191  *
192  * @relatesalso as_hashmap
193  */
194 uint32_t as_hashmap_size(const as_hashmap * map);
195 
196 /*******************************************************************************
197  * ACCESSOR AND MODIFIER FUNCTIONS
198  ******************************************************************************/
199 
200 /**
201  * Get the value for specified key.
202  *
203  * @param map The map.
204  * @param key The key.
205  *
206  * @return The value for the specified key. Otherwise NULL.
207  *
208  * @relatesalso as_hashmap
209  */
210 as_val * as_hashmap_get(const as_hashmap * map, const as_val * key);
211 
212 /**
213  * Set the value for specified key.
214  *
215  * @param map The map.
216  * @param key The key.
217  * @param val The value for the given key.
218  *
219  * @return 0 on success. Otherwise an error occurred.
220  *
221  * @relatesalso as_hashmap
222  */
223 int as_hashmap_set(as_hashmap * map, const as_val * key, const as_val * val);
224 
225 /**
226  * Remove all entries from the map.
227  *
228  * @param map The map.
229  *
230  * @return 0 on success. Otherwise an error occurred.
231  *
232  * @relatesalso as_hashmap
233  */
234 int as_hashmap_clear(as_hashmap * map);
235 
236 /**
237  * Remove the entry specified by the key.
238  *
239  * @param map The map to remove the entry from.
240  * @param key The key of the entry to be removed.
241  *
242  * @return 0 on success. Otherwise an error occurred.
243  *
244  * @relatesalso as_hashmap
245  */
246 int as_hashmap_remove(as_hashmap * map, const as_val * key);
247 
248 /******************************************************************************
249  * ITERATION FUNCTIONS
250  *****************************************************************************/
251 
252 /**
253  * Call the callback function for each entry in the map.
254  *
255  * @param map The map.
256  * @param callback The function to call for each entry.
257  * @param udata User-data to be passed to the callback.
258  *
259  * @return true if iteration completes fully. false if iteration was aborted.
260  *
261  * @relatesalso as_hashmap
262  */
263 bool as_hashmap_foreach(const as_hashmap * map, as_map_foreach_callback callback, void * udata);
bool as_hashmap_foreach(const as_hashmap *map, as_map_foreach_callback callback, void *udata)
as_map _
Definition: as_hashmap.h:108
int as_hashmap_remove(as_hashmap *map, const as_val *key)
uint32_t table_capacity
Definition: as_hashmap.h:119
Definition: as_map.h:57
uint32_t as_hashmap_hashcode(const as_hashmap *map)
uint32_t count
Definition: as_hashmap.h:113
Definition: as_val.h:51
uint32_t insert_at
Definition: as_hashmap.h:129
as_hashmap_element * table
Definition: as_hashmap.h:120
uint32_t free_q
Definition: as_hashmap.h:130
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:127
as_hashmap_element * extras
Definition: as_hashmap.h:128
void as_hashmap_destroy(as_hashmap *map)
uint32_t capacity_step
Definition: as_hashmap.h:126
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:46
as_val * as_hashmap_get(const as_hashmap *map, const as_val *key)
int as_hashmap_clear(as_hashmap *map)