Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
as_hashmap.h
Go to the documentation of this file.
1
/*
2
* Copyright 2008-2016 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 {
37
as_val
*
p_key
;
38
as_val
*
p_val
;
39
uint32_t
next
;
40
}
as_hashmap_element
;
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
;
124
as_hashmap_element
*
table
;
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
;
132
as_hashmap_element
*
extras
;
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