\hypertarget{PL_8ih}{
\section{PL.ih File Reference}
\label{PL_8ih}\index{PL.ih@{PL.ih}}
}
Priority Lists, inline versions. 

{\tt \#include \char`\"{}IPBS/FFS.ih\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/L.ih\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/RW.ih\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/PL.h\char`\"{}}\par
{\tt \#include \char`\"{}PBI/Inline.h\char`\"{}}\par
{\tt \#include \char`\"{}PBI/Attribute.h\char`\"{}}\par


Include dependency graph for PL.ih:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=345pt]{PL_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=87pt]{PL_8ih__dep__incl}
\end{center}
\end{figure}
\subsection*{Defines}
\begin{CompactItemize}
\item 
\hypertarget{PL_8ih_a0}{
\#define \hyperlink{PL_8ih_a0}{PL\_\-\_\-EXP\_\-PROTO}~INLINE\_\-USR\_\-EXP\_\-PROTO}
\label{PL_8ih_a0}

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

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

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

\begin{CompactList}\small\item\em Internal Function declaration. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
PL\_\-\_\-EXP\_\-PROTO \hyperlink{struct__PL__que}{PL\_\-que} $\ast$ \hyperlink{PL_8ih_a4}{PL\_\-\_\-que\_\-get} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl, int que\_\-id) ATTR\_\-UNUSED\_\-OK
\begin{CompactList}\small\item\em Locates a pointer to the que specified by {\em que\_\-id\/}. \item\end{CompactList}\item 
PL\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{PL\_\-node} $\ast$ \hyperlink{PL_8ih_a5}{PL\_\-\_\-insert} (\hyperlink{struct__PL__que}{PL\_\-que} $\ast$que, \hyperlink{struct__L__node}{PL\_\-node} $\ast$node) ATTR\_\-UNUSED\_\-OK
\begin{CompactList}\small\item\em Adds a node to the tail of a PL managed que. \item\end{CompactList}\item 
PL\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{PL\_\-node} $\ast$ \hyperlink{PL_8ih_a6}{PL\_\-\_\-jam} (\hyperlink{struct__PL__que}{PL\_\-que} $\ast$que, \hyperlink{struct__L__node}{PL\_\-node} $\ast$node) ATTR\_\-UNUSED\_\-OK
\begin{CompactList}\small\item\em Adds a node to the head of a PL managed que. \item\end{CompactList}\item 
PL\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{PL\_\-node} $\ast$ \hyperlink{PL_8ih_a7}{PL\_\-\_\-remove} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$wait\_\-list, int $\ast$que\_\-id) ATTR\_\-UNUSED\_\-OK
\begin{CompactList}\small\item\em Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then {\em PL\_\-\_\-remove\/} returns NULL immediately without blocking. \item\end{CompactList}\item 
PL\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{PL\_\-node} $\ast$ \hyperlink{PL_8ih_a8}{PL\_\-\_\-remove\-W} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$wait\_\-list, int $\ast$que\_\-id) ATTR\_\-UNUSED\_\-OK
\begin{CompactList}\small\item\em Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then {\em PL\_\-\_\-remove\-W\/} waits indefinitely. \item\end{CompactList}\item 
PL\_\-\_\-EXP\_\-PROTO \hyperlink{struct__L__node}{PL\_\-node} $\ast$ \hyperlink{PL_8ih_a9}{PL\_\-\_\-remove\-W\_\-toc} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$wait\_\-list, int $\ast$que\_\-id, const \hyperlink{struct__TOC}{TOC} $\ast$toc) ATTR\_\-UNUSED\_\-OK
\begin{CompactList}\small\item\em Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then {\em PL\_\-\_\-remove\-W\_\-toc\/} waits the specified until the timeout expires. \item\end{CompactList}\item 
PL\_\-\_\-EXP\_\-PROTO \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} \hyperlink{PL_8ih_a10}{PL\_\-\_\-get} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl) ATTR\_\-UNUSED\_\-OK
\begin{CompactList}\small\item\em Returns a list of the currently active ques. \item\end{CompactList}\item 
PL\_\-\_\-EXP\_\-PROTO \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} \hyperlink{PL_8ih_a11}{PL\_\-\_\-get\-W} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$list) ATTR\_\-UNUSED\_\-OK
\begin{CompactList}\small\item\em Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks indefinitely until this condition is met. \item\end{CompactList}\item 
PL\_\-\_\-EXP\_\-PROTO \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} \hyperlink{PL_8ih_a12}{PL\_\-\_\-get\-W\_\-toc} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$list, const \hyperlink{struct__TOC}{TOC} $\ast$toc) ATTR\_\-UNUSED\_\-OK
\begin{CompactList}\small\item\em Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks until this condition is met or the timeout expires. \item\end{CompactList}\item 
PL\_\-\_\-LCL\_\-FNC \hyperlink{struct__L__node}{PL\_\-node} $\ast$ \hyperlink{PL_8ih_a13}{pl\_\-\_\-remove} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$wait\_\-list, int $\ast$que\_\-id)
\begin{CompactList}\small\item\em Bare bones, non-interlocked removal routine. This is for internal use only. \item\end{CompactList}\item 
PL\_\-\_\-EXP\_\-FNC \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} \hyperlink{PL_8ih_a14}{PL\_\-\_\-wake} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl, \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} wait\_\-list)
\begin{CompactList}\small\item\em Issues a wake up call to the PL ques if any of ques in the wait list is currently active. \item\end{CompactList}\item 
PL\_\-\_\-LCL\_\-FNC \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} \hyperlink{PL_8ih_a15}{pl\_\-\_\-test\_\-or} (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$pl, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$list)
\begin{CompactList}\small\item\em Tests whether the current active list of ques contains any member of the specified list. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Priority Lists, 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: PL.ih,v 1.1.1.1 2006/02/10 21:45:35 saxton Exp $
\end{verbatim}
\normalsize


