\section{cue.c File Reference}
\label{cue_8c}\index{cue.c@{cue.c}}


Routines that act upon the cue structure.  


{\ttfamily \#include $<$lci\_\-p.h$>$}\par
{\ttfamily \#include $<$LCI/LCI\_\-msgs.h$>$}\par
{\ttfamily \#include $<$MSG/MSG\_\-pubdefs.h$>$}\par
{\ttfamily \#include $<$PBS/MBA.h$>$}\par
{\ttfamily \#include $<$PBS/WUT.h$>$}\par
{\ttfamily \#include $<$PBS/SEM.h$>$}\par
{\ttfamily \#include $<$string.h$>$}\par
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
\hyperlink{lci__p_8h_ad9b0a7c12a10194bee64c74b1f8a12ec}{LCI\_\-cue} $\ast$ \hyperlink{cue_8c_a31b61a3f852fcd8c2cd9dd36c5e682a4}{LCI\_\-newCue} (void)
\begin{DoxyCompactList}\small\item\em Create a new cue. \end{DoxyCompactList}\item 
unsigned \hyperlink{cue_8c_a06983ef6516cc9e991d7baf115e9fffd}{LCI\_\-deleteCue} (\hyperlink{lci__p_8h_ad9b0a7c12a10194bee64c74b1f8a12ec}{LCI\_\-cue} $\ast$cue)
\begin{DoxyCompactList}\small\item\em Delete a cue. \end{DoxyCompactList}\item 
void \hyperlink{cue_8c_a68e03f7db1f5486592fd6a56c74704f3}{LCI\_\-clearCue} (\hyperlink{lci__p_8h_ad9b0a7c12a10194bee64c74b1f8a12ec}{LCI\_\-cue} $\ast$cue)
\begin{DoxyCompactList}\small\item\em Clear a cue. \end{DoxyCompactList}\item 
unsigned \hyperlink{cue_8c_a5542d4f986974bee670ebb3cf8adeeda}{LCI\_\-waitCue} (\hyperlink{lci__p_8h_ad9b0a7c12a10194bee64c74b1f8a12ec}{LCI\_\-cue} $\ast$cue, unsigned timeout)
\begin{DoxyCompactList}\small\item\em Wait for a cue to complete or time out. \end{DoxyCompactList}\item 
void \hyperlink{cue_8c_a9e35d61657eb30d22f26d68392f52e05}{LCI\_\-signalCue} (\hyperlink{lci__p_8h_ad9b0a7c12a10194bee64c74b1f8a12ec}{LCI\_\-cue} $\ast$cue)
\begin{DoxyCompactList}\small\item\em Signal cue completion. \end{DoxyCompactList}\item 
void \hyperlink{cue_8c_a21e53f5c9579985fb457442bee8c8c4e}{LCI\_\-clearCueCounts} (\hyperlink{lci__p_8h_ad9b0a7c12a10194bee64c74b1f8a12ec}{LCI\_\-cue} $\ast$cue)
\begin{DoxyCompactList}\small\item\em Clear cue counters. \end{DoxyCompactList}\item 
void \hyperlink{cue_8c_ad425faf1408ffb559d469279fe44722e}{LCI\_\-getCueCounts} (\hyperlink{lci__p_8h_ad9b0a7c12a10194bee64c74b1f8a12ec}{LCI\_\-cue} $\ast$cue, unsigned int $\ast$nWait, unsigned int $\ast$nSignal, unsigned int $\ast$nTimeout)
\begin{DoxyCompactList}\small\item\em Get cue counters. \end{DoxyCompactList}\item 
WUT\_\-cb\_\-status \hyperlink{cue_8c_aaba4b9aa5e0b5190c6405dd80b750066}{cue\_\-wut\_\-cb} (void $\ast$prm, WUT\_\-tmr $\ast$wut)
\begin{DoxyCompactList}\small\item\em Timer callback. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
Routines that act upon the cue structure. \begin{DoxyAuthor}{Author}
James Swain \& Owen Saxton
\end{DoxyAuthor}
The order of calling the functions presented here should be LCI\_\-newCue LCI\_\-clearCue -\/-\/$>$ LCI\_\-waitCue -\/-\/$>$ In another task -\/-\/$>$ LCI\_\-signalCue : Repeat as necessary : LCI\_\-deleteCue

{\bfseries \$Id:} \hyperlink{cue_8c}{cue.c},v 1.5 2011/03/29 19:32:57 saxton Exp \$ 

\subsection{Function Documentation}
\index{cue.c@{cue.c}!cue\_\-wut\_\-cb@{cue\_\-wut\_\-cb}}
\index{cue\_\-wut\_\-cb@{cue\_\-wut\_\-cb}!cue.c@{cue.c}}
\subsubsection[{cue\_\-wut\_\-cb}]{\setlength{\rightskip}{0pt plus 5cm}WUT\_\-cb\_\-status cue\_\-wut\_\-cb (
\begin{DoxyParamCaption}
\item[{void $\ast$}]{prm, }
\item[{WUT\_\-tmr $\ast$}]{wut}
\end{DoxyParamCaption}
)}\label{cue_8c_aaba4b9aa5e0b5190c6405dd80b750066}


Timer callback. 

This routine is called back when the wake-\/up timer goes off. It sets the end state to LCI\_\-CUE\_\-TIMEDOUT and gives the semaphore


\begin{DoxyParams}{Parameters}
{\em prm} & Pointer to the LCI\_\-cue structure\\
\hline
{\em wut} & Pointer to the wake-\/up timer\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em WUT\_\-K\_\-STATE\_\-CHANGE\_\-YES} & \\
\hline
\end{DoxyRetVals}


References LCI\_\-CUE\_\-TIMEDOUT.



Referenced by LCI\_\-waitCue().

\index{cue.c@{cue.c}!LCI\_\-clearCue@{LCI\_\-clearCue}}
\index{LCI\_\-clearCue@{LCI\_\-clearCue}!cue.c@{cue.c}}
\subsubsection[{LCI\_\-clearCue}]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-clearCue (
\begin{DoxyParamCaption}
\item[{{\bf LCI\_\-cue} $\ast$}]{cue}
\end{DoxyParamCaption}
)}\label{cue_8c_a68e03f7db1f5486592fd6a56c74704f3}


Clear a cue. 

This routine puts the cue into a known cleared state, ready for the next wait.


\begin{DoxyParams}{Parameters}
{\em cue} & Pointer to an allocated, initialised cue structure (from LCI\_\-newCue) \\
\hline
\end{DoxyParams}


References LCI\_\-CUE\_\-UNSET.



Referenced by LCI\_\-collect().

\index{cue.c@{cue.c}!LCI\_\-clearCueCounts@{LCI\_\-clearCueCounts}}
\index{LCI\_\-clearCueCounts@{LCI\_\-clearCueCounts}!cue.c@{cue.c}}
\subsubsection[{LCI\_\-clearCueCounts}]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-clearCueCounts (
\begin{DoxyParamCaption}
\item[{{\bf LCI\_\-cue} $\ast$}]{cue}
\end{DoxyParamCaption}
)}\label{cue_8c_a21e53f5c9579985fb457442bee8c8c4e}


Clear cue counters. 

This routine zeroes the counts of waits, signals and timeouts.


\begin{DoxyParams}{Parameters}
{\em cue} & Pointer to a cue being used. \\
\hline
\end{DoxyParams}


Referenced by LCI\_\-collClearCounts().

\index{cue.c@{cue.c}!LCI\_\-deleteCue@{LCI\_\-deleteCue}}
\index{LCI\_\-deleteCue@{LCI\_\-deleteCue}!cue.c@{cue.c}}
\subsubsection[{LCI\_\-deleteCue}]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-deleteCue (
\begin{DoxyParamCaption}
\item[{{\bf LCI\_\-cue} $\ast$}]{cue}
\end{DoxyParamCaption}
)}\label{cue_8c_a06983ef6516cc9e991d7baf115e9fffd}


Delete a cue. 

This routine destroys the semaphore and wake-\/up timer and then frees the memory associated with the cue structure


\begin{DoxyParams}{Parameters}
{\em cue} & Pointer to an initialised cue structure (make sure that it is not currently running!)\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em LCI\_\-SUCCESS} & if all goes well \\
\hline
{\em LCI\_\-WUTDFAIL} & if the wake-\/up timer could not be destroyed, because it was in a bad state \\
\hline
\end{DoxyRetVals}


References LCI\_\-CUE\_\-UNSET.



Referenced by LCI\_\-collDelete().

\index{cue.c@{cue.c}!LCI\_\-getCueCounts@{LCI\_\-getCueCounts}}
\index{LCI\_\-getCueCounts@{LCI\_\-getCueCounts}!cue.c@{cue.c}}
\subsubsection[{LCI\_\-getCueCounts}]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-getCueCounts (
\begin{DoxyParamCaption}
\item[{{\bf LCI\_\-cue} $\ast$}]{cue, }
\item[{unsigned int $\ast$}]{nWait, }
\item[{unsigned int $\ast$}]{nSignal, }
\item[{unsigned int $\ast$}]{nTimeout}
\end{DoxyParamCaption}
)}\label{cue_8c_ad425faf1408ffb559d469279fe44722e}


Get cue counters. 

This routine obtains the counts of waits, signals and timeouts since the last time the cue was cleared.


\begin{DoxyParams}{Parameters}
{\em cue} & Pointer to a cue being used.\\
\hline
{\em nWait} & Address of an integer to receive the number of wait calls, or NULL if not needed.\\
\hline
{\em nSignal} & Address of an integer to receive the number of signal calls, or NULL if not needed.\\
\hline
{\em nTimeout} & Address of an integer to receive the number of timeouts, or NULL if not needed. \\
\hline
\end{DoxyParams}


Referenced by LCI\_\-collCounts().

\index{cue.c@{cue.c}!LCI\_\-newCue@{LCI\_\-newCue}}
\index{LCI\_\-newCue@{LCI\_\-newCue}!cue.c@{cue.c}}
\subsubsection[{LCI\_\-newCue}]{\setlength{\rightskip}{0pt plus 5cm}{\bf LCI\_\-cue}$\ast$ LCI\_\-newCue (
\begin{DoxyParamCaption}
\item[{void}]{}
\end{DoxyParamCaption}
)}\label{cue_8c_a31b61a3f852fcd8c2cd9dd36c5e682a4}


Create a new cue. 

This routine allocates memory for the cue structure then creates the timer and semaphore to be held by the structure

\begin{DoxyReturn}{Returns}
Pointer to an allocated and initialised cue structure, or NULL if there is an error. 
\end{DoxyReturn}


Referenced by LCI\_\-collCreate().

\index{cue.c@{cue.c}!LCI\_\-signalCue@{LCI\_\-signalCue}}
\index{LCI\_\-signalCue@{LCI\_\-signalCue}!cue.c@{cue.c}}
\subsubsection[{LCI\_\-signalCue}]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-signalCue (
\begin{DoxyParamCaption}
\item[{{\bf LCI\_\-cue} $\ast$}]{cue}
\end{DoxyParamCaption}
)}\label{cue_8c_a9e35d61657eb30d22f26d68392f52e05}


