\hypertarget{QI_8ih}{
\section{QI.ih File Reference}
\label{QI_8ih}\index{QI.ih@{QI.ih}}
}
Interlocked doubly linked list, inline versions.  


{\tt \#include $<$PBI/Inline.h$>$}\par
{\tt \#include $<$PBI/Attribute.h$>$}\par
{\tt \#include $<$PBS/Q.h$>$}\par
{\tt \#include $<$PBS/Q.ih$>$}\par
{\tt \#include $<$PBS/RW.h$>$}\par
{\tt \#include $<$PBS/RW.ih$>$}\par
{\tt \#include $<$PBS/QI.h$>$}\par
{\tt \#include $<$PBS/TOC\_\-comdefs.h$>$}\par
\subsection*{Functions}
\begin{CompactItemize}
\item 
QI\_\-\_\-EXP\_\-PROTO int \hyperlink{QI_8ih_1b4f1bb90b8b1124a8116e72e61fb637}{QI\_\-\_\-disable} (\hyperlink{struct__QI__head}{QI\_\-head} $\ast$e) \_\-OK
\begin{CompactList}\small\item\em Disables the dequeing of nodes from this que. \item\end{CompactList}\item 
QI\_\-\_\-EXP\_\-PROTO int \hyperlink{QI_8ih_382584a4388e291f060fe70f3e8f53d8}{QI\_\-\_\-enable} (\hyperlink{struct__QI__head}{QI\_\-head} $\ast$que) \_\-OK
\begin{CompactList}\small\item\em Enable the dequeing of nodes from this que. \item\end{CompactList}\item 
QI\_\-\_\-EXP\_\-PROTO int \hyperlink{QI_8ih_2b4e630cd4cfece5c9ea845dc1b74640}{QI\_\-\_\-enabled} (const \hyperlink{struct__QI__head}{QI\_\-head} $\ast$que) \_\-OK
\begin{CompactList}\small\item\em Returns the state of the disabled flag for this que. \item\end{CompactList}\item 
QI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__Q__node}{QI\_\-node} $\ast$ \hyperlink{QI_8ih_e1e8ed1aa9e4875c0c56d5ff23a30218}{QI\_\-\_\-insert} (\hyperlink{struct__QI__head}{QI\_\-head} $\ast$que, \hyperlink{struct__Q__node}{QI\_\-node} $\ast$node) \_\-OK
\begin{CompactList}\small\item\em Adds a node to the tail of a previously initialized que. \item\end{CompactList}\item 
QI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__Q__node}{QI\_\-node} $\ast$ \hyperlink{QI_8ih_8885964809c0c794c18a1af9097953ab}{QI\_\-\_\-jam} (\hyperlink{struct__QI__head}{QI\_\-head} $\ast$que, \hyperlink{struct__Q__node}{QI\_\-node} $\ast$node) \_\-OK
\begin{CompactList}\small\item\em Adds a node to the head of a previously initialized que. \item\end{CompactList}\item 
QI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__Q__node}{QI\_\-node} $\ast$ \hyperlink{QI_8ih_6873cd45990e39b6d816ea91fc7cefa6}{QI\_\-\_\-remove} (\hyperlink{struct__QI__head}{QI\_\-head} $\ast$que) \_\-OK
\begin{CompactList}\small\item\em Removes the node from the tail of a previously initialized que. An empty que returns NULL as its node. \item\end{CompactList}\item 
QI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__Q__node}{QI\_\-node} $\ast$ \hyperlink{QI_8ih_2ebd4a02e9a7ee207801c6f881b2928c}{QI\_\-\_\-removeW} (\hyperlink{struct__QI__head}{QI\_\-head} $\ast$que) \_\-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}\item 
QI\_\-\_\-EXP\_\-PROTO \hyperlink{struct__Q__node}{QI\_\-node} $\ast$ \hyperlink{QI_8ih_1b974721ece73e7050325a265cd9a520}{QI\_\-\_\-removeW\_\-toc} (\hyperlink{struct__QI__head}{QI\_\-head} $\ast$que, const \hyperlink{struct__TOC}{TOC} $\ast$toc) \_\-OK
\begin{CompactList}\small\item\em Removes the node from the head of a previously initialized que. If the que is empty, the thread of code is blocked until a node becomes available or the timeout condition is satisfied. \item\end{CompactList}\item 
QI\_\-\_\-EXP\_\-FNC void \hyperlink{QI_8ih_b8070ed0759d2015a738a6f42dfd5f80}{QI\_\-\_\-append} (\hyperlink{struct__QI__head}{QI\_\-head} $\ast$dst, \hyperlink{struct__QI__head}{QI\_\-head} $\ast$src)
\begin{CompactList}\small\item\em Appends the {\em src\/} que members to the {\em dst\/} que. \item\end{CompactList}\item 
QI\_\-\_\-EXP\_\-FNC void \hyperlink{QI_8ih_d602826d5f166d035eebd1801a8c2d01}{QI\_\-\_\-prepend} (\hyperlink{struct__QI__head}{QI\_\-head} $\ast$dst, \hyperlink{struct__QI__head}{QI\_\-head} $\ast$src)
\begin{CompactList}\small\item\em Prepends the {\em src\/} que members to the {\em que\/} list. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Interlocked doubly 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: QI.ih,v 1.4 2011/03/24 23:05:43 apw Exp $
\end{verbatim}
\normalsize


\begin{Desc}
\item[SYNOPSIS]This defines the inline interlocked versions of the Que routines. These allow the user to build interlocked doubly linked lists. These routines parallel some of the functionality of the VxWorks {\em llxxxx\/} routines, but are portable to both VxWorks and host platforms, in addition to being 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 Q routines provide the same functionality without the overhead of being interlocked.

\begin{Desc}
\item[Note:]Conspicious by its absence is an interlocked unlink. This is deliberate. There is no safe way to provide a routine to unlink a node in an interlocked fashion. If the node was located without any interlocks on the que, there is no guarantee that by the time the mythical QI\_\-\_\-unlink routine gets called and interlocks the que, that the node is still on the que. \end{Desc}


\subsection{Function Documentation}
\hypertarget{QI_8ih_b8070ed0759d2015a738a6f42dfd5f80}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-append@{QI\_\-\_\-append}}
\index{QI\_\-\_\-append@{QI\_\-\_\-append}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-append}]{\setlength{\rightskip}{0pt plus 5cm}void QI\_\-\_\-append ({\bf QI\_\-head} $\ast$ {\em dst}, \/  {\bf QI\_\-head} $\ast$ {\em src})}}
\label{QI_8ih_b8070ed0759d2015a738a6f42dfd5f80}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dst}]A previously initialized que acting as the destination \item[{\em src}]A previously initialized que acting as the source\end{description}
\end{Desc}
Appends the source que to the destination que. After this operation the destination que will have consist of its original members followed by the members on the source que. The source que will be empty. 

