1ZHASH(3) CZMQ Manual ZHASH(3)
2
6 zhash - Class for simple 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 // Callback function for zhash_freefn method
12 typedef void (zhash_free_fn) (
13 void *data);
14 // Create a new, empty hash container
16 CZMQ_EXPORT zhash_t *
17 zhash_new (void);
18 // 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 // Destroy a hash container and all items in it
26 CZMQ_EXPORT void
27 zhash_destroy (zhash_t **self_p);
28 // 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 // 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 // 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 // Return the item at the specified key, or null
47 CZMQ_EXPORT void *
48 zhash_lookup (zhash_t *self, const char *key);
49 // 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 // 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 // Return the number of keys/items in the hash table
64 CZMQ_EXPORT size_t
65 zhash_size (zhash_t *self);
66 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // Self test of this class.
158 CZMQ_EXPORT void
159 zhash_test (bool verbose);
160 Please add '@interface' section in './../src/zhash.c'.
162
164 zhash is an expandable hash table container. This is a simple
165 container. For heavy-duty applications we recommend using zhashx.
166 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
172 From zhash_test method.
173 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 // 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 // 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 // Look for non-existent items
206 item = (char *) zhash_lookup (hash, "foo");
207 assert (item == NULL);
208 // 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 // Some rename tests
216 // 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 // Trying to rename an unknown item to a non-existent key
224 rc = zhash_rename (hash, "WHATBEEF", "NONESUCH");
225 assert (rc == -1);
226 // 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 // 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 // Test keys method
242 zlist_t *keys = zhash_keys (hash);
243 assert (zlist_size (keys) == 4);
244 zlist_destroy (&keys);
245 // 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 (©);
253 // 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 (©);
263 // 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 (©);
275 zsys_file_delete (".cache");
276 // 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 // 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 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 // Destructor should be safe to call twice
313 zhash_destroy (&hash);
314 zhash_destroy (&hash);
315 assert (hash == NULL);
316 // 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 #if defined (__WINDOWS__)
336 zsys_shutdown();
337 #endif
338
341 The czmq manual was written by the authors in the AUTHORS file.
342
344 Main web site:
345 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
358 1. zeromq-dev@lists.zeromq.org
359 mailto:zeromq-dev@lists.zeromq.org
360CZMQ 4.2.1 01/19/2023 ZHASH(3)