OpenMPI  0.1.1
opal_hash_table.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
3  * University Research and Technology
4  * Corporation. All rights reserved.
5  * Copyright (c) 2004-2005 The University of Tennessee and The University
6  * of Tennessee Research Foundation. All rights
7  * reserved.
8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9  * University of Stuttgart. All rights reserved.
10  * Copyright (c) 2004-2005 The Regents of the University of California.
11  * All rights reserved.
12  * $COPYRIGHT$
13  *
14  * Additional copyrights may follow
15  *
16  * $HEADER$
17  *
18  */
19 
20 /** @file
21  *
22  * A hash table that may be indexed with either fixed length
23  * (e.g. uint32_t/uint64_t) or arbitrary size binary key
24  * values. However, only one key type may be used in a given table
25  * concurrently.
26  */
27 
28 #ifndef OPAL_HASH_TABLE_H
29 #define OPAL_HASH_TABLE_H
30 
31 #include "opal_config.h"
32 
33 #ifdef HAVE_STDINT_H
34 #include <stdint.h>
35 #endif
36 #include "opal/class/opal_list.h"
37 
38 BEGIN_C_DECLS
39 
41 
43 {
44  opal_object_t super; /**< subclass of opal_object_t */
45  opal_list_t ht_nodes; /**< free list of hash nodes */
46  opal_list_t *ht_table; /**< each item is an array of opal_fhnode_t nodes */
47  size_t ht_table_size; /**< size of table */
48  size_t ht_size; /**< number of values on table */
49  size_t ht_mask;
50 };
52 
53 
54 
55 /**
56  * Initializes the table size, must be called before using
57  * the table.
58  *
59  * @param table The input hash table (IN).
60  * @param size The size of the table, which will be rounded up
61  * (if required) to the next highest power of two (IN).
62  * @return OPAL error code.
63  *
64  */
65 
66 OPAL_DECLSPEC int opal_hash_table_init(opal_hash_table_t* ht, size_t table_size);
67 
68 
69 /**
70  * Returns the number of elements currently stored in the table.
71  *
72  * @param table The input hash table (IN).
73  * @return The number of elements in the table.
74  *
75  */
76 
78 {
79  return ht->ht_size;
80 }
81 
82 /**
83  * Remove all elements from the table.
84  *
85  * @param table The input hash table (IN).
86  * @return OPAL return code.
87  *
88  */
89 
90 OPAL_DECLSPEC int opal_hash_table_remove_all(opal_hash_table_t *ht);
91 
92 /**
93  * Retrieve value via uint32_t key.
94  *
95  * @param table The input hash table (IN).
96  * @param key The input key (IN).
97  * @param ptr The value associated with the key
98  * @return integer return code:
99  * - OPAL_SUCCESS if key was found
100  * - OPAL_ERR_NOT_FOUND if key was not found
101  * - OPAL_ERROR other error
102  *
103  */
104 
105 OPAL_DECLSPEC int opal_hash_table_get_value_uint32(opal_hash_table_t* table, uint32_t key,
106  void** ptr);
107 
108 /**
109  * Set value based on uint32_t key.
110  *
111  * @param table The input hash table (IN).
112  * @param key The input key (IN).
113  * @param value The value to be associated with the key (IN).
114  * @return OPAL return code.
115  *
116  */
117 
118 OPAL_DECLSPEC int opal_hash_table_set_value_uint32(opal_hash_table_t* table, uint32_t key, void* value);
119 
120 /**
121  * Remove value based on uint32_t key.
122  *
123  * @param table The input hash table (IN).
124  * @param key The input key (IN).
125  * @return OPAL return code.
126  *
127  */
128 
129 OPAL_DECLSPEC int opal_hash_table_remove_value_uint32(opal_hash_table_t* table, uint32_t key);
130 
131 /**
132  * Retrieve value via uint64_t key.
133  *
134  * @param table The input hash table (IN).
135  * @param key The input key (IN).
136  * @param ptr The value associated with the key
137  * @return integer return code:
138  * - OPAL_SUCCESS if key was found
139  * - OPAL_ERR_NOT_FOUND if key was not found
140  * - OPAL_ERROR other error
141  *
142  */
143 
144 OPAL_DECLSPEC int opal_hash_table_get_value_uint64(opal_hash_table_t *table, uint64_t key,
145  void **ptr);
146 
147 /**
148  * Set value based on uint64_t key.
149  *
150  * @param table The input hash table (IN).
151  * @param key The input key (IN).
152  * @param value The value to be associated with the key (IN).
153  * @return OPAL return code.
154  *
155  */
156 
157 OPAL_DECLSPEC int opal_hash_table_set_value_uint64(opal_hash_table_t *table, uint64_t key, void* value);
158 
159 /**
160  * Remove value based on uint64_t key.
161  *
162  * @param table The input hash table (IN).
163  * @param key The input key (IN).
164  * @return OPAL return code.
165  *
166  */
167 
168 OPAL_DECLSPEC int opal_hash_table_remove_value_uint64(opal_hash_table_t *table, uint64_t key);
169 
170 /**
171  * Retrieve value via arbitrary length binary key.
172  *
173  * @param table The input hash table (IN).
174  * @param key The input key (IN).
175  * @param ptr The value associated with the key
176  * @return integer return code:
177  * - OPAL_SUCCESS if key was found
178  * - OPAL_ERR_NOT_FOUND if key was not found
179  * - OPAL_ERROR other error
180  *
181  */
182 
183 OPAL_DECLSPEC int opal_hash_table_get_value_ptr(opal_hash_table_t *table, const void* key,
184  size_t keylen, void **ptr);
185 
186 /**
187  * Set value based on arbitrary length binary key.
188  *
189  * @param table The input hash table (IN).
190  * @param key The input key (IN).
191  * @param value The value to be associated with the key (IN).
192  * @return OPAL return code.
193  *
194  */
195 
196 OPAL_DECLSPEC int opal_hash_table_set_value_ptr(opal_hash_table_t *table, const void* key, size_t keylen, void* value);
197 
198 /**
199  * Remove value based on arbitrary length binary key.
200  *
201  * @param table The input hash table (IN).
202  * @param key The input key (IN).
203  * @return OPAL return code.
204  *
205  */
206 
207 OPAL_DECLSPEC int opal_hash_table_remove_value_ptr(opal_hash_table_t *table, const void* key, size_t keylen);
208 
209 
210 /** The following functions are only for allowing iterating through
211  the hash table. The calls return along with a key, a pointer to
212  the hash node with the current key, so that subsequent calls do
213  not have to traverse all over again to the key (although it may
214  just be a simple thing - to go to the array element and then
215  traverse through the individual list). But lets take out this
216  inefficiency too. This is similar to having an STL iterator in
217  functionality */
218 
219 /**
220  * Get the first 32 bit key from the hash table, which can be used later to
221  * get the next key
222  * @param table The hash table pointer (IN)
223  * @param key The first key (OUT)
224  * @param value The value corresponding to this key (OUT)
225  * @param node The pointer to the hash table internal node which stores
226  * the key-value pair (this is required for subsequent calls
227  * to get_next_key) (OUT)
228  * @return OPAL error code
229  *
230  */
231 
232 OPAL_DECLSPEC int opal_hash_table_get_first_key_uint32(opal_hash_table_t *table, uint32_t *key,
233  void **value, void **node);
234 
235 
236 /**
237  * Get the next 32 bit key from the hash table, knowing the current key
238  * @param table The hash table pointer (IN)
239  * @param key The key (OUT)
240  * @param value The value corresponding to this key (OUT)
241  * @param in_node The node pointer from previous call to either get_first
242  or get_next (IN)
243  * @param out_node The pointer to the hash table internal node which stores
244  * the key-value pair (this is required for subsequent calls
245  * to get_next_key) (OUT)
246  * @return OPAL error code
247  *
248  */
249 
250 OPAL_DECLSPEC int opal_hash_table_get_next_key_uint32(opal_hash_table_t *table, uint32_t *key,
251  void **value, void *in_node,
252  void **out_node);
253 
254 
255 /**
256  * Get the first 64 key from the hash table, which can be used later to
257  * get the next key
258  * @param table The hash table pointer (IN)
259  * @param key The first key (OUT)
260  * @param value The value corresponding to this key (OUT)
261  * @param node The pointer to the hash table internal node which stores
262  * the key-value pair (this is required for subsequent calls
263  * to get_next_key) (OUT)
264  * @return OPAL error code
265  *
266  */
267 
268 OPAL_DECLSPEC int opal_hash_table_get_first_key_uint64(opal_hash_table_t *table, uint64_t *key,
269  void **value, void **node);
270 
271 
272 /**
273  * Get the next 64 bit key from the hash table, knowing the current key
274  * @param table The hash table pointer (IN)
275  * @param key The key (OUT)
276  * @param value The value corresponding to this key (OUT)
277  * @param in_node The node pointer from previous call to either get_first
278  or get_next (IN)
279  * @param out_node The pointer to the hash table internal node which stores
280  * the key-value pair (this is required for subsequent calls
281  * to get_next_key) (OUT)
282  * @return OPAL error code
283  *
284  */
285 
286 OPAL_DECLSPEC int opal_hash_table_get_next_key_uint64(opal_hash_table_t *table, uint64_t *key,
287  void **value, void *in_node,
288  void **out_node);
289 
290 END_C_DECLS
291 
292 #endif /* OPAL_HASH_TABLE_H */
OPAL_DECLSPEC int opal_hash_table_set_value_uint32(opal_hash_table_t *table, uint32_t key, void *value)
Set value based on uint32_t key.
Definition: opal_hash_table.c:153
Definition: opal_hash_table.h:42
OPAL_DECLSPEC int opal_hash_table_get_first_key_uint64(opal_hash_table_t *table, uint64_t *key, void **value, void **node)
Get the first 64 key from the hash table, which can be used later to get the next key...
Definition: opal_hash_table.c:542
size_t ht_size
number of values on table
Definition: opal_hash_table.h:48
OPAL_DECLSPEC int opal_hash_table_get_first_key_uint32(opal_hash_table_t *table, uint32_t *key, void **value, void **node)
The following functions are only for allowing iterating through the hash table.
Definition: opal_hash_table.c:470
OPAL_DECLSPEC int opal_hash_table_get_value_uint64(opal_hash_table_t *table, uint64_t key, void **ptr)
Retrieve value via uint64_t key.
Definition: opal_hash_table.c:234
static size_t opal_hash_table_get_size(opal_hash_table_t *ht)
Returns the number of elements currently stored in the table.
Definition: opal_hash_table.h:77
OPAL_DECLSPEC int opal_hash_table_set_value_ptr(opal_hash_table_t *table, const void *key, size_t keylen, void *value)
Set value based on arbitrary length binary key.
Definition: opal_hash_table.c:396
OPAL_DECLSPEC int opal_hash_table_remove_all(opal_hash_table_t *ht)
Remove all elements from the table.
Definition: opal_hash_table.c:89
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
opal_object_t super
subclass of opal_object_t
Definition: opal_hash_table.h:44
OPAL_DECLSPEC int opal_hash_table_get_value_ptr(opal_hash_table_t *table, const void *key, size_t keylen, void **ptr)
Retrieve value via arbitrary length binary key.
Definition: opal_hash_table.c:369
opal_list_t * ht_table
each item is an array of opal_fhnode_t nodes
Definition: opal_hash_table.h:46
OPAL_DECLSPEC int opal_hash_table_remove_value_ptr(opal_hash_table_t *table, const void *key, size_t keylen)
Remove value based on arbitrary length binary key.
Definition: opal_hash_table.c:437
opal_list_t ht_nodes
free list of hash nodes
Definition: opal_hash_table.h:45
Base object.
Definition: opal_object.h:182
Definition: opal_list.h:147
OPAL_DECLSPEC int opal_hash_table_remove_value_uint64(opal_hash_table_t *table, uint64_t key)
Remove value based on uint64_t key.
Definition: opal_hash_table.c:296
OPAL_DECLSPEC int opal_hash_table_init(opal_hash_table_t *ht, size_t table_size)
Initializes the table size, must be called before using the table.
Definition: opal_hash_table.c:71
OPAL_DECLSPEC int opal_hash_table_get_value_uint32(opal_hash_table_t *table, uint32_t key, void **ptr)
Retrieve value via uint32_t key.
Definition: opal_hash_table.c:128
OPAL_DECLSPEC int opal_hash_table_remove_value_uint32(opal_hash_table_t *table, uint32_t key)
Remove value based on uint32_t key.
Definition: opal_hash_table.c:189
OPAL_DECLSPEC int opal_hash_table_get_next_key_uint32(opal_hash_table_t *table, uint32_t *key, void **value, void *in_node, void **out_node)
Get the next 32 bit key from the hash table, knowing the current key.
Definition: opal_hash_table.c:497
OPAL_DECLSPEC int opal_hash_table_get_next_key_uint64(opal_hash_table_t *table, uint64_t *key, void **value, void *in_node, void **out_node)
Get the next 64 bit key from the hash table, knowing the current key.
Definition: opal_hash_table.c:569
OPAL_DECLSPEC int opal_hash_table_set_value_uint64(opal_hash_table_t *table, uint64_t key, void *value)
Set value based on uint64_t key.
Definition: opal_hash_table.c:259
size_t ht_table_size
size of table
Definition: opal_hash_table.h:47
#define OBJ_CLASS_DECLARATION(NAME)
Declaration for class descriptor.
Definition: opal_object.h:236