\hypertarget{LLI_8ih}{
\section{LLI.ih File Reference}
\label{LLI_8ih}\index{LLI.ih@{LLI.ih}}
}
Defines the inline Linked List Interlocked (LLI) routines. 


{\tt \#include \char`\"{}BBC/LL.ih\char`\"{}}\par
{\tt \#include \char`\"{}BBC/inline.h\char`\"{}}\par
{\tt \#include \char`\"{}BBC/LLI\_\-pubdefs.h\char`\"{}}\par
\subsection*{Defines}
\begin{CompactItemize}
\item 
\#define \hyperlink{LLI_8ih_a0}{LLI\_\-\_\-EXT\_\-PROTO}\ INLINE\_\-USR\_\-EXT\_\-PROTO
\item 
\#define \hyperlink{LLI_8ih_a1}{LLI\_\-\_\-LCL\_\-PROTO}\ INLINE\_\-USR\_\-LCL\_\-PROTO
\item 
\#define \hyperlink{LLI_8ih_a2}{LLI\_\-\_\-EXT\_\-FNC}\ INLINE\_\-USR\_\-EXT\_\-FNC
\item 
\#define \hyperlink{LLI_8ih_a3}{LLI\_\-\_\-LCL\_\-FNC}\ INLINE\_\-USR\_\-LCL\_\-FNC
\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
LLI\_\-\_\-EXT\_\-PROTO int \hyperlink{LLI_8ih_a4}{LLI\_\-\_\-init} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list, enum \hyperlink{LLI__type_8h_a4}{\_\-LLI\_\-type} type)
\begin{CompactList}\small\item\em Initializes the list head of a doubly linked list to an empty list.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO int \hyperlink{LLI_8ih_a5}{LLI\_\-\_\-destroy} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list)
\begin{CompactList}\small\item\em Destroys the data structures associate with a linked list.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO struct \_\-LLI\_\-node $\ast$ \hyperlink{LLI_8ih_a6}{LLI\_\-\_\-insert} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list, struct \_\-LLI\_\-node $\ast$node)
\begin{CompactList}\small\item\em Adds a node to the tail of a previously initialized linked list.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO struct \_\-LLI\_\-node $\ast$ \hyperlink{LLI_8ih_a7}{LLI\_\-\_\-jam} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list, struct \_\-LLI\_\-node $\ast$node)
\begin{CompactList}\small\item\em Adds a node to the head of a previously initialized linked list.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO struct \_\-LLI\_\-node $\ast$ \hyperlink{LLI_8ih_a8}{LLI\_\-\_\-remove} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list)
\begin{CompactList}\small\item\em Removes the node from the tail of a previously initialized linked list. An empty list returns NULL as its node.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO int \hyperlink{LLI_8ih_a9}{LLI\_\-\_\-lock\_\-init} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list, enum \hyperlink{LLI__type_8h_a4}{\_\-LLI\_\-type} type)
\begin{CompactList}\small\item\em This initializes the blocking control structures.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO LLI\_\-key \hyperlink{LLI_8ih_a10}{LLI\_\-\_\-lock} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list)
\begin{CompactList}\small\item\em This routine blocks until a node becomes available.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO void \hyperlink{LLI_8ih_a11}{LLI\_\-\_\-unlock} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list, LLI\_\-key key)
\begin{CompactList}\small\item\em This routine unblocks the previously block list.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO int \hyperlink{LLI_8ih_a12}{LLI\_\-\_\-wake} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list)
\begin{CompactList}\small\item\em This provides the signaling mechanism to wake up a thread of code which was previously blocked.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO int \hyperlink{LLI_8ih_a13}{LLI\_\-\_\-lock\_\-destroy} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list)
\begin{CompactList}\small\item\em Frees any resources associated with the blocking mechanism.\item\end{CompactList}\item 
LLI\_\-\_\-EXT\_\-PROTO struct \_\-LLI\_\-node $\ast$ \hyperlink{LLI_8ih_a14}{LLI\_\-\_\-remove\-W} (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$list, int timeout)
\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}\end{CompactItemize}


