You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
382 lines
14 KiB
382 lines
14 KiB
'\" t
|
|
.\" Title: zhash
|
|
.\" Author: [see the "AUTHORS" section]
|
|
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
|
|
.\" Date: 12/31/2016
|
|
.\" Manual: CZMQ Manual
|
|
.\" Source: CZMQ 4.0.2
|
|
.\" Language: English
|
|
.\"
|
|
.TH "ZHASH" "3" "12/31/2016" "CZMQ 4\&.0\&.2" "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"
|
|
zhash \- simple 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\&.
|
|
// Callback function for zhash_freefn method
|
|
typedef void (zhash_free_fn) (
|
|
void *data);
|
|
|
|
// Create a new, empty hash container
|
|
CZMQ_EXPORT zhash_t *
|
|
zhash_new (void);
|
|
|
|
// Unpack binary frame into a new hash table\&. Packed data must follow format
|
|
// defined by zhash_pack\&. Hash table is set to autofree\&. An empty frame
|
|
// unpacks to an empty hash table\&.
|
|
CZMQ_EXPORT zhash_t *
|
|
zhash_unpack (zframe_t *frame);
|
|
|
|
// Destroy a hash container and all items in it
|
|
CZMQ_EXPORT void
|
|
zhash_destroy (zhash_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
|
|
zhash_insert (zhash_t *self, const char *key, void *item);
|
|
|
|
// Update item into hash table with specified key and item\&.
|
|
// If key is already present, destroys old item and inserts new one\&.
|
|
// Use free_fn method to ensure deallocator is properly called on item\&.
|
|
CZMQ_EXPORT void
|
|
zhash_update (zhash_t *self, const char *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
|
|
zhash_delete (zhash_t *self, const char *key);
|
|
|
|
// Return the item at the specified key, or null
|
|
CZMQ_EXPORT void *
|
|
zhash_lookup (zhash_t *self, const char *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
|
|
zhash_rename (zhash_t *self, const char *old_key, const char *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 *
|
|
zhash_freefn (zhash_t *self, const char *key, zhash_free_fn free_fn);
|
|
|
|
// Return the number of keys/items in the hash table
|
|
CZMQ_EXPORT size_t
|
|
zhash_size (zhash_t *self);
|
|
|
|
// 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\&.
|
|
// Caller owns return value and must destroy it when done\&.
|
|
CZMQ_EXPORT zhash_t *
|
|
zhash_dup (zhash_t *self);
|
|
|
|
// Return keys for items in table
|
|
// Caller owns return value and must destroy it when done\&.
|
|
CZMQ_EXPORT zlist_t *
|
|
zhash_keys (zhash_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 zhash_cursor()\&. NOTE: do NOT modify the table while iterating\&.
|
|
CZMQ_EXPORT void *
|
|
zhash_first (zhash_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
|
|
// zhash_first() to process all items in a hash table\&. If you need the
|
|
// items in sorted order, use zhash_keys() and then zlist_sort()\&. To
|
|
// access the key for this item use zhash_cursor()\&. NOTE: do NOT modify
|
|
// the table while iterating\&.
|
|
CZMQ_EXPORT void *
|
|
zhash_next (zhash_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 char *
|
|
zhash_cursor (zhash_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
|
|
zhash_comment (zhash_t *self, const char *format, \&.\&.\&.) CHECK_PRINTF (2);
|
|
|
|
// 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 *
|
|
zhash_pack (zhash_t *self);
|
|
|
|
// 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
|
|
zhash_save (zhash_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
|
|
zhash_load (zhash_t *self, const char *filename);
|
|
|
|
// When a hash table was loaded from a file by zhash_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
|
|
zhash_refresh (zhash_t *self);
|
|
|
|
// Set hash for automatic value destruction
|
|
CZMQ_EXPORT void
|
|
zhash_autofree (zhash_t *self);
|
|
|
|
// Self test of this class\&.
|
|
CZMQ_EXPORT void
|
|
zhash_test (bool verbose);
|
|
|
|
Please add \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zhash\&.c\*(Aq\&.
|
|
.fi
|
|
.SH "DESCRIPTION"
|
|
.sp
|
|
zhash is an expandable hash table container\&. This is a simple container\&. For heavy\-duty applications we recommend using zhashx\&.
|
|
.sp
|
|
Note that it\(cqs relatively slow (50K insertions/deletes per second), so don\(cqt do inserts/updates on the critical path for message I/O\&. It can do 2\&.5M lookups per second for 16\-char keys\&. Timed on a 1\&.6GHz CPU\&.
|
|
.SH "EXAMPLE"
|
|
.PP
|
|
\fBFrom zhash_test method\fR.
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
zhash_t *hash = zhash_new ();
|
|
assert (hash);
|
|
assert (zhash_size (hash) == 0);
|
|
assert (zhash_first (hash) == NULL);
|
|
assert (zhash_cursor (hash) == NULL);
|
|
|
|
// Insert some items
|
|
int rc;
|
|
rc = zhash_insert (hash, "DEADBEEF", "dead beef");
|
|
char *item = (char *) zhash_first (hash);
|
|
assert (streq (zhash_cursor (hash), "DEADBEEF"));
|
|
assert (streq (item, "dead beef"));
|
|
assert (rc == 0);
|
|
rc = zhash_insert (hash, "ABADCAFE", "a bad cafe");
|
|
assert (rc == 0);
|
|
rc = zhash_insert (hash, "C0DEDBAD", "coded bad");
|
|
assert (rc == 0);
|
|
rc = zhash_insert (hash, "DEADF00D", "dead food");
|
|
assert (rc == 0);
|
|
assert (zhash_size (hash) == 4);
|
|
|
|
// Look for existing items
|
|
item = (char *) zhash_lookup (hash, "DEADBEEF");
|
|
assert (streq (item, "dead beef"));
|
|
item = (char *) zhash_lookup (hash, "ABADCAFE");
|
|
assert (streq (item, "a bad cafe"));
|
|
item = (char *) zhash_lookup (hash, "C0DEDBAD");
|
|
assert (streq (item, "coded bad"));
|
|
item = (char *) zhash_lookup (hash, "DEADF00D");
|
|
assert (streq (item, "dead food"));
|
|
|
|
// Look for non\-existent items
|
|
item = (char *) zhash_lookup (hash, "foo");
|
|
assert (item == NULL);
|
|
|
|
// Try to insert duplicate items
|
|
rc = zhash_insert (hash, "DEADBEEF", "foo");
|
|
assert (rc == \-1);
|
|
item = (char *) zhash_lookup (hash, "DEADBEEF");
|
|
assert (streq (item, "dead beef"));
|
|
|
|
// Some rename tests
|
|
|
|
// Valid rename, key is now LIVEBEEF
|
|
rc = zhash_rename (hash, "DEADBEEF", "LIVEBEEF");
|
|
assert (rc == 0);
|
|
item = (char *) zhash_lookup (hash, "LIVEBEEF");
|
|
assert (streq (item, "dead beef"));
|
|
|
|
// Trying to rename an unknown item to a non\-existent key
|
|
rc = zhash_rename (hash, "WHATBEEF", "NONESUCH");
|
|
assert (rc == \-1);
|
|
|
|
// Trying to rename an unknown item to an existing key
|
|
rc = zhash_rename (hash, "WHATBEEF", "LIVEBEEF");
|
|
assert (rc == \-1);
|
|
item = (char *) zhash_lookup (hash, "LIVEBEEF");
|
|
assert (streq (item, "dead beef"));
|
|
|
|
// Trying to rename an existing item to another existing item
|
|
rc = zhash_rename (hash, "LIVEBEEF", "ABADCAFE");
|
|
assert (rc == \-1);
|
|
item = (char *) zhash_lookup (hash, "LIVEBEEF");
|
|
assert (streq (item, "dead beef"));
|
|
item = (char *) zhash_lookup (hash, "ABADCAFE");
|
|
assert (streq (item, "a bad cafe"));
|
|
|
|
// Test keys method
|
|
zlist_t *keys = zhash_keys (hash);
|
|
assert (zlist_size (keys) == 4);
|
|
zlist_destroy (&keys);
|
|
|
|
// Test dup method
|
|
zhash_t *copy = zhash_dup (hash);
|
|
assert (zhash_size (copy) == 4);
|
|
item = (char *) zhash_lookup (copy, "LIVEBEEF");
|
|
assert (item);
|
|
assert (streq (item, "dead beef"));
|
|
zhash_destroy (©);
|
|
|
|
// Test pack/unpack methods
|
|
zframe_t *frame = zhash_pack (hash);
|
|
copy = zhash_unpack (frame);
|
|
zframe_destroy (&frame);
|
|
assert (zhash_size (copy) == 4);
|
|
item = (char *) zhash_lookup (copy, "LIVEBEEF");
|
|
assert (item);
|
|
assert (streq (item, "dead beef"));
|
|
zhash_destroy (©);
|
|
|
|
// Test save and load
|
|
zhash_comment (hash, "This is a test file");
|
|
zhash_comment (hash, "Created by %s", "czmq_selftest");
|
|
zhash_save (hash, "\&.cache");
|
|
copy = zhash_new ();
|
|
assert (copy);
|
|
zhash_load (copy, "\&.cache");
|
|
item = (char *) zhash_lookup (copy, "LIVEBEEF");
|
|
assert (item);
|
|
assert (streq (item, "dead beef"));
|
|
zhash_destroy (©);
|
|
zsys_file_delete ("\&.cache");
|
|
|
|
// Delete a item
|
|
zhash_delete (hash, "LIVEBEEF");
|
|
item = (char *) zhash_lookup (hash, "LIVEBEEF");
|
|
assert (item == NULL);
|
|
assert (zhash_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 *) zhash_lookup (hash, testset [testnbr]\&.name);
|
|
assert (item);
|
|
zhash_delete (hash, testset [testnbr]\&.name);
|
|
testset [testnbr]\&.exists = false;
|
|
}
|
|
else {
|
|
sprintf (testset [testnbr]\&.name, "%x\-%x", rand (), rand ());
|
|
if (zhash_insert (hash, testset [testnbr]\&.name, "") == 0)
|
|
testset [testnbr]\&.exists = true;
|
|
}
|
|
}
|
|
// Test 10K lookups
|
|
for (iteration = 0; iteration < 10000; iteration++)
|
|
item = (char *) zhash_lookup (hash, "DEADBEEFABADCAFE");
|
|
|
|
// Destructor should be safe to call twice
|
|
zhash_destroy (&hash);
|
|
zhash_destroy (&hash);
|
|
assert (hash == NULL);
|
|
|
|
// Test autofree; automatically copies and frees string values
|
|
hash = zhash_new ();
|
|
assert (hash);
|
|
zhash_autofree (hash);
|
|
char value [255];
|
|
strcpy (value, "This is a string");
|
|
rc = zhash_insert (hash, "key1", value);
|
|
assert (rc == 0);
|
|
strcpy (value, "Inserting with the same key will fail");
|
|
rc = zhash_insert (hash, "key1", value);
|
|
assert (rc == \-1);
|
|
strcpy (value, "Ring a ding ding");
|
|
rc = zhash_insert (hash, "key2", value);
|
|
assert (rc == 0);
|
|
assert (streq ((char *) zhash_lookup (hash, "key1"), "This is a string"));
|
|
assert (streq ((char *) zhash_lookup (hash, "key2"), "Ring a ding ding"));
|
|
zhash_destroy (&hash);
|
|
.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
|
|
|