'\" t .\" Title: zhashx .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 01/17/2021 .\" Manual: CZMQ Manual .\" Source: CZMQ 4.2.1 .\" Language: English .\" .TH "ZHASHX" "3" "01/17/2021" "CZMQ 4\&.2\&.1" "CZMQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" zhashx \- Class for extended generic hash container .SH "SYNOPSIS" .sp .nf // This is a stable class, and may not change except for emergencies\&. It // is provided in stable builds\&. // This class has draft methods, which may change over time\&. They are not // in stable releases, by default\&. Use \-\-enable\-drafts to enable\&. // Destroy an item typedef void (zhashx_destructor_fn) ( void **item); // Duplicate an item typedef void * (zhashx_duplicator_fn) ( const void *item); // Compare two items, for sorting typedef int (zhashx_comparator_fn) ( const void *item1, const void *item2); // Destroy an item\&. typedef void (zhashx_free_fn) ( void *data); // Hash function for keys\&. typedef size_t (zhashx_hash_fn) ( const void *key); // Serializes an item to a longstr\&. // The caller takes ownership of the newly created object\&. typedef char * (zhashx_serializer_fn) ( const void *item); // Deserializes a longstr into an item\&. // The caller takes ownership of the newly created object\&. typedef void * (zhashx_deserializer_fn) ( const char *item_str); // Create a new, empty hash container CZMQ_EXPORT zhashx_t * zhashx_new (void); // Unpack binary frame into a new hash table\&. Packed data must follow format // defined by zhashx_pack\&. Hash table is set to autofree\&. An empty frame // unpacks to an empty hash table\&. CZMQ_EXPORT zhashx_t * zhashx_unpack (zframe_t *frame); // Destroy a hash container and all items in it CZMQ_EXPORT void zhashx_destroy (zhashx_t **self_p); // Insert item into hash table with specified key and item\&. // If key is already present returns \-1 and leaves existing item unchanged // Returns 0 on success\&. CZMQ_EXPORT int zhashx_insert (zhashx_t *self, const void *key, void *item); // Update or insert item into hash table with specified key and item\&. If the // key is already present, destroys old item and inserts new one\&. If you set // a container item destructor, this is called on the old value\&. If the key // was not already present, inserts a new item\&. Sets the hash cursor to the // new item\&. CZMQ_EXPORT void zhashx_update (zhashx_t *self, const void *key, void *item); // Remove an item specified by key from the hash table\&. If there was no such // item, this function does nothing\&. CZMQ_EXPORT void zhashx_delete (zhashx_t *self, const void *key); // Delete all items from the hash table\&. If the key destructor is // set, calls it on every key\&. If the item destructor is set, calls // it on every item\&. CZMQ_EXPORT void zhashx_purge (zhashx_t *self); // Return the item at the specified key, or null CZMQ_EXPORT void * zhashx_lookup (zhashx_t *self, const void *key); // Reindexes an item from an old key to a new key\&. If there was no such // item, does nothing\&. Returns 0 if successful, else \-1\&. CZMQ_EXPORT int zhashx_rename (zhashx_t *self, const void *old_key, const void *new_key); // Set a free function for the specified hash table item\&. When the item is // destroyed, the free function, if any, is called on that item\&. // Use this when hash items are dynamically allocated, to ensure that // you don\*(Aqt have memory leaks\&. You can pass \*(Aqfree\*(Aq or NULL as a free_fn\&. // Returns the item, or NULL if there is no such item\&. CZMQ_EXPORT void * zhashx_freefn (zhashx_t *self, const void *key, zhashx_free_fn free_fn); // Return the number of keys/items in the hash table CZMQ_EXPORT size_t zhashx_size (zhashx_t *self); // Return a zlistx_t containing the keys for the items in the // table\&. Uses the key_duplicator to duplicate all keys and sets the // key_destructor as destructor for the list\&. // Caller owns return value and must destroy it when done\&. CZMQ_EXPORT zlistx_t * zhashx_keys (zhashx_t *self); // Return a zlistx_t containing the values for the items in the // table\&. Uses the duplicator to duplicate all items and sets the // destructor as destructor for the list\&. // Caller owns return value and must destroy it when done\&. CZMQ_EXPORT zlistx_t * zhashx_values (zhashx_t *self); // Simple iterator; returns first item in hash table, in no given order, // or NULL if the table is empty\&. This method is simpler to use than the // foreach() method, which is deprecated\&. To access the key for this item // use zhashx_cursor()\&. NOTE: do NOT modify the table while iterating\&. CZMQ_EXPORT void * zhashx_first (zhashx_t *self); // Simple iterator; returns next item in hash table, in no given order, // or NULL if the last item was already returned\&. Use this together with // zhashx_first() to process all items in a hash table\&. If you need the // items in sorted order, use zhashx_keys() and then zlistx_sort()\&. To // access the key for this item use zhashx_cursor()\&. NOTE: do NOT modify // the table while iterating\&. CZMQ_EXPORT void * zhashx_next (zhashx_t *self); // After a successful first/next method, returns the key for the item that // was returned\&. This is a constant string that you may not modify or // deallocate, and which lasts as long as the item in the hash\&. After an // unsuccessful first/next, returns NULL\&. CZMQ_EXPORT const void * zhashx_cursor (zhashx_t *self); // Add a comment to hash table before saving to disk\&. You can add as many // comment lines as you like\&. These comment lines are discarded when loading // the file\&. If you use a null format, all comments are deleted\&. CZMQ_EXPORT void zhashx_comment (zhashx_t *self, const char *format, \&.\&.\&.) CHECK_PRINTF (2); // Save hash table to a text file in name=value format\&. Hash values must be // printable strings; keys may not contain \*(Aq=\*(Aq character\&. Returns 0 if OK, // else \-1 if a file error occurred\&. CZMQ_EXPORT int zhashx_save (zhashx_t *self, const char *filename); // Load hash table from a text file in name=value format; hash table must // already exist\&. Hash values must printable strings; keys may not contain // \*(Aq=\*(Aq character\&. Returns 0 if OK, else \-1 if a file was not readable\&. CZMQ_EXPORT int zhashx_load (zhashx_t *self, const char *filename); // When a hash table was loaded from a file by zhashx_load, this method will // reload the file if it has been modified since, and is "stable", i\&.e\&. not // still changing\&. Returns 0 if OK, \-1 if there was an error reloading the // file\&. CZMQ_EXPORT int zhashx_refresh (zhashx_t *self); // Serialize hash table to a binary frame that can be sent in a message\&. // The packed format is compatible with the \*(Aqdictionary\*(Aq type defined in // http://rfc\&.zeromq\&.org/spec:35/FILEMQ, and implemented by zproto: // // ; A list of name/value pairs // dictionary = dict\-count *( dict\-name dict\-value ) // dict\-count = number\-4 // dict\-value = longstr // dict\-name = string // // ; Strings are always length + text contents // longstr = number\-4 *VCHAR // string = number\-1 *VCHAR // // ; Numbers are unsigned integers in network byte order // number\-1 = 1OCTET // number\-4 = 4OCTET // // Comments are not included in the packed data\&. Item values MUST be // strings\&. // Caller owns return value and must destroy it when done\&. CZMQ_EXPORT zframe_t * zhashx_pack (zhashx_t *self); // Make a copy of the list; items are duplicated if you set a duplicator // for the list, otherwise not\&. Copying a null reference returns a null // reference\&. Note that this method\*(Aqs behavior changed slightly for CZMQ // v3\&.x, as it does not set nor respect autofree\&. It does however let you // duplicate any hash table safely\&. The old behavior is in zhashx_dup_v2\&. // Caller owns return value and must destroy it when done\&. CZMQ_EXPORT zhashx_t * zhashx_dup (zhashx_t *self); // Set a user\-defined deallocator for hash items; by default items are not // freed when the hash is destroyed\&. CZMQ_EXPORT void zhashx_set_destructor (zhashx_t *self, zhashx_destructor_fn destructor); // Set a user\-defined duplicator for hash items; by default items are not // copied when the hash is duplicated\&. CZMQ_EXPORT void zhashx_set_duplicator (zhashx_t *self, zhashx_duplicator_fn duplicator); // Set a user\-defined deallocator for keys; by default keys are freed // when the hash is destroyed using free()\&. CZMQ_EXPORT void zhashx_set_key_destructor (zhashx_t *self, zhashx_destructor_fn destructor); // Set a user\-defined duplicator for keys; by default keys are duplicated // using strdup\&. CZMQ_EXPORT void zhashx_set_key_duplicator (zhashx_t *self, zhashx_duplicator_fn duplicator); // Set a user\-defined comparator for keys; by default keys are // compared using strcmp\&. // The callback function should return zero (0) on matching // items\&. CZMQ_EXPORT void zhashx_set_key_comparator (zhashx_t *self, zhashx_comparator_fn comparator); // Set a user\-defined hash function for keys; by default keys are // hashed by a modified Bernstein hashing function\&. CZMQ_EXPORT void zhashx_set_key_hasher (zhashx_t *self, zhashx_hash_fn hasher); // Make copy of hash table; if supplied table is null, returns null\&. // Does not copy items themselves\&. Rebuilds new table so may be slow on // very large tables\&. NOTE: only works with item values that are strings // since there\*(Aqs no other way to know how to duplicate the item value\&. CZMQ_EXPORT zhashx_t * zhashx_dup_v2 (zhashx_t *self); // Self test of this class\&. CZMQ_EXPORT void zhashx_test (bool verbose); #ifdef CZMQ_BUILD_DRAFT_API // *** Draft method, for development use, may change without warning *** // Same as unpack but uses a user\-defined deserializer function to convert // a longstr back into item format\&. CZMQ_EXPORT zhashx_t * zhashx_unpack_own (zframe_t *frame, zhashx_deserializer_fn deserializer); // *** Draft method, for development use, may change without warning *** // Same as pack but uses a user\-defined serializer function to convert items // into longstr\&. // Caller owns return value and must destroy it when done\&. CZMQ_EXPORT zframe_t * zhashx_pack_own (zhashx_t *self, zhashx_serializer_fn serializer); #endif // CZMQ_BUILD_DRAFT_API Please add \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zhashx\&.c\*(Aq\&. .fi .SH "DESCRIPTION" .sp zhashx is an extended hash table container with more functionality than zhash, its simpler cousin\&. .sp The hash table always has a size that is prime and roughly doubles its size when 75% full\&. In case of hash collisions items are chained in a linked list\&. The hash table size is increased slightly (up to 5 times before roughly doubling the size) when an overly long chain (between 1 and 63 items depending on table size) is detected\&. .SH "EXAMPLE" .PP \fBFrom zhashx_test method\fR. .sp .if n \{\ .RS 4 .\} .nf zhashx_t *hash = zhashx_new (); assert (hash); assert (zhashx_size (hash) == 0); assert (zhashx_first (hash) == NULL); assert (zhashx_cursor (hash) == NULL); // Insert some items int rc; rc = zhashx_insert (hash, "DEADBEEF", "dead beef"); char *item = (char *) zhashx_first (hash); assert (streq ((char *) zhashx_cursor (hash), "DEADBEEF")); assert (streq (item, "dead beef")); assert (rc == 0); rc = zhashx_insert (hash, "ABADCAFE", "a bad cafe"); assert (rc == 0); rc = zhashx_insert (hash, "C0DEDBAD", "coded bad"); assert (rc == 0); rc = zhashx_insert (hash, "DEADF00D", "dead food"); assert (rc == 0); assert (zhashx_size (hash) == 4); // Look for existing items item = (char *) zhashx_lookup (hash, "DEADBEEF"); assert (streq (item, "dead beef")); item = (char *) zhashx_lookup (hash, "ABADCAFE"); assert (streq (item, "a bad cafe")); item = (char *) zhashx_lookup (hash, "C0DEDBAD"); assert (streq (item, "coded bad")); item = (char *) zhashx_lookup (hash, "DEADF00D"); assert (streq (item, "dead food")); // Look for non\-existent items item = (char *) zhashx_lookup (hash, "foo"); assert (item == NULL); // Try to insert duplicate items rc = zhashx_insert (hash, "DEADBEEF", "foo"); assert (rc == \-1); item = (char *) zhashx_lookup (hash, "DEADBEEF"); assert (streq (item, "dead beef")); // Some rename tests // Valid rename, key is now LIVEBEEF rc = zhashx_rename (hash, "DEADBEEF", "LIVEBEEF"); assert (rc == 0); item = (char *) zhashx_lookup (hash, "LIVEBEEF"); assert (streq (item, "dead beef")); // Trying to rename an unknown item to a non\-existent key rc = zhashx_rename (hash, "WHATBEEF", "NONESUCH"); assert (rc == \-1); // Trying to rename an unknown item to an existing key rc = zhashx_rename (hash, "WHATBEEF", "LIVEBEEF"); assert (rc == \-1); item = (char *) zhashx_lookup (hash, "LIVEBEEF"); assert (streq (item, "dead beef")); // Trying to rename an existing item to another existing item rc = zhashx_rename (hash, "LIVEBEEF", "ABADCAFE"); assert (rc == \-1); item = (char *) zhashx_lookup (hash, "LIVEBEEF"); assert (streq (item, "dead beef")); item = (char *) zhashx_lookup (hash, "ABADCAFE"); assert (streq (item, "a bad cafe")); // Test keys method zlistx_t *keys = zhashx_keys (hash); assert (zlistx_size (keys) == 4); zlistx_destroy (&keys); zlistx_t *values = zhashx_values (hash); assert (zlistx_size (values) == 4); zlistx_destroy (&values); // Test dup method zhashx_t *copy = zhashx_dup (hash); assert (zhashx_size (copy) == 4); item = (char *) zhashx_lookup (copy, "LIVEBEEF"); assert (item); assert (streq (item, "dead beef")); zhashx_destroy (©); // Test pack/unpack methods zframe_t *frame = zhashx_pack (hash); copy = zhashx_unpack (frame); zframe_destroy (&frame); assert (zhashx_size (copy) == 4); item = (char *) zhashx_lookup (copy, "LIVEBEEF"); assert (item); assert (streq (item, "dead beef")); zhashx_destroy (©); #ifdef CZMQ_BUILD_DRAFT_API // Test own pack/unpack methods zhashx_t *own_hash = zhashx_new (); zhashx_set_destructor (own_hash, s_test_destroy_int); assert (own_hash); int *val1 = (int *) zmalloc (sizeof (int)); int *val2 = (int *) zmalloc (sizeof (int)); *val1 = 25; *val2 = 100; zhashx_insert (own_hash, "val1", val1); zhashx_insert (own_hash, "val2", val2); frame = zhashx_pack_own (own_hash, s_test_serialize_int); copy = zhashx_unpack_own (frame, s_test_deserialze_int); zhashx_set_destructor (copy, s_test_destroy_int); zframe_destroy (&frame); assert (zhashx_size (copy) == 2); assert (*((int *) zhashx_lookup (copy, "val1")) == 25); assert (*((int *) zhashx_lookup (copy, "val2")) == 100); zhashx_destroy (©); zhashx_destroy (&own_hash); #endif // CZMQ_BUILD_DRAFT_API // Test save and load zhashx_comment (hash, "This is a test file"); zhashx_comment (hash, "Created by %s", "czmq_selftest"); zhashx_save (hash, "\&.cache"); copy = zhashx_new (); assert (copy); zhashx_load (copy, "\&.cache"); item = (char *) zhashx_lookup (copy, "LIVEBEEF"); assert (item); assert (streq (item, "dead beef")); zhashx_destroy (©); zsys_file_delete ("\&.cache"); // Delete a item zhashx_delete (hash, "LIVEBEEF"); item = (char *) zhashx_lookup (hash, "LIVEBEEF"); assert (item == NULL); assert (zhashx_size (hash) == 3); // Check that the queue is robust against random usage struct { char name [100]; bool exists; } testset [200]; memset (testset, 0, sizeof (testset)); int testmax = 200, testnbr, iteration; srandom ((unsigned) time (NULL)); for (iteration = 0; iteration < 25000; iteration++) { testnbr = randof (testmax); assert (testnbr != testmax); assert (testnbr < testmax); if (testset [testnbr]\&.exists) { item = (char *) zhashx_lookup (hash, testset [testnbr]\&.name); assert (item); zhashx_delete (hash, testset [testnbr]\&.name); testset [testnbr]\&.exists = false; } else { sprintf (testset [testnbr]\&.name, "%x\-%x", rand (), rand ()); if (zhashx_insert (hash, testset [testnbr]\&.name, "") == 0) testset [testnbr]\&.exists = true; } } // Test 10K lookups for (iteration = 0; iteration < 10000; iteration++) item = (char *) zhashx_lookup (hash, "DEADBEEFABADCAFE"); // Destructor should be safe to call twice zhashx_destroy (&hash); zhashx_destroy (&hash); assert (hash == NULL); // Test randof() limits \- should be within (0\&.\&.testmax) // and randomness distribution \- should not have (many) zero\-counts // If there are \- maybe the ZSYS_RANDOF_MAX is too big for this platform // Note: This test can take a while on systems with weak floating point HW testmax = 999; size_t rndcnt[999]; assert ((sizeof (rndcnt)/sizeof(rndcnt[0])) == testmax); memset (rndcnt, 0, sizeof (rndcnt)); for (iteration = 0; iteration < 10000000; iteration++) { testnbr = randof (testmax); assert (testnbr != testmax); assert (testnbr < testmax); assert (testnbr >= 0); rndcnt[testnbr]++; } int rndmisses = 0; for (iteration = 0; iteration < testmax; iteration++) { if (rndcnt[iteration] == 0) { zsys_warning("zhashx_test() : random distribution fault : got 0 hits for %d/%d", iteration, testmax); rndmisses++; } } // Too many misses are suspicious\&.\&.\&. we can lose half the entries // for each bit not used in the assumed ZSYS_RANDOF_MAX\&.\&.\&. assert ( (rndmisses < (testmax / 3 )) ); // Test destructor; automatically copies and frees string values hash = zhashx_new (); assert (hash); zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free); zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup); char value [255]; strcpy (value, "This is a string"); rc = zhashx_insert (hash, "key1", value); assert (rc == 0); strcpy (value, "Ring a ding ding"); rc = zhashx_insert (hash, "key2", value); assert (rc == 0); assert (streq ((char *) zhashx_lookup (hash, "key1"), "This is a string")); assert (streq ((char *) zhashx_lookup (hash, "key2"), "Ring a ding ding")); zhashx_destroy (&hash); // Test purger and shrinker: no data should end up unreferenced in valgrind hash = zhashx_new (); assert (hash); zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free); zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup); char valuep [255]; strcpy (valuep, "This is a string"); rc = zhashx_insert (hash, "key1", valuep); assert (rc == 0); strcpy (valuep, "Ring a ding ding"); rc = zhashx_insert (hash, "key2", valuep); assert (rc == 0); strcpy (valuep, "Cartahena delenda est"); rc = zhashx_insert (hash, "key3", valuep); assert (rc == 0); strcpy (valuep, "So say we all!"); rc = zhashx_insert (hash, "key4", valuep); assert (rc == 0); assert (streq ((char *) zhashx_lookup (hash, "key1"), "This is a string")); assert (streq ((char *) zhashx_lookup (hash, "key2"), "Ring a ding ding")); assert (streq ((char *) zhashx_lookup (hash, "key3"), "Cartahena delenda est")); assert (streq ((char *) zhashx_lookup (hash, "key4"), "So say we all!")); zhashx_purge (hash); zhashx_destroy (&hash); #if defined (__WINDOWS__) zsys_shutdown(); #endif .fi .if n \{\ .RE .\} .sp .SH "AUTHORS" .sp The czmq manual was written by the authors in the AUTHORS file\&. .SH "RESOURCES" .sp Main web site: \m[blue]\fB\%\fR\m[] .sp Report bugs to the email <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[1]\d\s+2> .SH "COPYRIGHT" .sp Copyright (c) the Contributors as noted in the AUTHORS file\&. This file is part of CZMQ, the high\-level C binding for 0MQ: http://czmq\&.zeromq\&.org\&. This Source Code Form is subject to the terms of the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. LICENSE included with the czmq distribution\&. .SH "NOTES" .IP " 1." 4 zeromq-dev@lists.zeromq.org .RS 4 \%mailto:zeromq-dev@lists.zeromq.org .RE