Main Page
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-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 {
33
as_val
*
p_key
;
34
as_val
*
p_val
;
35
uint32_t
next
;
36
}
as_hashmap_element
;
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
*/
108
as_map
_
;
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
;
120
as_hashmap_element
*
table
;
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
;
128
as_hashmap_element
*
extras
;
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);