\begin{Desc}
\item[SYNOPSIS]This defines the Priority List routines. A Priority List is a an array of interlocked singly linked lists. A producer places items on one queues managed by the PL facility using one of the insertion routines, {\em PL\_\-insert\/} or {\em PL\_\-jam\/}. The consumer then removes the highest priority non-empty queue using one of the {\em PL\_\-\_\-remove\/} routines.\end{Desc}
This facility allows multiple producers to insert on any or all of the managed queues. While nothing prohibits multiply consumers to pend on the PL set of managed queues, this would be fairly unusual.

Internally, the interlocking of the queues may or may not be private to each queue. This is a platform implementation decision depending on the cost of interlock mechanism. However, the blocking mechanism is always shared among all the queues. This, in fact, is the distinguishing feature.

\subsection{Function Documentation}
\hypertarget{PL_8ih_a10}{
\index{PL.ih@{PL.ih}!PL__get@{PL\_\-\_\-get}}
\index{PL__get@{PL\_\-\_\-get}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-get]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} PL\_\-\_\-get (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl})}}
\label{PL_8ih_a10}


Returns a list of the currently active ques. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]A previously initialized PL control structure. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A list of the currently active ques.\end{Desc}
\begin{Desc}
\item[Warning:]The caller is cautioned that the list returned only reflects the state of the active ques at the time of the call. Writers to the que may add active nodes to previously inactive ques or, in the case of multiple readers, other readers may remove nodes causing previously active ques to become inactive.\end{Desc}
Note that in single reader usage, the returned list will always be at least a subset of the active ques. Since no other reader is removing nodes, the active list can only stay the same or get larger.\hypertarget{PL_8ih_a11}{
\index{PL.ih@{PL.ih}!PL__getW@{PL\_\-\_\-getW}}
\index{PL__getW@{PL\_\-\_\-getW}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-getW]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} PL\_\-\_\-get\-W (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl}, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$ {\em wait\_\-list})}}
\label{PL_8ih_a11}


Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks indefinitely until this condition is met. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]A previously initialized PL control structure. \item[{\em wait\_\-list}]A pointer to the list of the ques to wait on. The wait is treated as an OR. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The list of active ques. It is guaranteed to include at least one member in the wait list. Note that the list is not trimmed to the wait list. This would destroy information and the trimming is easily done by user\end{Desc}
\begin{Desc}
\item[Warning:]The caller is cautioned that the list returned only reflects the state of the active ques at the time of the call. Writers to the que may add active nodes to previously inactive ques or, in the case of multiple readers, other readers may remove nodes causing previously active ques to become inactive.\end{Desc}
Note that in single reader usage, the returned list will always be at least a subset of the active ques. Since no other reader is removing nodes, the active list can only stay the same or get larger.\hypertarget{PL_8ih_a12}{
\index{PL.ih@{PL.ih}!PL__getW_toc@{PL\_\-\_\-getW\_\-toc}}
\index{PL__getW_toc@{PL\_\-\_\-getW\_\-toc}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-getW\_\-toc]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} PL\_\-\_\-get\-W\_\-toc (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl}, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$ {\em wait\_\-list}, const \hyperlink{struct__TOC}{TOC} $\ast$ {\em toc})}}
\label{PL_8ih_a12}


Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks until this condition is met or the timeout expires. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]A previously initialized PL control structure. \item[{\em wait\_\-list}]A pointer to the list of the ques to wait on. The wait is treated as an OR. \item[{\em toc}]The timeout control structure.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The list of active ques. It is guaranteed to include at least one member in the wait list. Note that the list is not trimmed to the wait list. This would destroy information and the trimming is easily done by user\end{Desc}
\begin{Desc}
\item[Warning:]The caller is cautioned that the list returned only reflects the state of the active ques at the time of the call. Writers to the que may add active nodes to previously inactive ques or, in the case of multiple readers, other readers may remove nodes causing previously active ques to become inactive.\end{Desc}
Note that in single reader usage, the returned list will always be at least a subset of the active ques. Since no other reader is removing nodes, the active list can only stay the same or get larger.\hypertarget{PL_8ih_a5}{
\index{PL.ih@{PL.ih}!PL__insert@{PL\_\-\_\-insert}}
\index{PL__insert@{PL\_\-\_\-insert}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-insert]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{PL\_\-node} $\ast$ PL\_\-\_\-insert (\hyperlink{struct__PL__que}{PL\_\-que} $\ast$ {\em que}, \hyperlink{struct__L__node}{PL\_\-node} $\ast$ {\em node})}}
\label{PL_8ih_a5}


