\hypertarget{LI_8ih}{
\section{LI.ih File Reference}
\label{LI_8ih}\index{LI.ih@{LI.ih}}
}
Interlocked singly linked list, inline versions. 

{\tt \#include \char`\"{}PBI/Inline.h\char`\"{}}\par
{\tt \#include \char`\"{}PBI/Attribute.h\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/L.h\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/L.ih\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/RW.h\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/RW.ih\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/LI.h\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/TOC\_\-comdefs.h\char`\"{}}\par


Include dependency graph for LI.ih:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=384pt]{LI_8ih__incl}
\end{center}
\end{figure}


This graph shows which files directly or indirectly include this file:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=85pt]{LI_8ih__dep__incl}
\end{center}
\end{figure}
\subsection*{Defines}
\begin{CompactItemize}
\item 
\hypertarget{LI_8ih_a0}{
\#define \hyperlink{LI_8ih_a0}{LI\_\-\_\-EXP\_\-PROTO}~INLINE\_\-USR\_\-EXP\_\-PROTO}
\label{LI_8ih_a0}

\begin{CompactList}\small\item\em Export Prototype spec. \item\end{CompactList}\item 
\hypertarget{LI_8ih_a1}{
\#define \hyperlink{LI_8ih_a1}{LI\_\-\_\-LCL\_\-PROTO}~INLINE\_\-USR\_\-LCL\_\-PROTO}
\label{LI_8ih_a1}

\begin{CompactList}\small\item\em Internal Prototype spec. \item\end{CompactList}\item 
\hypertarget{LI_8ih_a2}{
\#define \hyperlink{LI_8ih_a2}{LI\_\-\_\-EXP\_\-FNC}~INLINE\_\-USR\_\-EXP\_\-FNC}
\label{LI_8ih_a2}

\begin{CompactList}\small\item\em Export Function declaration. \item\end{CompactList}\item 
\hypertarget{LI_8ih_a3}{
\#define \hyperlink{LI_8ih_a3}{LI\_\-\_\-LCL\_\-FNC}~INLINE\_\-USR\_\-LCL\_\-FNC}
\label{LI_8ih_a3}

\begin{CompactList}\small\item\em Internal Function declaration. \item\end{CompactList}\item 
\hypertarget{LI_8ih_a4}{
\#define \hyperlink{LI_8ih_a4}{\_\-OK}~ATTR\_\-UNUSED\_\-OK}
\label{LI_8ih_a4}

\begin{CompactList}\small\item\em Abbreviation for ATTR\_\-UNUSED\_\-OK, undefined in this file. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
LI\_\-\_\-EXP\_\-PROTO void \hyperlink{LI_8ih_a5}{LI\_\-\_\-append} (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$dst, \hyperlink{struct__LI__head}{LI\_\-head} $\ast$src) \_\-OK
\begin{CompactList}\small\item\em Appends the {\em src\/} list members to the {\em dst\/} list. \item\end{CompactList}\item 
LI\_\-\_\-EXP\_\-PROTO int \hyperlink{LI_8ih_a6}{LI\_\-\_\-disable} (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$list) \_\-OK
\begin{CompactList}\small\item\em Disables the dequeing of nodes from this list. \item\end{CompactList}\item 
LI\_\-\_\-EXP\_\-PROTO int \hyperlink{LI_8ih_a7}{LI\_\-\_\-enable} (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$list) \_\-OK
\begin{CompactList}\small\item\em Enable the dequeing of nodes from this list. \item\end{CompactList}\item 
LI\_\-\_\-EXP\_\-PROTO int \hyperlink{LI_8ih_a8}{LI\_\-\_\-enabled} (const \hyperlink{struct__LI__head}{LI\_\-head} $\ast$list) \_\-OK
\begin{CompactList}\small\item\em Returns the state of the enabled flag for this list. \item\end{CompactList}\item 
LI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{LI\_\-node} $\ast$ \hyperlink{LI_8ih_a9}{LI\_\-\_\-insert} (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$list, \hyperlink{struct__L__node}{LI\_\-node} $\ast$node) \_\-OK
\begin{CompactList}\small\item\em Adds a node to the tail of a previously initialized list. \item\end{CompactList}\item 
LI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{LI\_\-node} $\ast$ \hyperlink{LI_8ih_a10}{LI\_\-\_\-jam} (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$list, \hyperlink{struct__L__node}{LI\_\-node} $\ast$node) \_\-OK
\begin{CompactList}\small\item\em Adds a node to the head of a previously initialized list. \item\end{CompactList}\item 
LI\_\-\_\-EXP\_\-PROTO void \hyperlink{LI_8ih_a11}{LI\_\-\_\-prepend} (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$dst, \hyperlink{struct__LI__head}{LI\_\-head} $\ast$src) \_\-OK
\begin{CompactList}\small\item\em Prepends the {\em src\/} list members to the {\em dst\/} list. \item\end{CompactList}\item 
LI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{LI\_\-node} $\ast$ \hyperlink{LI_8ih_a12}{LI\_\-\_\-remove} (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$list) \_\-OK
\begin{CompactList}\small\item\em Removes the node from the tail of a previously initialized list. An empty list returns NULL as its node. \item\end{CompactList}\item 
LI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{LI\_\-node} $\ast$ \hyperlink{LI_8ih_a13}{LI\_\-\_\-remove\-W} (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$list) \_\-OK
\begin{CompactList}\small\item\em Removes the node from the tail of a previously initialized linked list. If the list is empty, the thread of code is blocked until a node becomes available. \item\end{CompactList}\item 
LI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{LI\_\-node} $\ast$ \hyperlink{LI_8ih_a14}{LI\_\-\_\-remove\-W\_\-toc} (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$list, const \hyperlink{struct__TOC}{TOC} $\ast$toc) \_\-OK
\begin{CompactList}\small\item\em Removes the node from the tail of a previously initialized linked list. If the list is empty, the thread of code is blocked until a node becomes available or the timeout expires. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Interlocked singly linked list, inline versions. 

\begin{Desc}
\item[Author:]JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc}


\footnotesize\begin{verbatim}    CVS $Id: LI.ih,v 1.1.1.1 2006/02/10 21:45:35 saxton Exp $
\end{verbatim}
\normalsize


\begin{Desc}
\item[SYNOPSIS]This defines the inline interlocked versions of the singly linked list routines. These routines are thread-safe\end{Desc}
See also the non-inlined versions of these routines which offer possible savings in code space and increased modularity at the expense of some performance. The L routines provide the same functionality without the overhead of being interlocked.

\subsection{Function Documentation}
\hypertarget{LI_8ih_a5}{
\index{LI.ih@{LI.ih}!LI__append@{LI\_\-\_\-append}}
\index{LI__append@{LI\_\-\_\-append}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-append]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC void LI\_\-\_\-append (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em dst}, \hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em src})}}
\label{LI_8ih_a5}


Appends the {\em src\/} list members to the {\em dst\/} list. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dst}]A previously initialized list acting as the destination \item[{\em src}]A previously initialized list acting as the source\end{description}
\end{Desc}
Appends the source list to the destination list. After this operation the destination list will have consist of its original members followed by the members on the source list. The source list will be empty.\hypertarget{LI_8ih_a6}{
\index{LI.ih@{LI.ih}!LI__disable@{LI\_\-\_\-disable}}
\index{LI__disable@{LI\_\-\_\-disable}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-disable]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC int LI\_\-\_\-disable (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em list})}}
\label{LI_8ih_a6}


