mirror of https://gitee.com/bigwinds/arangodb
219 lines
7.4 KiB
Groff
219 lines
7.4 KiB
Groff
'\" t
|
|
.\" Title: zhash
|
|
.\" Author: [see the "AUTHORS" section]
|
|
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
|
|
.\" Date: 08/30/2011
|
|
.\" Manual: czmq Manual
|
|
.\" Source: czmq 1.1.0
|
|
.\" Language: English
|
|
.\"
|
|
.TH "ZHASH" "7" "08/30/2011" "czmq 1\&.1\&.0" "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 \- generic type\-free hash container
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
.nf
|
|
// Callback function for zhash_foreach method
|
|
typedef int (zhash_foreach_fn) (char *key, void *item, void *argument);
|
|
// Callback function for zhash_freefn method
|
|
typedef void (zhash_free_fn) (void *data);
|
|
|
|
// Create a new, empty hash container
|
|
zhash_t *
|
|
zhash_new (void);
|
|
|
|
// Destroy a hash container and all items in it
|
|
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\&.
|
|
int
|
|
zhash_insert (zhash_t *self, 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\&.
|
|
void
|
|
zhash_update (zhash_t *self, char *key, void *item);
|
|
|
|
// Remove an item specified by key from the hash table\&. If there was no such
|
|
// item, this function does nothing\&.
|
|
void
|
|
zhash_delete (zhash_t *self, char *key);
|
|
|
|
// Return the item at the specified key, or null
|
|
void *
|
|
zhash_lookup (zhash_t *self, 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\&.
|
|
int
|
|
zhash_rename (zhash_t *self, char *old_key, 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\&.
|
|
void *
|
|
zhash_freefn (zhash_t *self, char *key, zhash_free_fn *free_fn);
|
|
|
|
// Return the number of keys/items in the hash table
|
|
size_t
|
|
zhash_size (zhash_t *self);
|
|
|
|
// Apply function to each item in the hash table\&. Items are iterated in no
|
|
// defined order\&. Stops if callback function returns non\-zero and returns
|
|
// final return code from callback function (zero = success)\&.
|
|
int
|
|
zhash_foreach (zhash_t *self, zhash_foreach_fn *callback, void *argument);
|
|
|
|
// Self test of this class
|
|
void
|
|
zhash_test (int verbose);
|
|
.fi
|
|
.SH "DESCRIPTION"
|
|
.sp
|
|
Expandable hash table container
|
|
.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);
|
|
|
|
// Insert some items
|
|
int rc;
|
|
rc = zhash_insert (hash, "DEADBEEF", (void *) 0xDEADBEEF);
|
|
assert (rc == 0);
|
|
rc = zhash_insert (hash, "ABADCAFE", (void *) 0xABADCAFE);
|
|
assert (rc == 0);
|
|
rc = zhash_insert (hash, "C0DEDBAD", (void *) 0xC0DEDBAD);
|
|
assert (rc == 0);
|
|
rc = zhash_insert (hash, "DEADF00D", (void *) 0xDEADF00D);
|
|
assert (rc == 0);
|
|
assert (zhash_size (hash) == 4);
|
|
|
|
// Look for existing items
|
|
void *item;
|
|
item = zhash_lookup (hash, "DEADBEEF");
|
|
assert (item == (void *) 0xDEADBEEF);
|
|
item = zhash_lookup (hash, "ABADCAFE");
|
|
assert (item == (void *) 0xABADCAFE);
|
|
item = zhash_lookup (hash, "C0DEDBAD");
|
|
assert (item == (void *) 0xC0DEDBAD);
|
|
item = zhash_lookup (hash, "DEADF00D");
|
|
assert (item == (void *) 0xDEADF00D);
|
|
|
|
// Look for non\-existent items
|
|
item = zhash_lookup (hash, "0xF0000000");
|
|
assert (item == NULL);
|
|
|
|
// Try to insert duplicate items
|
|
rc = zhash_insert (hash, "DEADBEEF", (void *) 0xF0000000);
|
|
assert (rc == \-1);
|
|
item = zhash_lookup (hash, "DEADBEEF");
|
|
assert (item == (void *) 0xDEADBEEF);
|
|
|
|
// Rename an item
|
|
rc = zhash_rename (hash, "DEADBEEF", "LIVEBEEF");
|
|
assert (rc == 0);
|
|
rc = zhash_rename (hash, "WHATBEEF", "LIVEBEEF");
|
|
assert (rc == \-1);
|
|
|
|
// Delete a item
|
|
zhash_delete (hash, "LIVEBEEF");
|
|
item = 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);
|
|
if (testset [testnbr]\&.exists) {
|
|
item = 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 = zhash_lookup (hash, "DEADBEEFABADCAFE");
|
|
|
|
// Destructor should be safe to call twice
|
|
zhash_destroy (&hash);
|
|
zhash_destroy (&hash);
|
|
assert (hash == NULL);
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.SH "SEE ALSO"
|
|
.sp
|
|
\fBczmq\fR(7)
|
|
.SH "AUTHORS"
|
|
.sp
|
|
The czmq manual was written by Pieter Hintjens<\m[blue]\fBph@imatix\&.com\fR\m[]\&\s-2\u[1]\d\s+2>\&.
|
|
.SH "RESOURCES"
|
|
.sp
|
|
Main web site: \m[blue]\fBhttp://czmq\&.zeromq\&.org/\fR\m[]
|
|
.sp
|
|
Report bugs to the 0MQ development mailing list: <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[2]\d\s+2>
|
|
.SH "COPYRIGHT"
|
|
.sp
|
|
Copyright (c) 1991\-2010 iMatix Corporation and contributors\&. License LGPLv3+: GNU LGPL 3 or later <\m[blue]\fBhttp://gnu\&.org/licenses/lgpl\&.html\fR\m[]>\&. This is free software: you are free to change it and redistribute it\&. There is NO WARRANTY, to the extent permitted by law\&. For details see the files COPYING and COPYING\&.LESSER included with the czmq distribution\&.
|
|
.SH "NOTES"
|
|
.IP " 1." 4
|
|
ph@imatix.com
|
|
.RS 4
|
|
\%mailto:ph@imatix.com
|
|
.RE
|
|
.IP " 2." 4
|
|
zeromq-dev@lists.zeromq.org
|
|
.RS 4
|
|
\%mailto:zeromq-dev@lists.zeromq.org
|
|
.RE
|