\subsection{Detailed Description}
Defines the inline Linked List Interlocked (LLI) routines.



\begin{Desc}
\item[Author: ]\par
JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc}
This defines the inline interlocked versions of the Linked List routines.  These allow the user to build interlocked doubly linked lists. These routines parallel some of the functionality of the Vx\-Works {\em ll\-XXXX} routines, but are portable to both Vx\-Works and host platforms.

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 LL routines provide the same functionality without the overhead of being interlocked.



\subsection{Define Documentation}
\hypertarget{LLI_8ih_a2}{
\index{LLI.ih@{LLI.ih}!LLI__EXT_FNC@{LLI\_\-\_\-EXT\_\-FNC}}
\index{LLI__EXT_FNC@{LLI\_\-\_\-EXT\_\-FNC}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-EXT\_\-FNC]{\setlength{\rightskip}{0pt plus 5cm}\#define LLI\_\-\_\-EXT\_\-FNC\ INLINE\_\-USR\_\-EXT\_\-FNC}}
\label{LLI_8ih_a2}


External Function declaration \hypertarget{LLI_8ih_a0}{
\index{LLI.ih@{LLI.ih}!LLI__EXT_PROTO@{LLI\_\-\_\-EXT\_\-PROTO}}
\index{LLI__EXT_PROTO@{LLI\_\-\_\-EXT\_\-PROTO}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-EXT\_\-PROTO]{\setlength{\rightskip}{0pt plus 5cm}\#define LLI\_\-\_\-EXT\_\-PROTO\ INLINE\_\-USR\_\-EXT\_\-PROTO}}
\label{LLI_8ih_a0}


External Prototype spec \hypertarget{LLI_8ih_a3}{
\index{LLI.ih@{LLI.ih}!LLI__LCL_FNC@{LLI\_\-\_\-LCL\_\-FNC}}
\index{LLI__LCL_FNC@{LLI\_\-\_\-LCL\_\-FNC}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-LCL\_\-FNC]{\setlength{\rightskip}{0pt plus 5cm}\#define LLI\_\-\_\-LCL\_\-FNC\ INLINE\_\-USR\_\-LCL\_\-FNC}}
\label{LLI_8ih_a3}


Internal Function declaration \hypertarget{LLI_8ih_a1}{
\index{LLI.ih@{LLI.ih}!LLI__LCL_PROTO@{LLI\_\-\_\-LCL\_\-PROTO}}
\index{LLI__LCL_PROTO@{LLI\_\-\_\-LCL\_\-PROTO}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-LCL\_\-PROTO]{\setlength{\rightskip}{0pt plus 5cm}\#define LLI\_\-\_\-LCL\_\-PROTO\ INLINE\_\-USR\_\-LCL\_\-PROTO}}
\label{LLI_8ih_a1}


Internal Prototype spec 

\subsection{Function Documentation}
\hypertarget{LLI_8ih_a5}{
\index{LLI.ih@{LLI.ih}!LLI__destroy@{LLI\_\-\_\-destroy}}
\index{LLI__destroy@{LLI\_\-\_\-destroy}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-destroy]{\setlength{\rightskip}{0pt plus 5cm}LLI\_\-\_\-EXT\_\-FNC int LLI\_\-\_\-destroy (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list})}}
\label{LLI_8ih_a5}


Destroys the data structures associate with a linked list.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]Pointer to the link list head to destroy.\end{description}
\end{Desc}
Currently this routine is effectively a NO-OP, but is provided for upward compatibility, just in case at some time in the future this operations does something meaningful. \hypertarget{LLI_8ih_a4}{
\index{LLI.ih@{LLI.ih}!LLI__init@{LLI\_\-\_\-init}}
\index{LLI__init@{LLI\_\-\_\-init}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-init]{\setlength{\rightskip}{0pt plus 5cm}LLI\_\-\_\-EXT\_\-FNC int LLI\_\-\_\-init (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list}, enum \hyperlink{LLI__type_8h_a4}{\_\-LLI\_\-type} {\em type})}}
\label{LLI_8ih_a4}


Initializes the list head of a doubly linked list to an empty list.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]Pointer to the link list head to initialize. \item[{\em 
type}]The type of interlocking linked list\end{description}
\end{Desc}
The linked list head is initialized to an empty list. This must be done before performing any other operations on the linked list. The {\em type} determines how the linked list blocks when one attempts to remove a node from an empty list. \hypertarget{LLI_8ih_a6}{
\index{LLI.ih@{LLI.ih}!LLI__insert@{LLI\_\-\_\-insert}}
\index{LLI__insert@{LLI\_\-\_\-insert}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-insert]{\setlength{\rightskip}{0pt plus 5cm}LLI\_\-\_\-EXT\_\-FNC struct \_\-LLI\_\-node $\ast$ LLI\_\-\_\-insert (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list}, struct \_\-LLI\_\-node $\ast$ {\em node})}}
\label{LLI_8ih_a6}


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

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]A previously initialized linked list head. \item[{\em 
node}]The node to add at the tail of the list \end{description}
\end{Desc}
\begin{Desc}
\item[Returns: ]\par
Pointer to the old backward link. This can be used to test  whether this was the first item on the queue. \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 LLI\_\-\_\-insert routine, the list behaves as a FIFO. \hypertarget{LLI_8ih_a7}{
\index{LLI.ih@{LLI.ih}!LLI__jam@{LLI\_\-\_\-jam}}
\index{LLI__jam@{LLI\_\-\_\-jam}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-jam]{\setlength{\rightskip}{0pt plus 5cm}LLI\_\-\_\-EXT\_\-FNC struct \_\-LLI\_\-node $\ast$ LLI\_\-\_\-jam (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list}, struct \_\-LLI\_\-node $\ast$ {\em node})}}
\label{LLI_8ih_a7}


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

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]A previously initialized linked list head. \item[{\em 
node}]The node to add.  \end{description}
\end{Desc}
\begin{Desc}
\item[Returns: ]\par
Pointer to the old forward link. This can be used to test  whether this was the first item on the queue. \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 LLI\_\-\_\-jam routine, the list behaves as a LIFO. \hypertarget{LLI_8ih_a10}{
\index{LLI.ih@{LLI.ih}!LLI__lock@{LLI\_\-\_\-lock}}
\index{LLI__lock@{LLI\_\-\_\-lock}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-lock]{\setlength{\rightskip}{0pt plus 5cm}LLI\_\-key LLI\_\-\_\-lock (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list})}}
\label{LLI_8ih_a10}