References \_\-QI\_\-head::head, Q\_\-\_\-append(), \_\-QI\_\-head::rw, RW\_\-\_\-lock2(), and RW\_\-\_\-unlock2().\hypertarget{QI_8ih_1b4f1bb90b8b1124a8116e72e61fb637}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-disable@{QI\_\-\_\-disable}}
\index{QI\_\-\_\-disable@{QI\_\-\_\-disable}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-disable}]{\setlength{\rightskip}{0pt plus 5cm}QI\_\-\_\-EXP\_\-FNC int QI\_\-\_\-disable ({\bf QI\_\-head} $\ast$ {\em que})}}
\label{QI_8ih_1b4f1bb90b8b1124a8116e72e61fb637}


Disables the dequeing of nodes from this que. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em que}]A previously initialized que \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Que was previously disabled \item[{\em !=0}]Que 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 QI\_\-\_\-removeXXX routines. Delivery of these items may resume after a call to {\em \hyperlink{QI_8ih_382584a4388e291f060fe70f3e8f53d8}{QI\_\-\_\-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 QI\_\-\_\-enable can be made, {\em i.e\/}. deadlock.\end{Desc}
To avoid this situation, either separate the task controlling the queue via QI\_\-\_\-disable's and QI\_\-\_\-enables' from the task allocating new items for the que or, if in the same task, cease to allocate new items when the QI que has been disabled. 

References \_\-QI\_\-head::rw, and RW\_\-\_\-disable().\hypertarget{QI_8ih_382584a4388e291f060fe70f3e8f53d8}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-enable@{QI\_\-\_\-enable}}
\index{QI\_\-\_\-enable@{QI\_\-\_\-enable}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-enable}]{\setlength{\rightskip}{0pt plus 5cm}QI\_\-\_\-EXP\_\-FNC int QI\_\-\_\-enable ({\bf QI\_\-head} $\ast$ {\em que})}}
\label{QI_8ih_382584a4388e291f060fe70f3e8f53d8}


