[asterisk-commits] murf: branch murf/datastructs r66979 - in
/team/murf/datastructs: doc/ funcs/
asterisk-commits at lists.digium.com
asterisk-commits at lists.digium.com
Fri Jun 1 22:40:03 MST 2007
Author: murf
Date: Sat Jun 2 00:40:02 2007
New Revision: 66979
URL: http://svn.digium.com/view/asterisk?view=rev&rev=66979
Log:
Checkpoint. Hashtest added to do a brutal test of hashtab in a highly multi-threaded, busy environ. Docs added. Debugged. Things work.
Added:
team/murf/datastructs/doc/hashtab-dialplan.tex (with props)
Modified:
team/murf/datastructs/doc/asterisk.tex
team/murf/datastructs/funcs/func_hashtab.c
Modified: team/murf/datastructs/doc/asterisk.tex
URL: http://svn.digium.com/view/asterisk/team/murf/datastructs/doc/asterisk.tex?view=diff&rev=66979&r1=66978&r2=66979
==============================================================================
--- team/murf/datastructs/doc/asterisk.tex (original)
+++ team/murf/datastructs/doc/asterisk.tex Sat Jun 2 00:40:02 2007
@@ -108,6 +108,11 @@
\section{Queue Logs}
\input{queuelog.tex}
+\Chapter{Data Structures}
+ \input{hashtab.tex}
+ \input{hashtab-dialplan.tex}
+
+
% Generate this using the "core dumpappdocs" CLI command that is present
% when Asterisk is built with dev-mode enabled.
\chapter{Application Reference}
Added: team/murf/datastructs/doc/hashtab-dialplan.tex
URL: http://svn.digium.com/view/asterisk/team/murf/datastructs/doc/hashtab-dialplan.tex?view=auto&rev=66979
==============================================================================
--- team/murf/datastructs/doc/hashtab-dialplan.tex (added)
+++ team/murf/datastructs/doc/hashtab-dialplan.tex Sat Jun 2 00:40:02 2007
@@ -1,0 +1,98 @@
+\subsubsection{Using HashTabs in the Dialplan}
+
+A series of functions were created, to allow using hash tables in the
+dialplan.
+
+What in the heck are hash tables, and who on earth would ever want to
+use them?
+
+First of all, hash tables store objects by a key. And in the case of
+the dialplan hashtabs, the key is a case-insensitive string. And the
+objects stored are also strings.
+
+Next, hashtables are good for only one kind of query: an exact match.
+In this case ``exact'' is case-insensitive. But it does it quick. For
+you computer science guys, O(1). For non-programmers, ideally, it
+looks at exactly one element to find the right one. So if you have a
+million of them, you'll reach into the barrel and pull out the exact
+right one each time. Ideally.
+
+Here's what the dialplan interface can do with hashtables:
+
+\begin{itemize}
+\item Create one and get a ``handle''.
+\item Destroy what you create.
+\item insert a {key, value} pair into the table
+\item remove a {key, value} pair from the table.
+\item look up a {key, value} pair based on the key.
+\item traverse (one at a time) all the keys stored in the table.
+\end{itemize}
+
+You can also use the astdb (DB function) to do the same job; the
+difference is that hashtabs are not persistent (no files are created
+on disk), lighter weight, and hopefully faster.
+
+You can create as many hashtabs as you want/need.
+
+You can put as many or as few items in it as you want/need.
+
+You can mimic array storage. If the keys are ``1'', ``2'', etc,
+you get the same affect as using an array with integer indices.
+You can also do n-dimensional arrays by using keys like ``1,2,4'',
+etc. One advantage to this is, that the arrays can be ``sparse'', with
+not every position filled, and the unused elements will not use up
+space.
+
+These hash tables use read/write locks to protect themselves, in the
+case where you might want to use a single hash table for use by
+multiple channels. (Store the table ``handle'' in a global variable).
+
+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.
+\end{itemize}
+
+Here is a short example of using hashtabs in the dialplan (in AEL format):
+
+\begin{verbatim}
+ 8776 =>
+ {
+ Set(HT=${HASHTAB(S(50))});
+ Set(HASHTAB_ACCESS(${HT},name1)=John);
+ Set(HASHTAB_ACCESS(${HT},name2)=Joseph);
+ Set(HASHTAB_ACCESS(${HT},name3)=Jacob);
+ Set(HASHTAB_ACCESS(${HT},name4)=James);
+ Set(HASHTAB_ACCESS(${HT},name5)=Jello);
+ Set(HASHTAB_ACCESS(${HT},name6)=Jim);
+ Set(HASHTAB_ACCESS(${HT},name7)=Jasper);
+ Set(HASHTAB_ACCESS(${HT},name8)=Jolly);
+ Set(HASHTAB_ACCESS(${HT},name9)=Jennifer);
+ NoOp(There are ${HASHTAB_SIZE(${HT})} elements in the table);
+ Set(HT_IT=${HASHTAB_TRAVERSE(${HT})});
+ while(1)
+ {
+ Set(zz=${HASHTAB_NEXT(${HT_IT})});
+ if("${zz}"=="")
+ break;
+ NoOp(Element ${zz} is in the table);
+ }
+ NoOp(Getting rid of Jennifer -- ${HASHTAB_REMOVE(${HT},name9)} -- Doesn't fit anyway);
+ NoOp(There are NOW ${HASHTAB_SIZE(${HT})} elements in the table);
+ Set(HT_IT=${HASHTAB_TRAVERSE(${HT})});
+ while(1)
+ {
+ Set(zz=${HASHTAB_NEXT(${HT_IT})});
+ if("${zz}"=="")
+ break;
+ NoOp(Element ${zz} is in the table);
+ }
+ NoOp(Closing the Hashtab. ${HASHTAB_DESTROY(${HT})} -- Should be gone now);
+ }
+\end{verbatim}
Propchange: team/murf/datastructs/doc/hashtab-dialplan.tex
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/murf/datastructs/doc/hashtab-dialplan.tex
------------------------------------------------------------------------------
svn:keywords = Author Id Date Revision
Propchange: team/murf/datastructs/doc/hashtab-dialplan.tex
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: team/murf/datastructs/funcs/func_hashtab.c
URL: http://svn.digium.com/view/asterisk/team/murf/datastructs/funcs/func_hashtab.c?view=diff&rev=66979&r1=66978&r2=66979
==============================================================================
--- team/murf/datastructs/funcs/func_hashtab.c (original)
+++ team/murf/datastructs/funcs/func_hashtab.c Sat Jun 2 00:40:02 2007
@@ -268,7 +268,7 @@
initsize = atoi(opt_args[OPT_ARG_INITSIZE]);
}
- ht = ast_hashtab_create(initsize, comparefunc, resizefunc, newsizefunc, hashfunc, 0);
+ ht = ast_hashtab_create(initsize, comparefunc, resizefunc, newsizefunc, hashfunc, 1);
asprintf(&handle, "%lu", (unsigned long)ht);
@@ -293,7 +293,7 @@
" HASHTAB_SIZE(handle) -- returns the number of elements stored in the hashtab\n"
" HASHTAB_TRAVERSE(handle) -- returns a hashtab iterator handle\n"
"A Hashtab iterator can be manipulated with these functions:\n"
- " HASHTAB_NEXT(it_handle) -- returns the first/next element in the hashtab, empty string when done\n",
+" HASHTAB_NEXT(it_handle) -- returns the first/next element in the hashtab, empty string when done\n",
.read = function_hashtab_create
};
More information about the asterisk-commits
mailing list