\hypertarget{cue_8h}{
\section{cue.h File Reference}
\label{cue_8h}\index{cue.h@{cue.h}}
}
Definitions for the routines that act upon the cue structure. 



This graph shows which files directly or indirectly include this file:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=133pt]{cue_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
\hypertarget{cue_8h_a0}{
typedef \hyperlink{struct__LCI__cue}{\_\-LCI\_\-cue} \hyperlink{cue_8h_a0}{LCI\_\-cue}}
\label{cue_8h_a0}

\begin{CompactList}\small\item\em Declaration of the opaque cue structure. \item\end{CompactList}\end{CompactItemize}
\subsection*{Enumerations}
\begin{CompactItemize}
\item 
enum \hyperlink{cue_8h_a12}{LCI\_\-CUE\_\-END} \{ \par
\hyperlink{cue_8h_a12a1}{LCI\_\-CUE\_\-FAILED} =  -1, 
\par
\hyperlink{cue_8h_a12a2}{LCI\_\-CUE\_\-UNSET} =  0, 
\par
\hyperlink{cue_8h_a12a3}{LCI\_\-CUE\_\-SIGNALED} =  1, 
\par
\hyperlink{cue_8h_a12a4}{LCI\_\-CUE\_\-TIMEDOUT} =  2
 \}
\begin{CompactList}\small\item\em State information returned from LCI\_\-wait indicating how the cue was terminated. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
void \hyperlink{cue_8h_a5}{LCI\_\-clear\-Cue} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue)
\begin{CompactList}\small\item\em Clear a cue. \item\end{CompactList}\item 
void \hyperlink{cue_8h_a6}{LCI\_\-clear\-Cue\-Counts} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue)
\begin{CompactList}\small\item\em Clear cue counters. \item\end{CompactList}\item 
unsigned \hyperlink{cue_8h_a7}{LCI\_\-delete\-Cue} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue)
\begin{CompactList}\small\item\em Delete a cue. \item\end{CompactList}\item 
void \hyperlink{cue_8h_a8}{LCI\_\-get\-Cue\-Counts} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue, unsigned int $\ast$n\-Wait, unsigned int $\ast$n\-Signal, unsigned int $\ast$n\-Timeout)
\begin{CompactList}\small\item\em Get cue counters. \item\end{CompactList}\item 
\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$ \hyperlink{cue_8h_a9}{LCI\_\-new\-Cue} (void)
\begin{CompactList}\small\item\em Create a new cue. \item\end{CompactList}\item 
void \hyperlink{cue_8h_a10}{LCI\_\-signal\-Cue} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue)
\begin{CompactList}\small\item\em Signal cue completion. \item\end{CompactList}\item 
unsigned \hyperlink{cue_8h_a11}{LCI\_\-wait\-Cue} (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$cue, unsigned timeout)
\begin{CompactList}\small\item\em Wait for a cue to complete or time out. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Definitions for the routines that act upon the cue structure. 

\begin{Desc}
\item[Author:]James Swain \& Owen Saxton\end{Desc}
\begin{Desc}
\item[Id]\hyperlink{cue_8h}{cue.h},v 1.4 2007/08/21 22:55:41 saxton Exp \end{Desc}


\subsection{Enumeration Type Documentation}
\hypertarget{cue_8h_a12}{
\index{cue.h@{cue.h}!LCI_CUE_END@{LCI\_\-CUE\_\-END}}
\index{LCI_CUE_END@{LCI\_\-CUE\_\-END}!cue.h@{cue.h}}
\subsubsection[LCI\_\-CUE\_\-END]{\setlength{\rightskip}{0pt plus 5cm}enum \hyperlink{cue_8h_a12}{LCI\_\-CUE\_\-END}}}
\label{cue_8h_a12}


State information returned from LCI\_\-wait indicating how the cue was terminated. 

\begin{Desc}
\item[Enumerator: ]\par
\begin{description}
\index{LCI_CUE_FAILED@{LCI\_\-CUE\_\-FAILED}!cue.h@{cue.h}}\index{cue.h@{cue.h}!LCI_CUE_FAILED@{LCI\_\-CUE\_\-FAILED}}\item[{\em 
\hypertarget{cue_8h_a12a1}{
LCI\_\-CUE\_\-FAILED}
\label{cue_8h_a12a1}
}]The wake-up timer failed to start. \index{LCI_CUE_UNSET@{LCI\_\-CUE\_\-UNSET}!cue.h@{cue.h}}\index{cue.h@{cue.h}!LCI_CUE_UNSET@{LCI\_\-CUE\_\-UNSET}}\item[{\em 
\hypertarget{cue_8h_a12a2}{
LCI\_\-CUE\_\-UNSET}
\label{cue_8h_a12a2}
}]No end state to report (the cue has never been used or is currently waiting). \index{LCI_CUE_SIGNALED@{LCI\_\-CUE\_\-SIGNALED}!cue.h@{cue.h}}\index{cue.h@{cue.h}!LCI_CUE_SIGNALED@{LCI\_\-CUE\_\-SIGNALED}}\item[{\em 
\hypertarget{cue_8h_a12a3}{
LCI\_\-CUE\_\-SIGNALED}
\label{cue_8h_a12a3}
}]The cue was signalled. \index{LCI_CUE_TIMEDOUT@{LCI\_\-CUE\_\-TIMEDOUT}!cue.h@{cue.h}}\index{cue.h@{cue.h}!LCI_CUE_TIMEDOUT@{LCI\_\-CUE\_\-TIMEDOUT}}\item[{\em 
\hypertarget{cue_8h_a12a4}{
LCI\_\-CUE\_\-TIMEDOUT}
\label{cue_8h_a12a4}
}]The wake-up timer went off. \end{description}
\end{Desc}