This routine blocks until a node becomes available.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]The list head of the list to block \end{description}
\end{Desc}
\begin{Desc}
\item[Return values: ]\par
\begin{description}
\item[{\em 
key}]The key used to unblock the list \end{description}
\end{Desc}


{\bf WARNING} \par
 This is not meant to be a user callable routine. It is included here only because INLINING demands it. \hypertarget{LLI_8ih_a13}{
\index{LLI.ih@{LLI.ih}!LLI__lock_destroy@{LLI\_\-\_\-lock\_\-destroy}}
\index{LLI__lock_destroy@{LLI\_\-\_\-lock\_\-destroy}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-lock\_\-destroy]{\setlength{\rightskip}{0pt plus 5cm}int LLI\_\-\_\-lock\_\-destroy (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list})}}
\label{LLI_8ih_a13}


Frees any resources associated with the blocking mechanism.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
The}]list head  \end{description}
\end{Desc}
\begin{Desc}
\item[Return values: ]\par
\begin{description}
\item[{\em 
Status}]of the teardown procedure \end{description}
\end{Desc}


 {\bf WARNING} \par
 This is not meant to be a user callable routine. It is included here only because INLINING demands it. \hypertarget{LLI_8ih_a9}{
\index{LLI.ih@{LLI.ih}!LLI__lock_init@{LLI\_\-\_\-lock\_\-init}}
\index{LLI__lock_init@{LLI\_\-\_\-lock\_\-init}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-lock\_\-init]{\setlength{\rightskip}{0pt plus 5cm}LLI\_\-key LLI\_\-\_\-lock\_\-init (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list}, enum \hyperlink{LLI__type_8h_a4}{\_\-LLI\_\-type} {\em type})}}
\label{LLI_8ih_a9}