Disables the dequeing of nodes from this list. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em list}]A previously initialized list. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]= List was previously disabled \item[{\em !=0}]= List was previously enabled\end{description}
\end{Desc}
Any items on the que and any items placed on the que after the disable call will not be dequed by any of the LI\_\-\_\-remove\-XXX routines. Delivery of these items may resume after a call to {\em \hyperlink{LI_8ih_a7}{LI\_\-\_\-enable()}\/}.

\begin{Desc}
\item[Warning:]Be cautious with this routine. It is very easy to deadlock the system by having the same task disable the que and place items on the que. Sooner or later in this situation the source of items to be placed on the que will become exhausted. If the user is getting these items from a resource that blocks when it the pool of items becomes exhausted, no call to issue a LI\_\-\_\-enable can be made, {\em i.e\/}. deadlock.\end{Desc}
To avoid this situation, either separate the task controlling the queue via LI\_\-\_\-disable's and LI\_\-\_\-enables' from the task allocating new items for the que or, if in the same task, cease to allocate new items when the LI list has been disabled.\hypertarget{LI_8ih_a7}{
\index{LI.ih@{LI.ih}!LI__enable@{LI\_\-\_\-enable}}
\index{LI__enable@{LI\_\-\_\-enable}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-enable]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC int LI\_\-\_\-enable (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em list})}}
\label{LI_8ih_a7}


Enable the dequeing of nodes from this list. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em list}]A previously initialized list. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]= List was previously disabled \item[{\em !=0}]= List was previously enabled\end{description}
\end{Desc}
After issuing this call the LI\_\-\_\-remove routines will deliver items once again. If any LI\_\-\_\-remove call is currently waiting on a non-empty list, a wakeup call is issued, permitting nodes to be dequed.\hypertarget{LI_8ih_a8}{
\index{LI.ih@{LI.ih}!LI__enabled@{LI\_\-\_\-enabled}}
\index{LI__enabled@{LI\_\-\_\-enabled}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-enabled]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC int LI\_\-\_\-enabled (const \hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em list})}}
\label{LI_8ih_a8}


