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

NAME

6       zhash - Class for simple 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       // Callback function for zhash_freefn method
12       typedef void (zhash_free_fn) (
13           void *data);
14
15       //  Create a new, empty hash container
16       CZMQ_EXPORT zhash_t *
17           zhash_new (void);
18
19       //  Unpack binary frame into a new hash table. Packed data must follow format
20       //  defined by zhash_pack. Hash table is set to autofree. An empty frame
21       //  unpacks to an empty hash table.
22       CZMQ_EXPORT zhash_t *
23           zhash_unpack (zframe_t *frame);
24
25       //  Destroy a hash container and all items in it
26       CZMQ_EXPORT void
27           zhash_destroy (zhash_t **self_p);
28
29       //  Insert item into hash table with specified key and item.
30       //  If key is already present returns -1 and leaves existing item unchanged
31       //  Returns 0 on success.
32       CZMQ_EXPORT int
33           zhash_insert (zhash_t *self, const char *key, void *item);
34
35       //  Update item into hash table with specified key and item.
36       //  If key is already present, destroys old item and inserts new one.
37       //  Use free_fn method to ensure deallocator is properly called on item.
38       CZMQ_EXPORT void
39           zhash_update (zhash_t *self, const char *key, void *item);
40
41       //  Remove an item specified by key from the hash table. If there was no such
42       //  item, this function does nothing.
43       CZMQ_EXPORT void
44           zhash_delete (zhash_t *self, const char *key);
45
46       //  Return the item at the specified key, or null
47       CZMQ_EXPORT void *
48           zhash_lookup (zhash_t *self, const char *key);
49
50       //  Reindexes an item from an old key to a new key. If there was no such
51       //  item, does nothing. Returns 0 if successful, else -1.
52       CZMQ_EXPORT int
53           zhash_rename (zhash_t *self, const char *old_key, const char *new_key);
54
55       //  Set a free function for the specified hash table item. When the item is
56       //  destroyed, the free function, if any, is called on that item.
57       //  Use this when hash items are dynamically allocated, to ensure that
58       //  you don't have memory leaks. You can pass 'free' or NULL as a free_fn.
59       //  Returns the item, or NULL if there is no such item.
60       CZMQ_EXPORT void *
61           zhash_freefn (zhash_t *self, const char *key, zhash_free_fn free_fn);
62
63       //  Return the number of keys/items in the hash table
64       CZMQ_EXPORT size_t
65           zhash_size (zhash_t *self);
66
67       //  Make copy of hash table; if supplied table is null, returns null.
68       //  Does not copy items themselves. Rebuilds new table so may be slow on
69       //  very large tables. NOTE: only works with item values that are strings
70       //  since there's no other way to know how to duplicate the item value.
71       //  Caller owns return value and must destroy it when done.
72       CZMQ_EXPORT zhash_t *
73           zhash_dup (zhash_t *self);
74
75       //  Return keys for items in table
76       //  Caller owns return value and must destroy it when done.
77       CZMQ_EXPORT zlist_t *
78           zhash_keys (zhash_t *self);
79
80       //  Simple iterator; returns first item in hash table, in no given order,
81       //  or NULL if the table is empty. This method is simpler to use than the
82       //  foreach() method, which is deprecated. To access the key for this item
83       //  use zhash_cursor(). NOTE: do NOT modify the table while iterating.
84       CZMQ_EXPORT void *
85           zhash_first (zhash_t *self);
86
87       //  Simple iterator; returns next item in hash table, in no given order,
88       //  or NULL if the last item was already returned. Use this together with
89       //  zhash_first() to process all items in a hash table. If you need the
90       //  items in sorted order, use zhash_keys() and then zlist_sort(). To
91       //  access the key for this item use zhash_cursor(). NOTE: do NOT modify
92       //  the table while iterating.
93       CZMQ_EXPORT void *
94           zhash_next (zhash_t *self);
95
96       //  After a successful first/next method, returns the key for the item that
97       //  was returned. This is a constant string that you may not modify or
98       //  deallocate, and which lasts as long as the item in the hash. After an
99       //  unsuccessful first/next, returns NULL.
100       CZMQ_EXPORT const char *
101           zhash_cursor (zhash_t *self);
102
103       //  Add a comment to hash table before saving to disk. You can add as many
104       //  comment lines as you like. These comment lines are discarded when loading
105       //  the file. If you use a null format, all comments are deleted.
106       CZMQ_EXPORT void
107           zhash_comment (zhash_t *self, const char *format, ...) CHECK_PRINTF (2);
108
109       //  Serialize hash table to a binary frame that can be sent in a message.
110       //  The packed format is compatible with the 'dictionary' type defined in
111       //  http://rfc.zeromq.org/spec:35/FILEMQ, and implemented by zproto:
112       //
113       //     ; A list of name/value pairs
114       //     dictionary      = dict-count *( dict-name dict-value )
115       //     dict-count      = number-4
116       //     dict-value      = longstr
117       //     dict-name       = string
118       //
119       //     ; Strings are always length + text contents
120       //     longstr         = number-4 *VCHAR
121       //     string          = number-1 *VCHAR
122       //
123       //     ; Numbers are unsigned integers in network byte order
124       //     number-1        = 1OCTET
125       //     number-4        = 4OCTET
126       //
127       //  Comments are not included in the packed data. Item values MUST be
128       //  strings.
129       //  Caller owns return value and must destroy it when done.
130       CZMQ_EXPORT zframe_t *
131           zhash_pack (zhash_t *self);
132
133       //  Save hash table to a text file in name=value format. Hash values must be
134       //  printable strings; keys may not contain '=' character. Returns 0 if OK,
135       //  else -1 if a file error occurred.
136       CZMQ_EXPORT int
137           zhash_save (zhash_t *self, const char *filename);
138
139       //  Load hash table from a text file in name=value format; hash table must
140       //  already exist. Hash values must printable strings; keys may not contain
141       //  '=' character. Returns 0 if OK, else -1 if a file was not readable.
142       CZMQ_EXPORT int
143           zhash_load (zhash_t *self, const char *filename);
144
145       //  When a hash table was loaded from a file by zhash_load, this method will
146       //  reload the file if it has been modified since, and is "stable", i.e. not
147       //  still changing. Returns 0 if OK, -1 if there was an error reloading the
148       //  file.
149       CZMQ_EXPORT int
150           zhash_refresh (zhash_t *self);
151
152       //  Set hash for automatic value destruction. Note that this assumes that
153       //  values are NULL-terminated strings. Do not use with different types.
154       CZMQ_EXPORT void
155           zhash_autofree (zhash_t *self);
156
157       //  Self test of this class.
158       CZMQ_EXPORT void
159           zhash_test (bool verbose);
160
161       Please add '@interface' section in './../src/zhash.c'.
162