This initializes the blocking control structures.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]The list head \item[{\em 
type}]The type of blocking mechanism  \end{description}
\end{Desc}
\begin{Desc}
\item[Return values: ]\par
\begin{description}
\item[{\em 
The}]key used to lock and unlock the blocking mechanism \end{description}
\end{Desc}


 Returns the key used to block and unblock the blocking mechanisms. This is used when the list is to block when a removal is performed on an empty list.

{\bf WARNING} \par
 This is not meant to be a user callable routine. It is included here only because INLINING demands it. \hypertarget{LLI_8ih_a8}{
\index{LLI.ih@{LLI.ih}!LLI__remove@{LLI\_\-\_\-remove}}
\index{LLI__remove@{LLI\_\-\_\-remove}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-remove]{\setlength{\rightskip}{0pt plus 5cm}LLI\_\-\_\-EXT\_\-FNC struct \_\-LLI\_\-node $\ast$ LLI\_\-\_\-remove (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list})}}
\label{LLI_8ih_a8}


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

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]A previously initialized linked list head. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns: ]\par
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{LLI_8ih_a14}{
\index{LLI.ih@{LLI.ih}!LLI__removeW@{LLI\_\-\_\-removeW}}
\index{LLI__removeW@{LLI\_\-\_\-removeW}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-removeW]{\setlength{\rightskip}{0pt plus 5cm}struct \_\-LLI\_\-node $\ast$ LLI\_\-\_\-remove\-W (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list}, int {\em timeout})}}
\label{LLI_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.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]A previously initialized linked list head. \item[{\em 
timeout}]A timeout parameter. Currently the only timeout parameter is WAIT\_\-FOREVER (-1). \end{description}
\end{Desc}
\begin{Desc}
\item[Returns: ]\par
A pointer to the removed node. of NULL if the list is empty. \end{Desc}
\hypertarget{LLI_8ih_a11}{
\index{LLI.ih@{LLI.ih}!LLI__unlock@{LLI\_\-\_\-unlock}}
\index{LLI__unlock@{LLI\_\-\_\-unlock}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-unlock]{\setlength{\rightskip}{0pt plus 5cm}LLI\_\-\_\-unlock (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list}, LLI\_\-key {\em key})}}
\label{LLI_8ih_a11}


This routine unblocks the previously block list.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]The list head of the list to unblock \item[{\em 
key}]The key used to unblock the list \end{description}
\end{Desc}


{\bf WARNING} \par
 This is not meant to be a user callable routine. It is included here only because INLINING demands it. \hypertarget{LLI_8ih_a12}{
\index{LLI.ih@{LLI.ih}!LLI__wake@{LLI\_\-\_\-wake}}
\index{LLI__wake@{LLI\_\-\_\-wake}!LLI.ih@{LLI.ih}}
\subsubsection[LLI\_\-\_\-wake]{\setlength{\rightskip}{0pt plus 5cm}int LLI\_\-\_\-wake (struct \hyperlink{struct__LLI__list}{\_\-LLI\_\-list} $\ast$ {\em list})}}
\label{LLI_8ih_a12}


This provides the signaling mechanism to wake up a thread of code which was previously blocked.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
list}]The list head \end{description}
\end{Desc}
\begin{Desc}
\item[Return values: ]\par
\begin{description}
\item[{\em 
Status}]of the blocking mechanism \end{description}
\end{Desc}


{\bf WARNING} \par
 This is not meant to be a user callable routine. It is included here only because INLINING demands it.