Returns the state of the enabled flag for this list. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em list}]A previously initialized list. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]List is currently disabled \item[{\em !=0}]List is currently enabled\end{description}
\end{Desc}
\begin{Desc}
\item[Warning:]As with all queries of this type, the answer is only good until it changes. The user is cautioned on its usage. It is primarily provided as a debugging tool.\end{Desc}
\hypertarget{LI_8ih_a9}{
\index{LI.ih@{LI.ih}!LI__insert@{LI\_\-\_\-insert}}
\index{LI__insert@{LI\_\-\_\-insert}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-insert]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{LI\_\-node} $\ast$ LI\_\-\_\-insert (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em list}, \hyperlink{struct__L__node}{LI\_\-node} $\ast$ {\em node})}}
\label{LI_8ih_a9}


Adds a node to the tail of a previously initialized list. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em list}]A previously initialized list. \item[{\em node}]The node to add at the tail of the list. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to the old backward link. This can be used to test whether this was the first item on the list. \par
 If return\_\-value == list, the empty)\end{Desc}
Adds the specified node to the tail of the list. If all nodes are added with the LI\_\-\_\-insert routine, the list behaves as a FIFO.\hypertarget{LI_8ih_a10}{
\index{LI.ih@{LI.ih}!LI__jam@{LI\_\-\_\-jam}}
\index{LI__jam@{LI\_\-\_\-jam}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-jam]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{LI\_\-node} $\ast$ LI\_\-\_\-jam (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em list}, \hyperlink{struct__L__node}{LI\_\-node} $\ast$ {\em node})}}
\label{LI_8ih_a10}


Adds a node to the head of a previously initialized list. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em list}]A previously initialized list. \item[{\em node}]The node to add. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to the old forward link. This can be used to test whether this was the first item on the list. \par
 If return\_\-value == list, the empty)\end{Desc}
Adds the specified node to the head of the list. If all nodes are added with the LI\_\-\_\-jam routine, the list behaves as a LIFO.\hypertarget{LI_8ih_a11}{
\index{LI.ih@{LI.ih}!LI__prepend@{LI\_\-\_\-prepend}}
\index{LI__prepend@{LI\_\-\_\-prepend}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-prepend]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC void LI\_\-\_\-prepend (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em dst}, \hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em src})}}
\label{LI_8ih_a11}


Prepends the {\em src\/} list members to the {\em dst\/} list. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dst}]A previously initialized list acting as the destination \item[{\em src}]A previously initialized list acting as the source\end{description}
\end{Desc}
Prepends the source list to the destination list. After this operation the destination list will have consist of its original members preceded by the members on the source list. The source list will be empty.\hypertarget{LI_8ih_a12}{
\index{LI.ih@{LI.ih}!LI__remove@{LI\_\-\_\-remove}}
\index{LI__remove@{LI\_\-\_\-remove}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-remove]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{LI\_\-node} $\ast$ LI\_\-\_\-remove (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em list})}}
\label{LI_8ih_a12}


Removes the node from the tail of a previously initialized list. An empty list returns NULL as its node. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em list}]A previously initialized list. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the removed node of NULL if the list is empty.\end{Desc}
Removes the node at the head of the list. If the list is empty, NULL is returned.\hypertarget{LI_8ih_a13}{
\index{LI.ih@{LI.ih}!LI__removeW@{LI\_\-\_\-removeW}}
\index{LI__removeW@{LI\_\-\_\-removeW}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-removeW]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{LI\_\-node} $\ast$ LI\_\-\_\-remove\-W (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em list})}}
\label{LI_8ih_a13}


Removes the node from the tail of a previously initialized linked list. If the list is empty, the thread of code is blocked until a node becomes available. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em list}]A previously initialized list \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the removed node or NULL on error or timeout.\end{Desc}
\hypertarget{LI_8ih_a14}{
\index{LI.ih@{LI.ih}!LI__removeW_toc@{LI\_\-\_\-removeW\_\-toc}}
\index{LI__removeW_toc@{LI\_\-\_\-removeW\_\-toc}!LI.ih@{LI.ih}}
\subsubsection[LI\_\-\_\-removeW\_\-toc]{\setlength{\rightskip}{0pt plus 5cm}LI\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{LI\_\-node} $\ast$ LI\_\-\_\-remove\-W\_\-toc (\hyperlink{struct__LI__head}{LI\_\-head} $\ast$ {\em list}, const \hyperlink{struct__TOC}{TOC} $\ast$ {\em toc})}}
\label{LI_8ih_a14}


Removes the node from the tail of a previously initialized linked list. If the list is empty, the thread of code is blocked until a node becomes available or the timeout expires. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em list}]A previously initialized list \item[{\em toc}]The timeout control structure. Maybe specified as either TOC\_\-NOWAIT or TOC\_\-FOREVER. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the removed node or NULL on error or timeout.\end{Desc}