DESCRIPTION

164       zhash is an expandable hash table container. This is a simple
165       container. For heavy-duty applications we recommend using zhashx.
166
167       Note that it’s relatively slow (50K insertions/deletes per second), so
168       don’t do inserts/updates on the critical path for message I/O. It can
169       do 2.5M lookups per second for 16-char keys. Timed on a 1.6GHz CPU.
170

EXAMPLE

172       From zhash_test method.
173
174           zhash_t *hash = zhash_new ();
175           assert (hash);
176           assert (zhash_size (hash) == 0);
177           assert (zhash_first (hash) == NULL);
178           assert (zhash_cursor (hash) == NULL);
179
180           //  Insert some items
181           int rc;
182           rc = zhash_insert (hash, "DEADBEEF", "dead beef");
183           char *item = (char *) zhash_first (hash);
184           assert (streq (zhash_cursor (hash), "DEADBEEF"));
185           assert (streq (item, "dead beef"));
186           assert (rc == 0);
187           rc = zhash_insert (hash, "ABADCAFE", "a bad cafe");
188           assert (rc == 0);
189           rc = zhash_insert (hash, "C0DEDBAD", "coded bad");
190           assert (rc == 0);
191           rc = zhash_insert (hash, "DEADF00D", "dead food");
192           assert (rc == 0);
193           assert (zhash_size (hash) == 4);
194
195           //  Look for existing items
196           item = (char *) zhash_lookup (hash, "DEADBEEF");
197           assert (streq (item, "dead beef"));
198           item = (char *) zhash_lookup (hash, "ABADCAFE");
199           assert (streq (item, "a bad cafe"));
200           item = (char *) zhash_lookup (hash, "C0DEDBAD");
201           assert (streq (item, "coded bad"));
202           item = (char *) zhash_lookup (hash, "DEADF00D");
203           assert (streq (item, "dead food"));
204
205           //  Look for non-existent items
206           item = (char *) zhash_lookup (hash, "foo");
207           assert (item == NULL);
208
209           //  Try to insert duplicate items
210           rc = zhash_insert (hash, "DEADBEEF", "foo");
211           assert (rc == -1);
212           item = (char *) zhash_lookup (hash, "DEADBEEF");
213           assert (streq (item, "dead beef"));
214
215           //  Some rename tests
216
217           //  Valid rename, key is now LIVEBEEF
218           rc = zhash_rename (hash, "DEADBEEF", "LIVEBEEF");
219           assert (rc == 0);
220           item = (char *) zhash_lookup (hash, "LIVEBEEF");
221           assert (streq (item, "dead beef"));
222
223           //  Trying to rename an unknown item to a non-existent key
224           rc = zhash_rename (hash, "WHATBEEF", "NONESUCH");
225           assert (rc == -1);
226
227           //  Trying to rename an unknown item to an existing key
228           rc = zhash_rename (hash, "WHATBEEF", "LIVEBEEF");
229           assert (rc == -1);
230           item = (char *) zhash_lookup (hash, "LIVEBEEF");
231           assert (streq (item, "dead beef"));
232
233           //  Trying to rename an existing item to another existing item
234           rc = zhash_rename (hash, "LIVEBEEF", "ABADCAFE");
235           assert (rc == -1);
236           item = (char *) zhash_lookup (hash, "LIVEBEEF");
237           assert (streq (item, "dead beef"));
238           item = (char *) zhash_lookup (hash, "ABADCAFE");
239           assert (streq (item, "a bad cafe"));
240
241           //  Test keys method
242           zlist_t *keys = zhash_keys (hash);
243           assert (zlist_size (keys) == 4);
244           zlist_destroy (&keys);
245
246           //  Test dup method
247           zhash_t *copy = zhash_dup (hash);
248           assert (zhash_size (copy) == 4);
249           item = (char *) zhash_lookup (copy, "LIVEBEEF");
250           assert (item);
251           assert (streq (item, "dead beef"));
252           zhash_destroy (&copy);
253
254           //  Test pack/unpack methods
255           zframe_t *frame = zhash_pack (hash);
256           copy = zhash_unpack (frame);
257           zframe_destroy (&frame);
258           assert (zhash_size (copy) == 4);
259           item = (char *) zhash_lookup (copy, "LIVEBEEF");
260           assert (item);
261           assert (streq (item, "dead beef"));
262           zhash_destroy (&copy);
263
264           //  Test save and load
265           zhash_comment (hash, "This is a test file");
266           zhash_comment (hash, "Created by %s", "czmq_selftest");
267           zhash_save (hash, ".cache");
268           copy = zhash_new ();
269           assert (copy);
270           zhash_load (copy, ".cache");
271           item = (char *) zhash_lookup (copy, "LIVEBEEF");
272           assert (item);
273           assert (streq (item, "dead beef"));
274           zhash_destroy (&copy);
275           zsys_file_delete (".cache");
276
277           //  Delete a item
278           zhash_delete (hash, "LIVEBEEF");
279           item = (char *) zhash_lookup (hash, "LIVEBEEF");
280           assert (item == NULL);
281           assert (zhash_size (hash) == 3);
282
283           //  Check that the queue is robust against random usage
284           struct {
285               char name [100];
286               bool exists;
287           } testset [200];
288           memset (testset, 0, sizeof (testset));
289           int testmax = 200, testnbr, iteration;
290
291           srandom ((unsigned) time (NULL));
292           for (iteration = 0; iteration < 25000; iteration++) {
293               testnbr = randof (testmax);
294               assert (testnbr != testmax);
295               assert (testnbr < testmax);
296               if (testset [testnbr].exists) {
297                   item = (char *) zhash_lookup (hash, testset [testnbr].name);
298                   assert (item);
299                   zhash_delete (hash, testset [testnbr].name);
300                   testset [testnbr].exists = false;
301               }
302               else {
303                   sprintf (testset [testnbr].name, "%x-%x", rand (), rand ());
304                   if (zhash_insert (hash, testset [testnbr].name, "") == 0)
305                       testset [testnbr].exists = true;
306               }
307           }
308           //  Test 10K lookups
309           for (iteration = 0; iteration < 10000; iteration++)
310               item = (char *) zhash_lookup (hash, "DEADBEEFABADCAFE");
311
312           //  Destructor should be safe to call twice
313           zhash_destroy (&hash);
314           zhash_destroy (&hash);
315           assert (hash == NULL);
316
317           // Test autofree; automatically copies and frees string values
318           hash = zhash_new ();
319           assert (hash);
320           zhash_autofree (hash);
321           char value [255];
322           strcpy (value, "This is a string");
323           rc = zhash_insert (hash, "key1", value);
324           assert (rc == 0);
325           strcpy (value, "Inserting with the same key will fail");
326           rc = zhash_insert (hash, "key1", value);
327           assert (rc == -1);
328           strcpy (value, "Ring a ding ding");
329           rc = zhash_insert (hash, "key2", value);
330           assert (rc == 0);
331           assert (streq ((char *) zhash_lookup (hash, "key1"), "This is a string"));
332           assert (streq ((char *) zhash_lookup (hash, "key2"), "Ring a ding ding"));
333           zhash_destroy (&hash);
334
335           #if defined (__WINDOWS__)
336           zsys_shutdown();
337           #endif
338
339

AUTHORS

341       The czmq manual was written by the authors in the AUTHORS file.
342

RESOURCES

344       Main web site:
345
346       Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
347
349       Copyright (c) the Contributors as noted in the AUTHORS file. This file
350       is part of CZMQ, the high-level C binding for 0MQ:
351       http://czmq.zeromq.org. This Source Code Form is subject to the terms
352       of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
353       distributed with this file, You can obtain one at
354       http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
355       distribution.
356

NOTES

358        1. zeromq-dev@lists.zeromq.org
359           mailto:zeromq-dev@lists.zeromq.org
360
361
362
363CZMQ 4.1.1                        07/24/2019                          ZHASH(3)
Impressum