\subsection{Function Documentation}
\hypertarget{cue_8h_a5}{
\index{cue.h@{cue.h}!LCI_clearCue@{LCI\_\-clearCue}}
\index{LCI_clearCue@{LCI\_\-clearCue}!cue.h@{cue.h}}
\subsubsection[LCI\_\-clearCue]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-clear\-Cue (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$ {\em cue})}}
\label{cue_8h_a5}


Clear a cue. 

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to an allocated, initialised cue structure (from LCI\_\-new\-Cue)\end{description}
\end{Desc}
\hypertarget{cue_8h_a6}{
\index{cue.h@{cue.h}!LCI_clearCueCounts@{LCI\_\-clearCueCounts}}
\index{LCI_clearCueCounts@{LCI\_\-clearCueCounts}!cue.h@{cue.h}}
\subsubsection[LCI\_\-clearCueCounts]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-clear\-Cue\-Counts (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$ {\em cue})}}
\label{cue_8h_a6}


Clear cue counters. 

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to a cue being used.\end{description}
\end{Desc}
\hypertarget{cue_8h_a7}{
\index{cue.h@{cue.h}!LCI_deleteCue@{LCI\_\-deleteCue}}
\index{LCI_deleteCue@{LCI\_\-deleteCue}!cue.h@{cue.h}}
\subsubsection[LCI\_\-deleteCue]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-delete\-Cue (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$ {\em cue})}}
\label{cue_8h_a7}


Delete a cue. 

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to an initialised cue structure (make sure that it is not currently running!)\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-SUCCESS}]if all goes well \item[{\em LCI\_\-WUTDFAIL}]if the wake-up timer could not be destroyed, because it was in a bad state\end{description}
\end{Desc}
\hypertarget{cue_8h_a8}{
\index{cue.h@{cue.h}!LCI_getCueCounts@{LCI\_\-getCueCounts}}
\index{LCI_getCueCounts@{LCI\_\-getCueCounts}!cue.h@{cue.h}}
\subsubsection[LCI\_\-getCueCounts]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-get\-Cue\-Counts (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$ {\em cue}, unsigned int $\ast$ {\em n\-Wait}, unsigned int $\ast$ {\em n\-Signal}, unsigned int $\ast$ {\em n\-Timeout})}}
\label{cue_8h_a8}


Get cue counters. 

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to a cue being used.\item[{\em n\-Wait}]Address of an integer to receive the number of wait calls, or NULL if not needed.\item[{\em n\-Signal}]Address of an integer to receive the number of signal calls, or NULL if not needed.\item[{\em n\-Timeout}]Address of an integer to receive the number of timeouts, or NULL if not needed.\end{description}
\end{Desc}
\hypertarget{cue_8h_a9}{
\index{cue.h@{cue.h}!LCI_newCue@{LCI\_\-newCue}}
\index{LCI_newCue@{LCI\_\-newCue}!cue.h@{cue.h}}
\subsubsection[LCI\_\-newCue]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__LCI__cue}{LCI\_\-cue}$\ast$ LCI\_\-new\-Cue (void)}}
\label{cue_8h_a9}


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{Desc}
\item[Returns:]Pointer to an allocated and initialised cue structure, or NULL if there is an error.\end{Desc}
\hypertarget{cue_8h_a10}{
\index{cue.h@{cue.h}!LCI_signalCue@{LCI\_\-signalCue}}
\index{LCI_signalCue@{LCI\_\-signalCue}!cue.h@{cue.h}}
\subsubsection[LCI\_\-signalCue]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-signal\-Cue (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$ {\em cue})}}
\label{cue_8h_a10}


Signal cue completion. 

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to a cue that is being waited upon\end{description}
\end{Desc}
\hypertarget{cue_8h_a11}{
\index{cue.h@{cue.h}!LCI_waitCue@{LCI\_\-waitCue}}
\index{LCI_waitCue@{LCI\_\-waitCue}!cue.h@{cue.h}}
\subsubsection[LCI\_\-waitCue]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-wait\-Cue (\hyperlink{struct__LCI__cue}{LCI\_\-cue} $\ast$ {\em cue}, unsigned {\em timeout})}}
\label{cue_8h_a11}


Wait for a cue to complete or time out. 

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cue}]Pointer to an allocated, initialised cue structure (from LCI\_\-new\-Cue)\item[{\em timeout}]Time, in microseconds, until the call times out.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-CUE\_\-SIGNALED}]Another task called signal \item[{\em LCI\_\-CUE\_\-TIMEDOUT}]If the timer expired before the cue was signalled. \item[{\em LCI\_\-CUE\_\-FAILED}]Timer failed to start (because of incorrect state)\end{description}
\end{Desc}