Enable the dequeing of nodes from this que. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em que}]A previously initialized que \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Que was previously disabled \item[{\em !=0}]Que was previously enabled\end{description}
\end{Desc}
After issuing this call the QI\_\-\_\-remove routines will deliver items once again. If any QI\_\-\_\-remove call is currently waiting on a non-empty que, a wakeup call is issued, permitting nodes to be dequed. 

References \_\-QI\_\-head::rw, and RW\_\-\_\-enable().\hypertarget{QI_8ih_2b4e630cd4cfece5c9ea845dc1b74640}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-enabled@{QI\_\-\_\-enabled}}
\index{QI\_\-\_\-enabled@{QI\_\-\_\-enabled}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-enabled}]{\setlength{\rightskip}{0pt plus 5cm}QI\_\-\_\-EXP\_\-FNC int QI\_\-\_\-enabled (const {\bf QI\_\-head} $\ast$ {\em que})}}
\label{QI_8ih_2b4e630cd4cfece5c9ea845dc1b74640}


Returns the state of the disabled flag for this que. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em que}]A previously initialized que \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Que is currently disabled \item[{\em !=0}]Que is currently enabled \end{description}
\end{Desc}


References \_\-QI\_\-head::rw, and RW\_\-\_\-enabled().\hypertarget{QI_8ih_e1e8ed1aa9e4875c0c56d5ff23a30218}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-insert@{QI\_\-\_\-insert}}
\index{QI\_\-\_\-insert@{QI\_\-\_\-insert}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-insert}]{\setlength{\rightskip}{0pt plus 5cm}QI\_\-\_\-EXP\_\-FNC {\bf QI\_\-node} $\ast$ QI\_\-\_\-insert ({\bf QI\_\-head} $\ast$ {\em que}, \/  {\bf QI\_\-node} $\ast$ {\em node})}}
\label{QI_8ih_e1e8ed1aa9e4875c0c56d5ff23a30218}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em que}]A previously initialized que. \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 que. \par
 If return\_\-value == que, the empty)\end{Desc}
Adds the specified node to the tail of the que. If all nodes are added with the QI\_\-\_\-insert routine, the que behaves as a FIFO. 

References \_\-QI\_\-head::head, Q\_\-\_\-insert(), \_\-QI\_\-head::rw, RW\_\-\_\-lock(), RW\_\-\_\-unlock(), and RW\_\-\_\-wake().\hypertarget{QI_8ih_8885964809c0c794c18a1af9097953ab}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-jam@{QI\_\-\_\-jam}}
\index{QI\_\-\_\-jam@{QI\_\-\_\-jam}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-jam}]{\setlength{\rightskip}{0pt plus 5cm}QI\_\-\_\-EXP\_\-FNC {\bf QI\_\-node} $\ast$ QI\_\-\_\-jam ({\bf QI\_\-head} $\ast$ {\em que}, \/  {\bf QI\_\-node} $\ast$ {\em node})}}
\label{QI_8ih_8885964809c0c794c18a1af9097953ab}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em que}]A previously initialized que. \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 queue. \par
 If return\_\-value == que, the empty)\end{Desc}
Adds the specified node to the head of the que. If all nodes are added with the QI\_\-\_\-jam routine, the que behaves as a LIFO. 

References \_\-QI\_\-head::head, Q\_\-\_\-jam(), \_\-QI\_\-head::rw, RW\_\-\_\-lock(), RW\_\-\_\-unlock(), and RW\_\-\_\-wake().\hypertarget{QI_8ih_d602826d5f166d035eebd1801a8c2d01}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-prepend@{QI\_\-\_\-prepend}}
\index{QI\_\-\_\-prepend@{QI\_\-\_\-prepend}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-prepend}]{\setlength{\rightskip}{0pt plus 5cm}void QI\_\-\_\-prepend ({\bf QI\_\-head} $\ast$ {\em dst}, \/  {\bf QI\_\-head} $\ast$ {\em src})}}
\label{QI_8ih_d602826d5f166d035eebd1801a8c2d01}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dst}]A previously initialized que acting as the destination \item[{\em src}]A previously initialized que acting as the source\end{description}
\end{Desc}
Prepends the source que to the destination que. After this operation the destination que will have consist of its original members preceded by the members on the source que. The source que will be empty. 

