1ZHASHX(3)                         CZMQ Manual                        ZHASHX(3)
2
3
4

NAME

6       zhashx - extended generic hash container
7

SYNOPSIS

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
17       // Duplicate an item
18       typedef void * (zhashx_duplicator_fn) (
19           const void *item);
20
21       // Compare two items, for sorting
22       typedef int (zhashx_comparator_fn) (
23           const void *item1, const void *item2);
24
25       // compare two items, for sorting
26       typedef void (zhashx_free_fn) (
27           void *data);
28
29       // compare two items, for sorting
30       typedef size_t (zhashx_hash_fn) (
31           const void *key);
32
33       // 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
38       // 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
43       //  Create a new, empty hash container
44       CZMQ_EXPORT zhashx_t *
45           zhashx_new (void);
46
47       //  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
53       //  Destroy a hash container and all items in it
54       CZMQ_EXPORT void
55           zhashx_destroy (zhashx_t **self_p);
56
57       //  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
63       //  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
71       //  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
76       //  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
82       //  Return the item at the specified key, or null
83       CZMQ_EXPORT void *
84           zhashx_lookup (zhashx_t *self, const void *key);
85
86       //  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
91       //  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
99       //  Return the number of keys/items in the hash table
100       CZMQ_EXPORT size_t
101           zhashx_size (zhashx_t *self);
102
103       //  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
110       //  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
117       //  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
124       //  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
133       //  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
140       //  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
146       //  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
152       //  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
158       //  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
165       //  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
189       //  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
198       //  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
203       //  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
208       //  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
213       //  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
218       //  Set a user-defined comparator for keys; by default keys are
219       //  compared using strcmp.
220       CZMQ_EXPORT void
221           zhashx_set_key_comparator (zhashx_t *self, zhashx_comparator_fn comparator);
222
223       //  Set a user-defined comparator for keys; by default keys are
224       //  compared using strcmp.
225       CZMQ_EXPORT void
226           zhashx_set_key_hasher (zhashx_t *self, zhashx_hash_fn hasher);
227
228       //  Make copy of hash table; if supplied table is null, returns null.
229       //  Does not copy items themselves. Rebuilds new table so may be slow on
230       //  very large tables. NOTE: only works with item values that are strings
231       //  since there's no other way to know how to duplicate the item value.
232       CZMQ_EXPORT zhashx_t *
233           zhashx_dup_v2 (zhashx_t *self);
234
235       //  Self test of this class.
236       CZMQ_EXPORT void
237           zhashx_test (bool verbose);
238
239       #ifdef CZMQ_BUILD_DRAFT_API
240       //  *** Draft method, for development use, may change without warning ***
241       //  Same as unpack but uses a user-defined deserializer function to convert
242       //  a longstr back into item format.
243       CZMQ_EXPORT zhashx_t *
244           zhashx_unpack_own (zframe_t *frame, zhashx_deserializer_fn deserializer);
245
246       //  *** Draft method, for development use, may change without warning ***
247       //  Same as pack but uses a user-defined serializer function to convert items
248       //  into longstr.
249       //  Caller owns return value and must destroy it when done.
250       CZMQ_EXPORT zframe_t *
251           zhashx_pack_own (zhashx_t *self, zhashx_serializer_fn serializer);
252
253       #endif // CZMQ_BUILD_DRAFT_API
254       Please add '@interface' section in './../src/zhashx.c'.
255

DESCRIPTION

257       zhashx is an extended hash table container with more functionality than
258       zhash, its simpler cousin.
259
260       The hash table always has a size that is prime and roughly doubles its
261       size when 75% full. In case of hash collisions items are chained in a
262       linked list. The hash table size is increased slightly (up to 5 times
263       before roughly doubling the size) when an overly long chain (between 1
264       and 63 items depending on table size) is detected.
265

EXAMPLE