Signal cue completion. 

This routine signals completion by setting the end state to LCI\_\-CUE\_\-SIGNALED and giving the semaphore


\begin{DoxyParams}{Parameters}
{\em cue} & Pointer to a cue that is being waited upon \\
\hline
\end{DoxyParams}


References LCI\_\-CUE\_\-SIGNALED.

\index{cue.c@{cue.c}!LCI\_\-waitCue@{LCI\_\-waitCue}}
\index{LCI\_\-waitCue@{LCI\_\-waitCue}!cue.c@{cue.c}}
\subsubsection[{LCI\_\-waitCue}]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-waitCue (
\begin{DoxyParamCaption}
\item[{{\bf LCI\_\-cue} $\ast$}]{cue, }
\item[{unsigned}]{timeout}
\end{DoxyParamCaption}
)}\label{cue_8c_a5542d4f986974bee670ebb3cf8adeeda}


Wait for a cue to complete or time out. 

This routine starts the wake-\/up timer and takes the semaphore


\begin{DoxyParams}{Parameters}
{\em cue} & Pointer to an allocated, initialised cue structure (from LCI\_\-newCue)\\
\hline
{\em timeout} & Time, in microseconds, until the call times out.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em LCI\_\-CUE\_\-SIGNALED} & Another task called signal \\
\hline
{\em LCI\_\-CUE\_\-TIMEDOUT} & If the timer expired before the cue was signalled. \\
\hline
{\em LCI\_\-CUE\_\-FAILED} & Timer failed to start (because of incorrect state) \\
\hline
\end{DoxyRetVals}


References cue\_\-wut\_\-cb(), and LCI\_\-CUE\_\-FAILED.



Referenced by LCI\_\-collect().