Adds a node to the tail of a PL managed que. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em que}]A PL managed que. \item[{\em node}]The node to add to {\em que\/} \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 queue. \par
 If return\_\-value == que, then the que was initially empty.\end{Desc}
Adds the specified node to the tail of the que. If all nodes are added with the PL\_\-\_\-insert routine, the que behaves as a FIFO.\hypertarget{PL_8ih_a6}{
\index{PL.ih@{PL.ih}!PL__jam@{PL\_\-\_\-jam}}
\index{PL__jam@{PL\_\-\_\-jam}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-jam]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{PL\_\-node} $\ast$ PL\_\-\_\-jam (\hyperlink{struct__PL__que}{PL\_\-que} $\ast$ {\em que}, \hyperlink{struct__L__node}{PL\_\-node} $\ast$ {\em node})}}
\label{PL_8ih_a6}


Adds a node to the head of a PL managed que. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em que}]A PL managed que. \item[{\em node}]The node to add to {\em que\/} \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 == list, then the que was initially empty\end{Desc}
Adds the specified node to the head of the list. If all nodes are added with the PL\_\-\_\-jam routine, the que behaves as a LIFO.\hypertarget{PL_8ih_a4}{
\index{PL.ih@{PL.ih}!PL__que_get@{PL\_\-\_\-que\_\-get}}
\index{PL__que_get@{PL\_\-\_\-que\_\-get}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-que\_\-get]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{struct__PL__que}{PL\_\-que} $\ast$ PL\_\-\_\-que\_\-get (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl}, int {\em que\_\-id})}}
\label{PL_8ih_a4}