267       From zhashx_test method.
268
269           zhashx_t *hash = zhashx_new ();
270           assert (hash);
271           assert (zhashx_size (hash) == 0);
272           assert (zhashx_first (hash) == NULL);
273           assert (zhashx_cursor (hash) == NULL);
274
275           //  Insert some items
276           int rc;
277           rc = zhashx_insert (hash, "DEADBEEF", "dead beef");
278           char *item = (char *) zhashx_first (hash);
279           assert (streq ((char *) zhashx_cursor (hash), "DEADBEEF"));
280           assert (streq (item, "dead beef"));
281           assert (rc == 0);
282           rc = zhashx_insert (hash, "ABADCAFE", "a bad cafe");
283           assert (rc == 0);
284           rc = zhashx_insert (hash, "C0DEDBAD", "coded bad");
285           assert (rc == 0);
286           rc = zhashx_insert (hash, "DEADF00D", "dead food");
287           assert (rc == 0);
288           assert (zhashx_size (hash) == 4);
289
290           //  Look for existing items
291           item = (char *) zhashx_lookup (hash, "DEADBEEF");
292           assert (streq (item, "dead beef"));
293           item = (char *) zhashx_lookup (hash, "ABADCAFE");
294           assert (streq (item, "a bad cafe"));
295           item = (char *) zhashx_lookup (hash, "C0DEDBAD");
296           assert (streq (item, "coded bad"));
297           item = (char *) zhashx_lookup (hash, "DEADF00D");
298           assert (streq (item, "dead food"));
299
300           //  Look for non-existent items
301           item = (char *) zhashx_lookup (hash, "foo");
302           assert (item == NULL);
303
304           //  Try to insert duplicate items
305           rc = zhashx_insert (hash, "DEADBEEF", "foo");
306           assert (rc == -1);
307           item = (char *) zhashx_lookup (hash, "DEADBEEF");
308           assert (streq (item, "dead beef"));
309
310           //  Some rename tests
311
312           //  Valid rename, key is now LIVEBEEF
313           rc = zhashx_rename (hash, "DEADBEEF", "LIVEBEEF");
314           assert (rc == 0);
315           item = (char *) zhashx_lookup (hash, "LIVEBEEF");
316           assert (streq (item, "dead beef"));
317
318           //  Trying to rename an unknown item to a non-existent key
319           rc = zhashx_rename (hash, "WHATBEEF", "NONESUCH");
320           assert (rc == -1);
321
322           //  Trying to rename an unknown item to an existing key
323           rc = zhashx_rename (hash, "WHATBEEF", "LIVEBEEF");
324           assert (rc == -1);
325           item = (char *) zhashx_lookup (hash, "LIVEBEEF");
326           assert (streq (item, "dead beef"));
327
328           //  Trying to rename an existing item to another existing item
329           rc = zhashx_rename (hash, "LIVEBEEF", "ABADCAFE");
330           assert (rc == -1);
331           item = (char *) zhashx_lookup (hash, "LIVEBEEF");
332           assert (streq (item, "dead beef"));
333           item = (char *) zhashx_lookup (hash, "ABADCAFE");
334           assert (streq (item, "a bad cafe"));
335
336           //  Test keys method
337           zlistx_t *keys = zhashx_keys (hash);
338           assert (zlistx_size (keys) == 4);
339           zlistx_destroy (&keys);
340
341           zlistx_t *values = zhashx_values(hash);
342           assert (zlistx_size (values) == 4);
343           zlistx_destroy (&values);
344
345           //  Test dup method
346           zhashx_t *copy = zhashx_dup (hash);
347           assert (zhashx_size (copy) == 4);
348           item = (char *) zhashx_lookup (copy, "LIVEBEEF");
349           assert (item);
350           assert (streq (item, "dead beef"));
351           zhashx_destroy (&copy);
352
353           //  Test pack/unpack methods
354           zframe_t *frame = zhashx_pack (hash);
355           copy = zhashx_unpack (frame);
356           zframe_destroy (&frame);
357           assert (zhashx_size (copy) == 4);
358           item = (char *) zhashx_lookup (copy, "LIVEBEEF");
359           assert (item);
360           assert (streq (item, "dead beef"));
361           zhashx_destroy (&copy);
362
363           #ifdef CZMQ_BUILD_DRAFT_API
364           //  Test own pack/unpack methods
365           zhashx_t *own_hash = zhashx_new ();
366           zhashx_set_destructor (own_hash, s_test_destroy_int);
367           assert (own_hash);
368           int *val1 = (int *) zmalloc (sizeof (int));
369           int *val2 = (int *) zmalloc (sizeof (int));
370           *val1 = 25;
371           *val2 = 100;
372           zhashx_insert (own_hash, "val1", val1);
373           zhashx_insert (own_hash, "val2", val2);
374           frame = zhashx_pack_own (own_hash, s_test_serialize_int);
375           copy = zhashx_unpack_own (frame, s_test_deserialze_int);
376           zhashx_set_destructor (copy, s_test_destroy_int);
377           zframe_destroy (&frame);
378           assert (zhashx_size (copy) == 2);
379           assert (*((int *) zhashx_lookup (copy, "val1")) == 25);
380           assert (*((int *) zhashx_lookup (copy, "val2")) == 100);
381           zhashx_destroy (&copy);
382           zhashx_destroy (&own_hash);
383           #endif // CZMQ_BUILD_DRAFT_API
384
385           //  Test save and load
386           zhashx_comment (hash, "This is a test file");
387           zhashx_comment (hash, "Created by %s", "czmq_selftest");
388           zhashx_save (hash, ".cache");
389           copy = zhashx_new ();
390           assert (copy);
391           zhashx_load (copy, ".cache");
392           item = (char *) zhashx_lookup (copy, "LIVEBEEF");
393           assert (item);
394           assert (streq (item, "dead beef"));
395           zhashx_destroy (&copy);
396           zsys_file_delete (".cache");
397
398           //  Delete a item
399           zhashx_delete (hash, "LIVEBEEF");
400           item = (char *) zhashx_lookup (hash, "LIVEBEEF");
401           assert (item == NULL);
402           assert (zhashx_size (hash) == 3);
403
404           //  Check that the queue is robust against random usage
405           struct {
406               char name [100];
407               bool exists;
408           } testset [200];
409           memset (testset, 0, sizeof (testset));
410           int testmax = 200, testnbr, iteration;
411
412           srandom ((unsigned) time (NULL));
413           for (iteration = 0; iteration < 25000; iteration++) {
414               testnbr = randof (testmax);
415               if (testset [testnbr].exists) {
416                   item = (char *) zhashx_lookup (hash, testset [testnbr].name);
417                   assert (item);
418                   zhashx_delete (hash, testset [testnbr].name);
419                   testset [testnbr].exists = false;
420               }
421               else {
422                   sprintf (testset [testnbr].name, "%x-%x", rand (), rand ());
423                   if (zhashx_insert (hash, testset [testnbr].name, "") == 0)
424                       testset [testnbr].exists = true;
425               }
426           }
427           //  Test 10K lookups
428           for (iteration = 0; iteration < 10000; iteration++)
429               item = (char *) zhashx_lookup (hash, "DEADBEEFABADCAFE");
430
431           //  Destructor should be safe to call twice
432           zhashx_destroy (&hash);
433           zhashx_destroy (&hash);
434           assert (hash == NULL);
435
436           //  Test destructor; automatically copies and frees string values
437           hash = zhashx_new ();
438           assert (hash);
439           zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free);
440           zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup);
441           char value [255];
442           strcpy (value, "This is a string");
443           rc = zhashx_insert (hash, "key1", value);
444           assert (rc == 0);
445           strcpy (value, "Ring a ding ding");
446           rc = zhashx_insert (hash, "key2", value);
447           assert (rc == 0);
448           assert (streq ((char *) zhashx_lookup (hash, "key1"), "This is a string"));
449           assert (streq ((char *) zhashx_lookup (hash, "key2"), "Ring a ding ding"));
450           zhashx_destroy (&hash);
451
452

AUTHORS

454       The czmq manual was written by the authors in the AUTHORS file.
455

RESOURCES

457       Main web site:
458
459       Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
460
462       Copyright (c) the Contributors as noted in the AUTHORS file. This file
463       is part of CZMQ, the high-level C binding for 0MQ:
464       http://czmq.zeromq.org. This Source Code Form is subject to the terms
465       of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
466       distributed with this file, You can obtain one at
467       http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
468       distribution.
469

NOTES

471        1. zeromq-dev@lists.zeromq.org
472           mailto:zeromq-dev@lists.zeromq.org
473
474
475
476CZMQ 4.0.2                        12/31/2016                         ZHASHX(3)
Impressum