1ZHASHX(3) CZMQ Manual ZHASHX(3)
2
6 zhashx - Class for extended generic hash container
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 // This class has draft methods, which may change over time. They are not
12 // in stable releases, by default. Use --enable-drafts to enable.
13 // Destroy an item
14 typedef void (zhashx_destructor_fn) (
15 void **item);
16 // Duplicate an item
18 typedef void * (zhashx_duplicator_fn) (
19 const void *item);
20 // Compare two items, for sorting
22 typedef int (zhashx_comparator_fn) (
23 const void *item1, const void *item2);
24 // Destroy an item.
26 typedef void (zhashx_free_fn) (
27 void *data);
28 // Hash function for keys.
30 typedef size_t (zhashx_hash_fn) (
31 const void *key);
32 // Serializes an item to a longstr.
34 // The caller takes ownership of the newly created object.
35 typedef char * (zhashx_serializer_fn) (
36 const void *item);
37 // Deserializes a longstr into an item.
39 // The caller takes ownership of the newly created object.
40 typedef void * (zhashx_deserializer_fn) (
41 const char *item_str);
42 // Create a new, empty hash container
44 CZMQ_EXPORT zhashx_t *
45 zhashx_new (void);
46 // Unpack binary frame into a new hash table. Packed data must follow format
48 // defined by zhashx_pack. Hash table is set to autofree. An empty frame
49 // unpacks to an empty hash table.
50 CZMQ_EXPORT zhashx_t *
51 zhashx_unpack (zframe_t *frame);
52 // Destroy a hash container and all items in it
54 CZMQ_EXPORT void
55 zhashx_destroy (zhashx_t **self_p);
56 // Insert item into hash table with specified key and item.
58 // If key is already present returns -1 and leaves existing item unchanged
59 // Returns 0 on success.
60 CZMQ_EXPORT int
61 zhashx_insert (zhashx_t *self, const void *key, void *item);
62 // Update or insert item into hash table with specified key and item. If the
64 // key is already present, destroys old item and inserts new one. If you set
65 // a container item destructor, this is called on the old value. If the key
66 // was not already present, inserts a new item. Sets the hash cursor to the
67 // new item.
68 CZMQ_EXPORT void
69 zhashx_update (zhashx_t *self, const void *key, void *item);
70 // Remove an item specified by key from the hash table. If there was no such
72 // item, this function does nothing.
73 CZMQ_EXPORT void
74 zhashx_delete (zhashx_t *self, const void *key);
75 // Delete all items from the hash table. If the key destructor is
77 // set, calls it on every key. If the item destructor is set, calls
78 // it on every item.
79 CZMQ_EXPORT void
80 zhashx_purge (zhashx_t *self);
81 // Return the item at the specified key, or null
83 CZMQ_EXPORT void *
84 zhashx_lookup (zhashx_t *self, const void *key);
85 // Reindexes an item from an old key to a new key. If there was no such
87 // item, does nothing. Returns 0 if successful, else -1.
88 CZMQ_EXPORT int
89 zhashx_rename (zhashx_t *self, const void *old_key, const void *new_key);
90 // Set a free function for the specified hash table item. When the item is
92 // destroyed, the free function, if any, is called on that item.
93 // Use this when hash items are dynamically allocated, to ensure that
94 // you don't have memory leaks. You can pass 'free' or NULL as a free_fn.
95 // Returns the item, or NULL if there is no such item.
96 CZMQ_EXPORT void *
97 zhashx_freefn (zhashx_t *self, const void *key, zhashx_free_fn free_fn);
98 // Return the number of keys/items in the hash table
100 CZMQ_EXPORT size_t
101 zhashx_size (zhashx_t *self);
102 // Return a zlistx_t containing the keys for the items in the
104 // table. Uses the key_duplicator to duplicate all keys and sets the
105 // key_destructor as destructor for the list.
106 // Caller owns return value and must destroy it when done.
107 CZMQ_EXPORT zlistx_t *
108 zhashx_keys (zhashx_t *self);
109 // Return a zlistx_t containing the values for the items in the
111 // table. Uses the duplicator to duplicate all items and sets the
112 // destructor as destructor for the list.
113 // Caller owns return value and must destroy it when done.
114 CZMQ_EXPORT zlistx_t *
115 zhashx_values (zhashx_t *self);
116 // Simple iterator; returns first item in hash table, in no given order,
118 // or NULL if the table is empty. This method is simpler to use than the
119 // foreach() method, which is deprecated. To access the key for this item
120 // use zhashx_cursor(). NOTE: do NOT modify the table while iterating.
121 CZMQ_EXPORT void *
122 zhashx_first (zhashx_t *self);
123 // Simple iterator; returns next item in hash table, in no given order,
125 // or NULL if the last item was already returned. Use this together with
126 // zhashx_first() to process all items in a hash table. If you need the
127 // items in sorted order, use zhashx_keys() and then zlistx_sort(). To
128 // access the key for this item use zhashx_cursor(). NOTE: do NOT modify
129 // the table while iterating.
130 CZMQ_EXPORT void *
131 zhashx_next (zhashx_t *self);
132 // After a successful first/next method, returns the key for the item that
134 // was returned. This is a constant string that you may not modify or
135 // deallocate, and which lasts as long as the item in the hash. After an
136 // unsuccessful first/next, returns NULL.
137 CZMQ_EXPORT const void *
138 zhashx_cursor (zhashx_t *self);
139 // Add a comment to hash table before saving to disk. You can add as many
141 // comment lines as you like. These comment lines are discarded when loading
142 // the file. If you use a null format, all comments are deleted.
143 CZMQ_EXPORT void
144 zhashx_comment (zhashx_t *self, const char *format, ...) CHECK_PRINTF (2);
145 // Save hash table to a text file in name=value format. Hash values must be
147 // printable strings; keys may not contain '=' character. Returns 0 if OK,
148 // else -1 if a file error occurred.
149 CZMQ_EXPORT int
150 zhashx_save (zhashx_t *self, const char *filename);
151 // Load hash table from a text file in name=value format; hash table must
153 // already exist. Hash values must printable strings; keys may not contain
154 // '=' character. Returns 0 if OK, else -1 if a file was not readable.
155 CZMQ_EXPORT int
156 zhashx_load (zhashx_t *self, const char *filename);
157 // When a hash table was loaded from a file by zhashx_load, this method will
159 // reload the file if it has been modified since, and is "stable", i.e. not
160 // still changing. Returns 0 if OK, -1 if there was an error reloading the
161 // file.
162 CZMQ_EXPORT int
163 zhashx_refresh (zhashx_t *self);
164 // Serialize hash table to a binary frame that can be sent in a message.
166 // The packed format is compatible with the 'dictionary' type defined in
167 // http://rfc.zeromq.org/spec:35/FILEMQ, and implemented by zproto:
168 //
169 // ; A list of name/value pairs
170 // dictionary = dict-count *( dict-name dict-value )
171 // dict-count = number-4
172 // dict-value = longstr
173 // dict-name = string
174 //
175 // ; Strings are always length + text contents
176 // longstr = number-4 *VCHAR
177 // string = number-1 *VCHAR
178 //
179 // ; Numbers are unsigned integers in network byte order
180 // number-1 = 1OCTET
181 // number-4 = 4OCTET
182 //
183 // Comments are not included in the packed data. Item values MUST be
184 // strings.
185 // Caller owns return value and must destroy it when done.
186 CZMQ_EXPORT zframe_t *
187 zhashx_pack (zhashx_t *self);
188 // Make a copy of the list; items are duplicated if you set a duplicator
190 // for the list, otherwise not. Copying a null reference returns a null
191 // reference. Note that this method's behavior changed slightly for CZMQ
192 // v3.x, as it does not set nor respect autofree. It does however let you
193 // duplicate any hash table safely. The old behavior is in zhashx_dup_v2.
194 // Caller owns return value and must destroy it when done.
195 CZMQ_EXPORT zhashx_t *
196 zhashx_dup (zhashx_t *self);
197 // Set a user-defined deallocator for hash items; by default items are not
199 // freed when the hash is destroyed.
200 CZMQ_EXPORT void
201 zhashx_set_destructor (zhashx_t *self, zhashx_destructor_fn destructor);
202 // Set a user-defined duplicator for hash items; by default items are not
204 // copied when the hash is duplicated.
205 CZMQ_EXPORT void
206 zhashx_set_duplicator (zhashx_t *self, zhashx_duplicator_fn duplicator);
207 // Set a user-defined deallocator for keys; by default keys are freed
209 // when the hash is destroyed using free().
210 CZMQ_EXPORT void
211 zhashx_set_key_destructor (zhashx_t *self, zhashx_destructor_fn destructor);
212 // Set a user-defined duplicator for keys; by default keys are duplicated
214 // using strdup.
215 CZMQ_EXPORT void
216 zhashx_set_key_duplicator (zhashx_t *self, zhashx_duplicator_fn duplicator);
217 // Set a user-defined comparator for keys; by default keys are
219 // compared using strcmp.
220 // The callback function should return zero (0) on matching
221 // items.
222 CZMQ_EXPORT void
223 zhashx_set_key_comparator (zhashx_t *self, zhashx_comparator_fn comparator);
224 // Set a user-defined hash function for keys; by default keys are
226 // hashed by a modified Bernstein hashing function.
227 CZMQ_EXPORT void
228 zhashx_set_key_hasher (zhashx_t *self, zhashx_hash_fn hasher);
229 // Make copy of hash table; if supplied table is null, returns null.
231 // Does not copy items themselves. Rebuilds new table so may be slow on
232 // very large tables. NOTE: only works with item values that are strings
233 // since there's no other way to know how to duplicate the item value.
234 CZMQ_EXPORT zhashx_t *
235 zhashx_dup_v2 (zhashx_t *self);
236 // Self test of this class.
238 CZMQ_EXPORT void
239 zhashx_test (bool verbose);
240 #ifdef CZMQ_BUILD_DRAFT_API
242 // *** Draft method, for development use, may change without warning ***
243 // Same as unpack but uses a user-defined deserializer function to convert
244 // a longstr back into item format.
245 CZMQ_EXPORT zhashx_t *
246 zhashx_unpack_own (zframe_t *frame, zhashx_deserializer_fn deserializer);
247 // *** Draft method, for development use, may change without warning ***
249 // Same as pack but uses a user-defined serializer function to convert items
250 // into longstr.
251 // Caller owns return value and must destroy it when done.
252 CZMQ_EXPORT zframe_t *
253 zhashx_pack_own (zhashx_t *self, zhashx_serializer_fn serializer);
254 #endif // CZMQ_BUILD_DRAFT_API
256 Please add '@interface' section in './../src/zhashx.c'.
257
259 zhashx is an extended hash table container with more functionality than
260 zhash, its simpler cousin.
261 The hash table always has a size that is prime and roughly doubles its
263 size when 75% full. In case of hash collisions items are chained in a
264 linked list. The hash table size is increased slightly (up to 5 times
265 before roughly doubling the size) when an overly long chain (between 1
266 and 63 items depending on table size) is detected.
267
269 From zhashx_test method.
270 zhashx_t *hash = zhashx_new ();
272 assert (hash);
273 assert (zhashx_size (hash) == 0);
274 assert (zhashx_first (hash) == NULL);
275 assert (zhashx_cursor (hash) == NULL);
276 // Insert some items
278 int rc;
279 rc = zhashx_insert (hash, "DEADBEEF", "dead beef");
280 char *item = (char *) zhashx_first (hash);
281 assert (streq ((char *) zhashx_cursor (hash), "DEADBEEF"));
282 assert (streq (item, "dead beef"));
283 assert (rc == 0);
284 rc = zhashx_insert (hash, "ABADCAFE", "a bad cafe");
285 assert (rc == 0);
286 rc = zhashx_insert (hash, "C0DEDBAD", "coded bad");
287 assert (rc == 0);
288 rc = zhashx_insert (hash, "DEADF00D", "dead food");
289 assert (rc == 0);
290 assert (zhashx_size (hash) == 4);
291 // Look for existing items
293 item = (char *) zhashx_lookup (hash, "DEADBEEF");
294 assert (streq (item, "dead beef"));
295 item = (char *) zhashx_lookup (hash, "ABADCAFE");
296 assert (streq (item, "a bad cafe"));
297 item = (char *) zhashx_lookup (hash, "C0DEDBAD");
298 assert (streq (item, "coded bad"));
299 item = (char *) zhashx_lookup (hash, "DEADF00D");
300 assert (streq (item, "dead food"));
301 // Look for non-existent items
303 item = (char *) zhashx_lookup (hash, "foo");
304 assert (item == NULL);
305 // Try to insert duplicate items
307 rc = zhashx_insert (hash, "DEADBEEF", "foo");
308 assert (rc == -1);
309 item = (char *) zhashx_lookup (hash, "DEADBEEF");
310 assert (streq (item, "dead beef"));
311 // Some rename tests
313 // Valid rename, key is now LIVEBEEF
315 rc = zhashx_rename (hash, "DEADBEEF", "LIVEBEEF");
316 assert (rc == 0);
317 item = (char *) zhashx_lookup (hash, "LIVEBEEF");
318 assert (streq (item, "dead beef"));
319 // Trying to rename an unknown item to a non-existent key
321 rc = zhashx_rename (hash, "WHATBEEF", "NONESUCH");
322 assert (rc == -1);
323 // Trying to rename an unknown item to an existing key
325 rc = zhashx_rename (hash, "WHATBEEF", "LIVEBEEF");
326 assert (rc == -1);
327 item = (char *) zhashx_lookup (hash, "LIVEBEEF");
328 assert (streq (item, "dead beef"));
329 // Trying to rename an existing item to another existing item
331 rc = zhashx_rename (hash, "LIVEBEEF", "ABADCAFE");
332 assert (rc == -1);
333 item = (char *) zhashx_lookup (hash, "LIVEBEEF");
334 assert (streq (item, "dead beef"));
335 item = (char *) zhashx_lookup (hash, "ABADCAFE");
336 assert (streq (item, "a bad cafe"));
337 // Test keys method
339 zlistx_t *keys = zhashx_keys (hash);
340 assert (zlistx_size (keys) == 4);
341 zlistx_destroy (&keys);
342 zlistx_t *values = zhashx_values (hash);
344 assert (zlistx_size (values) == 4);
345 zlistx_destroy (&values);
346 // Test dup method
348 zhashx_t *copy = zhashx_dup (hash);
349 assert (zhashx_size (copy) == 4);
350 item = (char *) zhashx_lookup (copy, "LIVEBEEF");
351 assert (item);
352 assert (streq (item, "dead beef"));
353 zhashx_destroy (©);
354 // Test pack/unpack methods
356 zframe_t *frame = zhashx_pack (hash);
357 copy = zhashx_unpack (frame);
358 zframe_destroy (&frame);
359 assert (zhashx_size (copy) == 4);
360 item = (char *) zhashx_lookup (copy, "LIVEBEEF");
361 assert (item);
362 assert (streq (item, "dead beef"));
363 zhashx_destroy (©);
364 #ifdef CZMQ_BUILD_DRAFT_API
366 // Test own pack/unpack methods
367 zhashx_t *own_hash = zhashx_new ();
368 zhashx_set_destructor (own_hash, s_test_destroy_int);
369 assert (own_hash);
370 int *val1 = (int *) zmalloc (sizeof (int));
371 int *val2 = (int *) zmalloc (sizeof (int));
372 *val1 = 25;
373 *val2 = 100;
374 zhashx_insert (own_hash, "val1", val1);
375 zhashx_insert (own_hash, "val2", val2);
376 frame = zhashx_pack_own (own_hash, s_test_serialize_int);
377 copy = zhashx_unpack_own (frame, s_test_deserialze_int);
378 zhashx_set_destructor (copy, s_test_destroy_int);
379 zframe_destroy (&frame);
380 assert (zhashx_size (copy) == 2);
381 assert (*((int *) zhashx_lookup (copy, "val1")) == 25);
382 assert (*((int *) zhashx_lookup (copy, "val2")) == 100);
383 zhashx_destroy (©);
384 zhashx_destroy (&own_hash);
385 #endif // CZMQ_BUILD_DRAFT_API
386 // Test save and load
388 zhashx_comment (hash, "This is a test file");
389 zhashx_comment (hash, "Created by %s", "czmq_selftest");
390 zhashx_save (hash, ".cache");
391 copy = zhashx_new ();
392 assert (copy);
393 zhashx_load (copy, ".cache");
394 item = (char *) zhashx_lookup (copy, "LIVEBEEF");
395 assert (item);
396 assert (streq (item, "dead beef"));
397 zhashx_destroy (©);
398 zsys_file_delete (".cache");
399 // Delete a item
401 zhashx_delete (hash, "LIVEBEEF");
402 item = (char *) zhashx_lookup (hash, "LIVEBEEF");
403 assert (item == NULL);
404 assert (zhashx_size (hash) == 3);
405 // Check that the queue is robust against random usage
407 struct {
408 char name [100];
409 bool exists;
410 } testset [200];
411 memset (testset, 0, sizeof (testset));
412 int testmax = 200, testnbr, iteration;
413 srandom ((unsigned) time (NULL));
415 for (iteration = 0; iteration < 25000; iteration++) {
416 testnbr = randof (testmax);
417 assert (testnbr != testmax);
418 assert (testnbr < testmax);
419 if (testset [testnbr].exists) {
420 item = (char *) zhashx_lookup (hash, testset [testnbr].name);
421 assert (item);
422 zhashx_delete (hash, testset [testnbr].name);
423 testset [testnbr].exists = false;
424 }
425 else {
426 sprintf (testset [testnbr].name, "%x-%x", rand (), rand ());
427 if (zhashx_insert (hash, testset [testnbr].name, "") == 0)
428 testset [testnbr].exists = true;
429 }
430 }
431 // Test 10K lookups
432 for (iteration = 0; iteration < 10000; iteration++)
433 item = (char *) zhashx_lookup (hash, "DEADBEEFABADCAFE");
434 // Destructor should be safe to call twice
436 zhashx_destroy (&hash);
437 zhashx_destroy (&hash);
438 assert (hash == NULL);
439 // Test randof() limits - should be within (0..testmax)
441 // and randomness distribution - should not have (many) zero-counts
442 // If there are - maybe the ZSYS_RANDOF_MAX is too big for this platform
443 // Note: This test can take a while on systems with weak floating point HW
444 testmax = 999;
445 size_t rndcnt[999];
446 assert ((sizeof (rndcnt)/sizeof(rndcnt[0])) == testmax);
447 memset (rndcnt, 0, sizeof (rndcnt));
448 for (iteration = 0; iteration < 10000000; iteration++) {
449 testnbr = randof (testmax);
450 assert (testnbr != testmax);
451 assert (testnbr < testmax);
452 assert (testnbr >= 0);
453 rndcnt[testnbr]++;
454 }
455 int rndmisses = 0;
456 for (iteration = 0; iteration < testmax; iteration++) {
457 if (rndcnt[iteration] == 0) {
458 zsys_warning("zhashx_test() : random distribution fault : got 0 hits for %d/%d",
459 iteration, testmax);
460 rndmisses++;
461 }
462 }
463 // Too many misses are suspicious... we can lose half the entries
464 // for each bit not used in the assumed ZSYS_RANDOF_MAX...
465 assert ( (rndmisses < (testmax / 3 )) );
466 // Test destructor; automatically copies and frees string values
468 hash = zhashx_new ();
469 assert (hash);
470 zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free);
471 zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup);
472 char value [255];
473 strcpy (value, "This is a string");
474 rc = zhashx_insert (hash, "key1", value);
475 assert (rc == 0);
476 strcpy (value, "Ring a ding ding");
477 rc = zhashx_insert (hash, "key2", value);
478 assert (rc == 0);
479 assert (streq ((char *) zhashx_lookup (hash, "key1"), "This is a string"));
480 assert (streq ((char *) zhashx_lookup (hash, "key2"), "Ring a ding ding"));
481 zhashx_destroy (&hash);
482 // Test purger and shrinker: no data should end up unreferenced in valgrind
484 hash = zhashx_new ();
485 assert (hash);
486 zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free);
487 zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup);
488 char valuep [255];
489 strcpy (valuep, "This is a string");
490 rc = zhashx_insert (hash, "key1", valuep);
491 assert (rc == 0);
492 strcpy (valuep, "Ring a ding ding");
493 rc = zhashx_insert (hash, "key2", valuep);
494 assert (rc == 0);
495 strcpy (valuep, "Cartahena delenda est");
496 rc = zhashx_insert (hash, "key3", valuep);
497 assert (rc == 0);
498 strcpy (valuep, "So say we all!");
499 rc = zhashx_insert (hash, "key4", valuep);
500 assert (rc == 0);
501 assert (streq ((char *) zhashx_lookup (hash, "key1"), "This is a string"));
502 assert (streq ((char *) zhashx_lookup (hash, "key2"), "Ring a ding ding"));
503 assert (streq ((char *) zhashx_lookup (hash, "key3"), "Cartahena delenda est"));
504 assert (streq ((char *) zhashx_lookup (hash, "key4"), "So say we all!"));
505 zhashx_purge (hash);
506 zhashx_destroy (&hash);
507 #if defined (__WINDOWS__)
509 zsys_shutdown();
510 #endif
511
514 The czmq manual was written by the authors in the AUTHORS file.
515
517 Main web site:
518 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
520
522 Copyright (c) the Contributors as noted in the AUTHORS file. This file
523 is part of CZMQ, the high-level C binding for 0MQ:
524 http://czmq.zeromq.org. This Source Code Form is subject to the terms
525 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
526 distributed with this file, You can obtain one at
527 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
528 distribution.
529
531 1. zeromq-dev@lists.zeromq.org
532 mailto:zeromq-dev@lists.zeromq.org
533CZMQ 4.2.1 07/19/2023 ZHASHX(3)