Locates a pointer to the que specified by {\em que\_\-id\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]The priority list \item[{\em que\_\-id}]The id of the que to locate\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the que specified by {\em que\_\-id\/} or NULL if {\em que\_\-id\/} specifies an invalid or non-configured que.\end{Desc}
\hypertarget{PL_8ih_a13}{
\index{PL.ih@{PL.ih}!pl__remove@{pl\_\-\_\-remove}}
\index{pl__remove@{pl\_\-\_\-remove}!PL.ih@{PL.ih}}
\subsubsection[pl\_\-\_\-remove]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__L__node}{PL\_\-node} $\ast$ pl\_\-\_\-remove (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl}, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$ {\em wait\_\-list}, int $\ast$ {\em que\_\-id})}}
\label{PL_8ih_a13}


Bare bones, non-interlocked removal routine. This is for internal use only. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]The priority list \item[{\em wait\_\-list}]Pointer to The list of ques to wait on. \item[{\em que\_\-id}]Returned with the id of the que the node was removed from\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the deque'd node of the highest priority active que in the {\em wait\_\-list\/}. If the {\em wait\_\-list\/} does not specify any configured ques, NULL is returned.\end{Desc}
\hypertarget{PL_8ih_a7}{
\index{PL.ih@{PL.ih}!PL__remove@{PL\_\-\_\-remove}}
\index{PL__remove@{PL\_\-\_\-remove}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-remove]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{PL\_\-node} $\ast$ PL\_\-\_\-remove (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl}, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$ {\em wait\_\-list}, int $\ast$ {\em que\_\-id})}}
\label{PL_8ih_a7}


Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then {\em PL\_\-\_\-remove\/} returns NULL immediately without blocking. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]A previously initialized PL control structure. \item[{\em wait\_\-list}]A pointer to the list of the ques to wait on. The wait is treated as an OR. \item[{\em que\_\-id}]Returned with the id of the que the node was removed from.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the removed node, or NULL if all the queues are empty.\end{Desc}
Removes the node at the head of the highest priority non-empty que. If the all eligible queues are empty, NULL is immediately returned. This routine does not block.\hypertarget{PL_8ih_a8}{
\index{PL.ih@{PL.ih}!PL__removeW@{PL\_\-\_\-removeW}}
\index{PL__removeW@{PL\_\-\_\-removeW}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-removeW]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{PL\_\-node} $\ast$ PL\_\-\_\-remove\-W (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl}, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$ {\em wait\_\-list}, int $\ast$ {\em que\_\-id})}}
\label{PL_8ih_a8}


Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then {\em PL\_\-\_\-remove\-W\/} waits indefinitely. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]A previously initialized PL control structure. \item[{\em wait\_\-list}]A pointer to the list of the ques to wait on. The wait is treated as an OR. as an OR. \item[{\em que\_\-id}]Returned with the id of the que the node was removed from.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the removed node, or NULL if on error\end{Desc}
Removes the highest priority available and eligible node from a PL. If all ques are empty, the routine blocks indefinitely or until something shows up or there is an error.

If there is an error, the routine returns NULL as its node. There are only two reasons NULL will be returned: 

\footnotesize\begin{verbatim}     1. Internal error
     2. The list of eligible ques does not include any configured ques.
  \end{verbatim}
