[asterisk-commits] murf: branch murf/datastructs r66980 -
/team/murf/datastructs/doc/
asterisk-commits at lists.digium.com
asterisk-commits at lists.digium.com
Sat Jun 2 21:28:00 MST 2007
Author: murf
Date: Sat Jun 2 23:27:59 2007
New Revision: 66980
URL: http://svn.digium.com/view/asterisk?view=rev&rev=66980
Log:
Some corrections to the tex files to make my docs acceptable to latex.
Modified:
team/murf/datastructs/doc/asterisk.tex
team/murf/datastructs/doc/hashtab-dialplan.tex
team/murf/datastructs/doc/hashtab.tex
Modified: team/murf/datastructs/doc/asterisk.tex
URL: http://svn.digium.com/view/asterisk/team/murf/datastructs/doc/asterisk.tex?view=diff&rev=66980&r1=66979&r2=66980
==============================================================================
--- team/murf/datastructs/doc/asterisk.tex (original)
+++ team/murf/datastructs/doc/asterisk.tex Sat Jun 2 23:27:59 2007
@@ -108,7 +108,7 @@
\section{Queue Logs}
\input{queuelog.tex}
-\Chapter{Data Structures}
+\chapter{Data Structures}
\input{hashtab.tex}
\input{hashtab-dialplan.tex}
Modified: team/murf/datastructs/doc/hashtab-dialplan.tex
URL: http://svn.digium.com/view/asterisk/team/murf/datastructs/doc/hashtab-dialplan.tex?view=diff&rev=66980&r1=66979&r2=66980
==============================================================================
--- team/murf/datastructs/doc/hashtab-dialplan.tex (original)
+++ team/murf/datastructs/doc/hashtab-dialplan.tex Sat Jun 2 23:27:59 2007
@@ -50,13 +50,13 @@
Here's the functions:
\begin{itemize}
-\item HASHTAB(<options>) -- to create a hash table and return a ``handle''.
-\item HASHTAB_ACCESS(handle, key) -- to read/write entries into the table.
-\item HASHTAB_REMOVE(handle, key) -- to remove an entry from the table
-\item HASHTAB_DESTROY(handle) -- to free the table's memory
-\item HASHTAB_SIZE(handle) -- to get the number of elements stored in the table.
-\item HASHTAB_TRAVERSE(handle) -- returns an ``iterator''
-\item HASHTAB_NEXT(iterator_handle) -- call over and over to get the elements stored in the table.
+\item \verb+HASHTAB(<options>)+ -- to create a hash table and return a ``handle''.
+\item \verb+HASHTAB_ACCESS(handle, key)+ -- to read/write entries into the table.
+\item \verb+HASHTAB_REMOVE(handle, key)+ -- to remove an entry from the table
+\item \verb+HASHTAB_DESTROY(handle)+ -- to free the table's memory
+\item \verb+HASHTAB_SIZE(handle)+ -- to get the number of elements stored in the table.
+\item \verb+HASHTAB_TRAVERSE(handle)+ -- returns an ``iterator''
+\item \verb+HASHTAB_NEXT(iterator_handle)+ -- call over and over to get the elements stored in the table.
\end{itemize}
Here is a short example of using hashtabs in the dialplan (in AEL format):
Modified: team/murf/datastructs/doc/hashtab.tex
URL: http://svn.digium.com/view/asterisk/team/murf/datastructs/doc/hashtab.tex?view=diff&rev=66980&r1=66979&r2=66980
==============================================================================
--- team/murf/datastructs/doc/hashtab.tex (original)
+++ team/murf/datastructs/doc/hashtab.tex Sat Jun 2 23:27:59 2007
@@ -86,7 +86,7 @@
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
-we simply provide the /verb+ast_hashtab_resize_java+ and /verb+ast_hashtab_newsize_java+
+we simply provide the \verb+ast_hashtab_resize_java+ and \verb+ast_hashtab_newsize_java+
function pointers:
\begin{verbatim}
@@ -96,7 +96,7 @@
my_hash, 0);
\end{verbatim}
-To look up a key in the table, use the /verb+ast_hashtab_lookup+ function,
+To look up a key in the table, use the \verb+ast_hashtab_lookup+ function,
which returns the object pointer of the object with that key, or NULL. But,
here is the hitch: An object is opaque to hashtab, so to find an object,
you have to supply an object with the key you are looking for. Thus, it can
@@ -115,7 +115,7 @@
To add elements to the hash table, there are a few different functions you can
use. You need to keep in mind that it is possible to enter the same object multiple
times into a hashtable. This is highly undesirable! So, either look up your key
-first, and if it is not there, insert the new entry, or use the /verb+ast_hashtab_insert_safe+
+first, and if it is not there, insert the new entry, or use the \verb+ast_hashtab_insert_safe+
function, which will efficiently insert your struct if it isn't already in the table.
(If it is, it does nothing!).
@@ -140,18 +140,18 @@
\subsubsection{Hashtab Locking}
-If the locking argument to /verb+ast_hashtab_create+ is non-zero, hashtab will use
+If the locking argument to \verb+ast_hashtab_create+ is non-zero, hashtab will use
read-write locks to make the code multi-thread safe. There is one drawback:
if locking is turned on, you cannot remove an element while you are traversing
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 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.
-
-In a non-locked mode, you can remove the element you got from /verb+ast_hashtab_next+ with
+or \verb+ast_hashtab_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.
+
+In a non-locked mode, you can remove the element you got from \verb+ast_hashtab_next+ with
no problem.
\subsubsection{Hashtab Methods}
@@ -159,7 +159,7 @@
Here is a list of the functions that manipulate hashtabs:
\begin{itemize}
-\item ast_hashtab_create
+\item \verb+ast_hashtab_create+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -181,10 +181,10 @@
return a non-zero number if the hash table should be resized. The newsize function will be
called at that time, to determine what the new size of the array should be. This number
will be incremented until it is a prime number, if it is not prime.
-The do_locking argument will cause the hashtab to use locking if it is non-zero.
-
-\end{itemize}
-\item ast_hashtab_destroy
+The \verb+do_locking argument+ will cause the hashtab to use locking if it is non-zero.
+
+\end{itemize}
+\item \verb+ast_hashtab_destroy+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -195,7 +195,7 @@
Don't try to keep using the table. It's gone!
\end{itemize}
-\item ast_hashtab_insert_immediate
+\item \verb+ast_hashtab_insert_immediate+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -206,7 +206,7 @@
object in the table. It requests a write lock.
\end{itemize}
-\item ast_hashtab_insert_immediate_bucket
+\item \verb+ast_hashtab_insert_immediate_bucket+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -222,7 +222,7 @@
instead.
\end{itemize}
-\item ast_hashtab_insert_safe
+\item \verb+ast_hashtab_insert_safe+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -235,7 +235,7 @@
It requests a write lock.
\end{itemize}
-\item ast_hashtab_lookup
+\item \verb+ast_hashtab_lookup+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -247,7 +247,7 @@
object was not found, it returns NULL. It sets a read lock.
\end{itemize}
-\item ast_hashtab_lookup_bucket
+\item \verb+ast_hashtab_lookup_bucket+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -262,7 +262,7 @@
may become obsolete if the table is resized.
\end{itemize}
-\item ast_hashtab_get_stats
+\item \verb+ast_hashtab_get_stats+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -272,19 +272,19 @@
This routine will fill in the numbers whose addresses you supply in the arg list,
with the relevant values stored in the hashtab itself. They are:
\begin{itemize}
-\item biggest_bucket_size
+\item \verb+biggest_bucket_size+
This value indicates the longest bucket chain in the bucket array. If it is greater than
1, there might be a problem, either with the hashing algorithm, or the size of the table.
-\item resize_count
+\item \verb+resize_count+
This is the number of times this table has been resized.
-\item num_objects
+\item \verb+num_objects+
This is the number of objects stored in this table.
-\item num_buckets
+\item \verb+num_buckets+
This is the size of the bucket array in this table.
\end{itemize}
\end{itemize}
-\item ast_hashtab_size
+\item \verb+ast_hashtab_size+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -294,7 +294,7 @@
This routine returns the number of objects that have been inserted into this hashtab.
\end{itemize}
-\item ast_hashtab_capacity
+\item \verb+ast_hashtab_capacity+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -304,7 +304,7 @@
This function returns the number of hash buckets allocated in the hashtab array.
\end{itemize}
-\item ast_hashtab_start_traversal
+\item \verb+ast_hashtab_start_traversal+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -322,7 +322,7 @@
or \verb+ast_hashtab_remove_this_object_nolock+ to actually remove the objects.
\end{itemize}
-\item ast_hashtab_start_write_traversal
+\item \verb+ast_hashtab_start_write_traversal+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -342,7 +342,7 @@
\end{itemize}
-\item ast_hashtab_next
+\item \verb+ast_hashtab_next+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -354,11 +354,11 @@
When no more objects exist to be traversed, this function returns a NULL.
If locking has been requested, do not even think about trying to
-remove objects returned by ast_hashtab_next, unless you start the traversal
+remove objects returned by \verb+ast_hashtab_next+, unless you start the traversal
with \verb+ast_hashtab_start_write_traversal+ !
\end{itemize}
-\item ast_hashtab_end_traversal
+\item \verb+ast_hashtab_end_traversal+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -366,12 +366,12 @@
\end{verbatim}
\item Description
This function frees up memory associated with the iterator. Use it after a traversal
-finishes, or you'll be building up memory leaks! Also, since the start_traversal
+finishes, or you'll be building up memory leaks! Also, since the \verb+start_traversal+
routine requests a read lock, this function will release that lock. Don't forget to
call this routine!
\end{itemize}
-\item ast_hashtab_remove_object_via_lookup
+\item \verb+ast_hashtab_remove_object_via_lookup+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -383,7 +383,7 @@
This function requests a write lock.
\end{itemize}
-\item ast_hashtab_remove_this_object
+\item \verb+ast_hashtab_remove_this_object+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -396,7 +396,7 @@
a NULL is returned, and nothing is done. This function requests a write lock.
\end{itemize}
-\item ast_hashtab_remove_object_via_lookup
+\item \verb+ast_hashtab_remove_object_via_lookup+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -408,7 +408,7 @@
This function requests a write lock.
\end{itemize}
-\item ast_hashtab_remove_this_object
+\item \verb+ast_hashtab_remove_this_object+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -421,7 +421,7 @@
a NULL is returned, and nothing is done. This function requests a write lock.
\end{itemize}
-\item ast_hashtab_remove_object_via_lookup_nolock
+\item \verb+ast_hashtab_remove_object_via_lookup_nolock+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -435,7 +435,7 @@
granted. Do not use this in any other fashion, unless you do not need locking.
\end{itemize}
-\item ast_hashtab_remove_this_object_nolock
+\item \verb+ast_hashtab_remove_this_object_nolock+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -463,7 +463,7 @@
You may not like or need any of them. It's totally up to you, the developer!
\begin{itemize}
-\item ast_hashtab_compare_strings
+\item \verb+ast_hashtab_compare_strings+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -473,7 +473,7 @@
Returns the result of strcmp(a,b).
\end{itemize}
-\item ast_hashtab_compare_strings_nocase
+\item \verb+ast_hashtab_compare_strings_nocase+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -482,7 +482,7 @@
\item Description
Returns the result of strcasecmp(a,b).
\end{itemize}
-\item ast_hashtab_compare_ints
+\item \verb+ast_hashtab_compare_ints+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -493,7 +493,7 @@
a equals b, a is greater than b, respectively.
\end{itemize}
-\item ast_hashtab_compare_shorts
+\item \verb+ast_hashtab_compare_shorts+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -503,7 +503,7 @@
assume the pointers point to shorts, return -1, 0, or 1 if a is less than b,
a equals b, a is greater than b, respectively.
\end{itemize}
-\item ast_hashtab_resize_java
+\item \verb+ast_hashtab_resize_java+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -512,7 +512,7 @@
\item Description
Returns 1 when the number of elements reaches 75% of the size of the array.
\end{itemize}
-\item ast_hashtab_resize_tight
+\item \verb+ast_hashtab_resize_tight+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -521,7 +521,7 @@
\item Description
Returns 1 when the number of elements exceeds the size of the array.
\end{itemize}
-\item ast_hashtab_resize_none
+\item \verb+ast_hashtab_resize_none+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -530,7 +530,7 @@
\item Description
Always returns 0.
\end{itemize}
-\item ast_hashtab_newsize_java
+\item \verb+ast_hashtab_newsize_java+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -539,7 +539,7 @@
\item Description
Returnshe lowest prime number at or above 2 times the current table size.
\end{itemize}
-\item ast_hashtab_newsize_tight
+\item \verb+ast_hashtab_newsize_tight+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -548,7 +548,7 @@
\item Description
Returns 1.5 x the current size. (rounding up to the next higher prime, of course)
\end{itemize}
-\item ast_hashtab_newsize_none
+\item \verb+ast_hashtab_newsize_none+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -557,7 +557,7 @@
\item Description
Returns the current size.
\end{itemize}
-\item ast_hashtab_hash_string
+\item \verb+ast_hashtab_hash_string+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -568,7 +568,7 @@
the character value. Repeat till all characters in the string are blended
in. Then take the modulus of that total.
\end{itemize}
-\item ast_hashtab_hash_string_sax
+\item \verb+ast_hashtab_hash_string_sax+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -577,7 +577,7 @@
\item Description
Shifting, Or, and addition. See the code.
\end{itemize}
-\item ast_hashtab_hash_string_nocase
+\item \verb+ast_hashtab_hash_string_nocase+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -588,7 +588,7 @@
the character value. Repeat till all characters in the string are blended
in. Then take the modulus of that total.
\end{itemize}
-\item int ast_hashtab_hash_int
+\item int \verb+ast_hashtab_hash_int+
\begin{itemize}
\item Prototype
\begin{verbatim}
@@ -597,7 +597,7 @@
\item Description
Very Basic: modulus applied to x.
\end{itemize}
-\item ast_hashtab_hash_short
+\item \verb+ast_hashtab_hash_short+
\begin{itemize}
\item Prototype
\begin{verbatim}
More information about the asterisk-commits
mailing list