References \_\-QI\_\-head::head, Q\_\-\_\-prepend(), \_\-QI\_\-head::rw, RW\_\-\_\-lock2(), and RW\_\-\_\-unlock2().\hypertarget{QI_8ih_6873cd45990e39b6d816ea91fc7cefa6}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-remove@{QI\_\-\_\-remove}}
\index{QI\_\-\_\-remove@{QI\_\-\_\-remove}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-remove}]{\setlength{\rightskip}{0pt plus 5cm}QI\_\-\_\-EXP\_\-FNC {\bf QI\_\-node} $\ast$ QI\_\-\_\-remove ({\bf QI\_\-head} $\ast$ {\em que})}}
\label{QI_8ih_6873cd45990e39b6d816ea91fc7cefa6}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em que}]A previously initialized que. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the removed node of NULL if the que is empty. Removes the node at the head of the que. If the que is empty, NULL is returned. \end{Desc}


References \_\-QI\_\-head::head, Q\_\-\_\-remove(), \_\-QI\_\-head::rw, RW\_\-\_\-enabled(), RW\_\-\_\-lock(), and RW\_\-\_\-unlock().

Referenced by QI\_\-\_\-removeW(), and QI\_\-\_\-removeW\_\-toc().\hypertarget{QI_8ih_2ebd4a02e9a7ee207801c6f881b2928c}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-removeW@{QI\_\-\_\-removeW}}
\index{QI\_\-\_\-removeW@{QI\_\-\_\-removeW}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-removeW}]{\setlength{\rightskip}{0pt plus 5cm}QI\_\-\_\-EXP\_\-FNC {\bf QI\_\-node} $\ast$ QI\_\-\_\-removeW ({\bf QI\_\-head} $\ast$ {\em que})}}
\label{QI_8ih_2ebd4a02e9a7ee207801c6f881b2928c}


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 que}]A previously initialized que \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the removed node or NULL on error. \end{Desc}


References Q\_\-\_\-remove(), QI\_\-\_\-remove(), \_\-QI\_\-head::rw, and RW\_\-getW().\hypertarget{QI_8ih_1b974721ece73e7050325a265cd9a520}{
\index{QI.ih@{QI.ih}!QI\_\-\_\-removeW\_\-toc@{QI\_\-\_\-removeW\_\-toc}}
\index{QI\_\-\_\-removeW\_\-toc@{QI\_\-\_\-removeW\_\-toc}!QI.ih@{QI.ih}}
\subsubsection[{QI\_\-\_\-removeW\_\-toc}]{\setlength{\rightskip}{0pt plus 5cm}QI\_\-\_\-EXP\_\-FNC {\bf QI\_\-node} $\ast$ QI\_\-\_\-removeW\_\-toc ({\bf QI\_\-head} $\ast$ {\em que}, \/  const {\bf TOC} $\ast$ {\em toc})}}
\label{QI_8ih_1b974721ece73e7050325a265cd9a520}


Removes the node from the head of a previously initialized que. If the que is empty, the thread of code is blocked until a node becomes available or the timeout condition is satisfied. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em que}]A previously initialized que. \item[{\em toc}]The timeout control structure. This may be one of the two special values {\em TOC\_\-NOWAIT\/} or {\em TOC\_\-FOREVER\/}. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the removed node. of NULL if the que is empty.\end{Desc}
Removes the node from the head of a previously initialized que. If the que is empty, the thread of code is blocked until a node becomes available or the timeout value is reached. See also {\em QI\_\-removeW\/} and QI\_\-remove. 

References Q\_\-remove(), QI\_\-\_\-remove(), \_\-QI\_\-head::rw, RW\_\-getW\_\-toc(), and TOC\_\-IS\_\-NOWAIT.