\normalsize
\hypertarget{PL_8ih_a9}{
\index{PL.ih@{PL.ih}!PL__removeW_toc@{PL\_\-\_\-removeW\_\-toc}}
\index{PL__removeW_toc@{PL\_\-\_\-removeW\_\-toc}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-removeW\_\-toc]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{struct__L__node}{PL\_\-node} $\ast$ PL\_\-\_\-remove\-W\_\-toc (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl}, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$ {\em wait\_\-list}, int $\ast$ {\em que\_\-id}, const \hyperlink{struct__TOC}{TOC} $\ast$ {\em toc})}}
\label{PL_8ih_a9}


Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then {\em PL\_\-\_\-remove\-W\_\-toc\/} waits the specified until the timeout expires. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]A previously initialized PL control structure. \item[{\em wait\_\-list}]A pointer to the list of the ques to wait on. The wait is treated as an OR. \item[{\em toc}]The Time\-Out control structure. This may be specified as TOC\_\-NOWAIT or TOC\_\-FOREVER. \item[{\em que\_\-id}]Returned with the id of the que the node was removed from \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the removed node, or NULL on error\end{Desc}
Removes the nodve at the head of the highest priority non-empty que. If the all eligible queues are empty, then {\em PL\_\-\_\-remove\-W\_\-toc\/} waits until something shows up or the timeout period, specified by {\em toc\/} expires.

If there is an error, the routine returns NULL as its node. There are only three reasons NULL will be returned:

\begin{itemize}
\item \# Internal error\item \# The list of eligible ques does not include any configured ques.\item \# Timeout expired.\end{itemize}
\hypertarget{PL_8ih_a15}{
\index{PL.ih@{PL.ih}!pl__test_or@{pl\_\-\_\-test\_\-or}}
\index{pl__test_or@{pl\_\-\_\-test\_\-or}!PL.ih@{PL.ih}}
\subsubsection[pl\_\-\_\-test\_\-or]{\setlength{\rightskip}{0pt plus 5cm}pl\_\-\_\-test\_\-or (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl}, volatile const \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} $\ast$ {\em list})}}
\label{PL_8ih_a15}


Tests whether the current active list of ques contains any member of the specified list. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]The PL control structure \item[{\em list}]A pointer to the list of the ques to test.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The list of active queues. Note that this list is not trimmed by the {\em list\/}. The caller is free to do this if he wishes. If the list does not contain any members of {\em list\/}, 0 is returned.\end{Desc}
\begin{Desc}
\item[Warning:]This is an internal routine primarily used as a RW\_\-get callback.\end{Desc}
\hypertarget{PL_8ih_a14}{
\index{PL.ih@{PL.ih}!PL__wake@{PL\_\-\_\-wake}}
\index{PL__wake@{PL\_\-\_\-wake}!PL.ih@{PL.ih}}
\subsubsection[PL\_\-\_\-wake]{\setlength{\rightskip}{0pt plus 5cm}PL\_\-\_\-EXP\_\-FNC \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} PL\_\-\_\-wake (\hyperlink{struct__PL__ctl}{PL\_\-ctl} $\ast$ {\em pl}, \hyperlink{PL__comdefs_8h_a0}{PL\_\-list} {\em wakeup\_\-list})}}
\label{PL_8ih_a14}


Issues a wake up call to the PL ques if any of ques in the wait list is currently active. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em pl}]A previously initialized PL control structure. \item[{\em wakeup\_\-list}]The list of ques to issue the wakeup call on \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The list of active ques at the time the wake up call was issued.\end{Desc}
This routine allows the user to effectively enable and disable the servicing of lists of ques. Remember that the wait list parameter passed to {\em \hyperlink{PL_8ih_a7}{PL\_\-\_\-remove()}\/}, {\em \hyperlink{PL_8ih_a8}{PL\_\-\_\-remove\-W()}\/} and {\em PL\_\-\_\-remove\-W\_\-toc\/} is passed as a volatile pointer. This means that some other piece of code is allowed to dynamically alter the contents of the wait list. However, if the remove routines are already pending on a list, the remove routines will never notice the change. Hence the reason for this routine.