[asterisk-commits] murf: branch murf/datastructs r72558 - /team/murf/datastructs/doc/hashtab.tex

[SVN commits to the Asterisk project]

Author: murf
Date: Fri Jun 29 00:00:38 2007
New Revision: 72558

URL: http://svn.digium.com/view/asterisk?view=rev&rev=72558
Log:
Updated the docs to include the 5 new locking funcs

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=72558&r1=72557&r2=72558
==============================================================================
--- team/murf/datastructs/doc/hashtab.tex (original)
+++ team/murf/datastructs/doc/hashtab.tex Fri Jun 29 00:00:38 2007
@@ -16,7 +16,7 @@
 When two object keys hash to the same value, their objects are put into a doubly-linked
 list in the hash table. Thus, each entry in a hash table is a list head. The ideal
 situation is to keep the list lengths to 1 as a maximum. If the hash table had
-a 100-element array allocated, it could store 1000 elements; lookups would just be
+a 100-element array allocated, it could store 1000 (or more!) elements; lookups would just be
 slower, as any lookup would have to sift thru an average of 10/2 = 5 objects (assuming
 the hashing function evenly spreads out the data). This
 is why resizing the hashtable is a nice feature, if the number of elements cannot
@@ -157,6 +157,17 @@
 
 In a non-locked mode, you can remove the element you got from \verb+ast_hashtab_next+ with
 no problem.
+
+For coupling operations at a higher level, with locking, you can create a non-locked table 
+and use these functions to do your own locking:
+\begin{itemize}
+\item \verb+ast_hashtab_initlock+: use this to initialize the lock in the hashtable.
+\item \verb+ast_hashtab_wrlock+: use this to obtain a write-lock for the hashtable.
+\item \verb+ast_hashtab_rdlock+: use this to obtain a read-lock for the hashtable.
+\item \verb+ast_hashtab_unlock+: use this to release a lock (read or write).
+\item \verb+ast_hashtab_destroylock+: use this to free lock allocations. Do this before you throw away the hashtable.
+\end{itemize}
+
 
 \subsubsection{Hashtab Methods}
 
@@ -450,6 +461,77 @@
 granted. Do not use this in any other fashion, unless you do not need locking.
 
 \end{itemize}
+\item \verb+ast_hashtab_initlock+
+\begin{itemize}
+\item Prototype
+\begin{verbatim}
+int  ast_hashtab_initlock(struct ast_hashtab *tab);
+\end{verbatim}
+\item Description
+This function initializes the r/w lock for the hashtab whose
+pointer you supply. Make sure to destroy it before destroying
+the table, when you are done using it.
+
+This function should be called before trying any of the other
+user controlled locking routines.
+
+The hash table should have been created without any locking. If it has
+been created with locking, you may find yourself in interesting
+deadlock situations!
+
+\end{itemize}
+\item \verb+ast_hashtab_wrlock+
+\begin{itemize}
+\item Prototype
+\begin{verbatim}
+int  ast_hashtab_wrlock(struct ast_hashtab *tab);
+\end{verbatim}
+\item Description
+This function will attempt to obtain a write lock for the
+hashtab instance. This may involve some waiting  until
+all currently read-locked finish their tasks and release
+their locks. No read locks will be granted until the write
+lock is released. Only one write lock will be granted
+at a time.
+
+\end{itemize}
+\item \verb+ast_hashtab_rdlock+
+\begin{itemize}
+\item Prototype
+\begin{verbatim}
+int  ast_hashtab_rdlock(struct ast_hashtab *tab);
+\end{verbatim}
+\item Description
+This function will attempt to obtain a read lock for the
+hashtab instance. This may involve waiting until a write
+lock is released. No write-locks will be granted while any
+read-locks are in force. Many read locks may be granted
+simultaneously.
+
+\end{itemize}
+\item \verb+ast_hashtab_unlock+
+\begin{itemize}
+\item Prototype
+\begin{verbatim}
+int  ast_hashtab_unlock(struct ast_hashtab *tab);
+\end{verbatim}
+\item Description
+This function can be used to release either a write
+or a read lock, that has been previously granted.
+
+\end{itemize}
+\item \verb+ast_hashtab_destroylock+
+\begin{itemize}
+\item Prototype
+\begin{verbatim}
+int  ast_hashtab_destroylock(struct ast_hashtab *tab);
+\end{verbatim}
+\item Description
+This function releases any memory allocated for a lock.
+Use this function before destroying a hashtab, if you have
+initialized the lock yourself.
+
+\end{itemize}
 \end{itemize}