[asterisk-commits] murf: branch murf/datastructs r67947 -
/team/murf/datastructs/doc/hashtab.tex
asterisk-commits at lists.digium.com
asterisk-commits at lists.digium.com
Wed Jun 6 17:13:17 MST 2007
Author: murf
Date: Wed Jun 6 19:13:16 2007
New Revision: 67947
URL: http://svn.digium.com/view/asterisk?view=rev&rev=67947
Log:
some doc updates to make things look prettier
Modified:
team/murf/datastructs/doc/hashtab.tex
Modified: team/murf/datastructs/doc/hashtab.tex
URL: http://svn.digium.com/view/asterisk/team/murf/datastructs/doc/hashtab.tex?view=diff&rev=67947&r1=67946&r2=67947
==============================================================================
--- team/murf/datastructs/doc/hashtab.tex (original)
+++ team/murf/datastructs/doc/hashtab.tex Wed Jun 6 19:13:16 2007
@@ -55,8 +55,8 @@
\begin{verbatim}
struct my_object
{
- char *key;
- char *val;
+ char *key;
+ char *val;
}
\end{verbatim}
@@ -67,14 +67,14 @@
\begin{verbatim}
static int my_compare(const void *a, const void *b)
{
- const struct my_object *ae = a, *be = b;
- return ast_hashtab_compare_strings_nocase(ae->key, be->key);
+ const struct my_object *ae = a, *be = b;
+ return ast_hashtab_compare_strings_nocase(ae->key, be->key);
}
static int my_hash(const void *obj, int modulus)
{
- const struct my_object *o = obj;
- return ast_hashtab_hash_string_nocase(o->key, modulus);
+ const struct my_object *o = obj;
+ return ast_hashtab_hash_string_nocase(o->key, modulus);
}
\end{verbatim}
@@ -85,15 +85,17 @@
hash that way, too!
For sizing, if we desire to use the java hashtable resizing algorithm, which
-doubles the hash table size when it reaches 75% of its capacity, then
+doubles the hash table size when it reaches 75\% of its capacity, then
we simply provide the \verb+ast_hashtab_resize_java+ and \verb+ast_hashtab_newsize_java+
function pointers:
\begin{verbatim}
struct ast_hashtab *ht;
- ht = ast_hashtab_create(100, my_compare,
- ast_hashtab_resize_java, ast_hashtab_newsize_java,
- my_hash, 0);
+ ht = ast_hashtab_create(
+ 100, my_compare,
+ ast_hashtab_resize_java,
+ ast_hashtab_newsize_java,
+ my_hash, 0);
\end{verbatim}
To look up a key in the table, use the \verb+ast_hashtab_lookup+ function,
@@ -103,12 +105,12 @@
use the same hash/compare functionality as it does internally for everything else:
\begin{verbatim}
- struct my_object *entry = 0;
- struct my_object lookup;
-
- lookup.key = args.key;
- lookup.val = 0;
- entry = ast_hashtab_lookup(ht, &lookup);
+ struct my_object *entry = 0;
+ struct my_object lookup;
+
+ lookup.key = args.key;
+ lookup.val = 0;
+ entry = ast_hashtab_lookup(ht, &lookup);
\end{verbatim}
@@ -120,22 +122,24 @@
(If it is, it does nothing!).
\begin{verbatim}
- lookup.key = "somekey";
- lookup.val = 0;
- entry = ast_hashtab_lookup(ht, &lookup);
-
- if (entry) { /* replace the existing value */
- if (entry->val)
- free(entry->val);
- entry->val = ast_strdup(value);
- } else { /* insert this into the table */
- entry = ast_calloc(sizeof(struct my_object),1);
- entry->val = ast_strdup(value);
- entry->key = ast_strdup("somekey");
-
- if (!ast_hashtab_insert_immediate(ht, entry))
- ast_log(LOG_NOTICE,"Did NOT add key %s = value %s\n", lookup.key, entry->val);
- }
+ lookup.key = "somekey";
+ lookup.val = 0;
+ entry = ast_hashtab_lookup(ht, &lookup);
+
+ if (entry) { /* replace the existing value */
+ if (entry->val)
+ free(entry->val);
+ entry->val = ast_strdup(value);
+ } else { /* insert this into the table */
+ entry = ast_calloc(sizeof(struct my_object),1);
+ entry->val = ast_strdup(value);
+ entry->key = ast_strdup("somekey");
+
+ if (!ast_hashtab_insert_immediate(ht, entry))
+ ast_log(LOG_NOTICE,
+ "Did NOT add key %s = value %s\n",
+ lookup.key, entry->val);
+ }
\end{verbatim}
\subsubsection{Hashtab Locking}
@@ -146,8 +150,8 @@
the hashtable, . Traversal is done with the read lock. Removal requires a write lock. Instant
deadlock.
To overcome this limitation, use \verb+ast_hashtab_start_write_traversal+, with
-either \verb+ast_hashtab_remove_object_via_lookup_nolock+
-or \verb+ast_hashtab_remove_this_object_nolock+. In this case, the \verb+start_write_traversal+ function
+either the \verb+remove_object_via_lookup_nolock+
+or \verb+remove_this_object_nolock+. In this case, the \verb+start_write_traversal+ function
will request a write lock, and the remove funcs will not request any; the standard ``next'' and
``end traversal'' funcs can be used.
@@ -163,12 +167,13 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-struct ast_hashtab * ast_hashtab_create(int initial_buckets,
- int (*compare)(const void *a, const void *b),
- int (*resize)(struct ast_hashtab *),
- int (*newsize)(struct ast_hashtab *tab),
- int (*hash)(const void *obj, int modulus),
- int do_locking );
+struct ast_hashtab * ast_hashtab_create(
+ int initial_buckets,
+ int (*compare)(const void *a, const void *b),
+ int (*resize)(struct ast_hashtab *),
+ int (*newsize)(struct ast_hashtab *tab),
+ int (*hash)(const void *obj, int modulus),
+ int do_locking );
\end{verbatim}
\item Description
This function creates a hash table and returns a pointer to it.
@@ -199,7 +204,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-int ast_hashtab_insert_immediate(struct ast_hashtab *tab, const void *obj);
+int ast_hashtab_insert_immediate(struct ast_hashtab *tab,
+ const void *obj);
\end{verbatim}
\item Description
This function calculates the hash of the provided object's key, It then inserts the
@@ -210,7 +216,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-int ast_hashtab_insert_immediate_bucket(struct ast_hashtab *tab, const void *obj, int h);
+int ast_hashtab_insert_immediate_bucket(struct ast_hashtab *tab,
+ const void *obj, int h);
\end{verbatim}
\item Description
This function does not calculate the hash of the key; instead it expects you
@@ -226,7 +233,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-int ast_hashtab_insert_safe(struct ast_hashtab *tab, const void *obj);
+int ast_hashtab_insert_safe(struct ast_hashtab *tab,
+ const void *obj);
\end{verbatim}
\item Description
This function hashes the sought-after key, and searches for the object with that key.
@@ -239,7 +247,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-void * ast_hashtab_lookup(struct ast_hashtab *tab, const void *obj);
+void * ast_hashtab_lookup(struct ast_hashtab *tab,
+ const void *obj);
\end{verbatim}
\item Description
This function hashes the key in the object provided, and looks for the
@@ -251,7 +260,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-void * ast_hashtab_lookup_bucket(struct ast_hashtab *tab, const void *obj, int *h);
+void * ast_hashtab_lookup_bucket(struct ast_hashtab *tab,
+ const void *obj, int *h);
\end{verbatim}
\item Description
This function sets the 3rd argument to the calculated hash value, returns the pointer
@@ -266,7 +276,11 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-void ast_hashtab_get_stats( struct ast_hashtab *tab, int *biggest_bucket_size, int *resize_count, int *num_objects, int *num_buckets);
+void ast_hashtab_get_stats(struct ast_hashtab *tab,
+ int *biggest_bucket_size,
+ int *resize_count,
+ int *num_objects,
+ int *num_buckets);
\end{verbatim}
\item Description
This routine will fill in the numbers whose addresses you supply in the arg list,
@@ -298,7 +312,7 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-int ast_hashtab_capacity( struct ast_hashtab *tab);
+int ast_hashtab_capacity(struct ast_hashtab *tab);
\end{verbatim}
\item Description
This function returns the number of hash buckets allocated in the hashtab array.
@@ -308,7 +322,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-struct ast_hashtab_iter *ast_hashtab_start_traversal(struct ast_hashtab *tab);
+struct ast_hashtab_iter
+ *ast_hashtab_start_traversal(struct ast_hashtab *tab);
\end{verbatim}
\item Description
This routine creates an iterator structure and returns it, to keep information
@@ -326,7 +341,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-struct ast_hashtab_iter *ast_hashtab_start_write_traversal(struct ast_hashtab *tab);
+struct ast_hashtab_iter
+ *ast_hashtab_start_write_traversal(struct ast_hashtab *tab);
\end{verbatim}
\item Description
This routine creates an iterator structure and returns it, to keep information
@@ -375,7 +391,9 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-void *ast_hashtab_remove_object_via_lookup(struct ast_hashtab *tab, void *obj);
+void *ast_hashtab_remove_object_via_lookup(
+ struct ast_hashtab *tab,
+ void *obj);
\end{verbatim}
\item Description
This function calculates the hash of the key, and then finds the proper bucket
@@ -387,7 +405,9 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-void *ast_hashtab_remove_this_object(struct ast_hashtab *tab, void *obj);
+void *ast_hashtab_remove_this_object(
+ struct ast_hashtab *tab,
+ void *obj);
\end{verbatim}
\item Description
This function first gets the hash of the key of the object, then finds the proper
@@ -396,36 +416,13 @@
a NULL is returned, and nothing is done. This function requests a write lock.
\end{itemize}
-\item \verb+ast_hashtab_remove_object_via_lookup+
-\begin{itemize}
-\item Prototype
-\begin{verbatim}
-void *ast_hashtab_remove_object_via_lookup(struct ast_hashtab *tab, void *obj);
-\end{verbatim}
-\item Description
-This function calculates the hash of the key, and then finds the proper bucket
-by finding a matching key (uses the compare function supplied to the create call).
-This function requests a write lock.
-
-\end{itemize}
-\item \verb+ast_hashtab_remove_this_object+
-\begin{itemize}
-\item Prototype
-\begin{verbatim}
-void *ast_hashtab_remove_this_object(struct ast_hashtab *tab, void *obj);
-\end{verbatim}
-\item Description
-This function first gets the hash of the key of the object, then finds the proper
-bucket by comparing object pointers, which is faster than comparing key values, especially
-if the keys are strings. If the object is found, its pointer is returned. Otherwise,
-a NULL is returned, and nothing is done. This function requests a write lock.
-
-\end{itemize}
\item \verb+ast_hashtab_remove_object_via_lookup_nolock+
\begin{itemize}
\item Prototype
\begin{verbatim}
-void *ast_hashtab_remove_object_via_lookup_nolock(struct ast_hashtab *tab, void *obj);
+void *ast_hashtab_remove_object_via_lookup_nolock(
+ struct ast_hashtab *tab,
+ void *obj);
\end{verbatim}
\item Description
This function calculates the hash of the key, and then finds the proper bucket
@@ -439,7 +436,9 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-void *ast_hashtab_remove_this_object_nolock(struct ast_hashtab *tab, void *obj);
+void *ast_hashtab_remove_this_object_nolock(
+ struct ast_hashtab *tab,
+ void *obj);
\end{verbatim}
\item Description
This function first gets the hash of the key of the object, then finds the proper
@@ -467,7 +466,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
- int ast_hashtab_compare_strings(const void *a, const void *b)
+ int ast_hashtab_compare_strings(const void *a,
+ const void *b)
\end{verbatim}
\item Description
Returns the result of strcmp(a,b).
@@ -477,7 +477,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
- int ast_hashtab_compare_strings_nocase(const void *a, const void *b)
+ int ast_hashtab_compare_strings_nocase(const void *a,
+ const void *b)
\end{verbatim}
\item Description
Returns the result of strcasecmp(a,b).
@@ -486,7 +487,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
-int ast_hashtab_compare_ints(const void *a, const void *b)
+int ast_hashtab_compare_ints(const void *a,
+ const void *b)
\end{verbatim}
\item Description
assume the pointers point to ints, return -1, 0, or 1 if a is less than b,
@@ -561,7 +563,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
- int ast_hashtab_hash_string(const void *obj, int modulus)
+ int ast_hashtab_hash_string(const void *obj,
+ int modulus)
\end{verbatim}
\item Description
Upcase each letter. take the running total, and multiply by 13, and add
@@ -572,7 +575,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
- int ast_hashtab_hash_string_sax(const void *obj, int modulus)
+ int ast_hashtab_hash_string_sax(const void *obj,
+ int modulus)
\end{verbatim}
\item Description
Shifting, Or, and addition. See the code.
@@ -581,7 +585,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
- int ast_hashtab_hash_string_nocase(const void *obj, int modulus)
+ int ast_hashtab_hash_string_nocase(const void *obj,
+ int modulus)
\end{verbatim}
\item Description
Upcase each letter. take the running total, and multiply by 13, and add
@@ -592,7 +597,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
- int ast_hashtab_hash_int(const int x, int modulus)
+ int ast_hashtab_hash_int(const int x,
+ int modulus)
\end{verbatim}
\item Description
Very Basic: modulus applied to x.
@@ -601,7 +607,8 @@
\begin{itemize}
\item Prototype
\begin{verbatim}
- int ast_hashtab_hash_short(const short x, int modulus)
+ int ast_hashtab_hash_short(const short x,
+ int modulus)
\end{verbatim}
\item Description
Very Basic: modulus applied to x.
More information about the asterisk-commits
mailing list