cue.c File Reference

Routines that act upon the cue structure. More...

#include <lci_p.h>
#include <LCI/LCI_msgs.h>
#include <MSG/MSG_pubdefs.h>
#include <PBS/MBA.h>
#include <PBS/WUT.h>
#include <PBS/SEM.h>
#include <string.h>

Functions
LCI_cue *	LCI_newCue (void)
	Create a new cue.
unsigned	LCI_deleteCue (LCI_cue *cue)
	Delete a cue.
void	LCI_clearCue (LCI_cue *cue)
	Clear a cue.
unsigned	LCI_waitCue (LCI_cue *cue, unsigned timeout)
	Wait for a cue to complete or time out.
void	LCI_signalCue (LCI_cue *cue)
	Signal cue completion.
void	LCI_clearCueCounts (LCI_cue *cue)
	Clear cue counters.
void	LCI_getCueCounts (LCI_cue *cue, unsigned int *nWait, unsigned int *nSignal, unsigned int *nTimeout)
	Get cue counters.
WUT_cb_status	cue_wut_cb (void *prm, WUT_tmr *wut)
	Timer callback.

---

Detailed Description

Routines that act upon the cue structure.

Author:

James Swain & Owen Saxton

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

$Id: cue.c,v 1.5 2011/03/29 19:32:57 saxton Exp $

---

Function Documentation

WUT_cb_status cue_wut_cb	(	void *	prm,
		WUT_tmr *	wut
	)

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

Parameters:

prm	Pointer to the LCI_cue structure
wut	Pointer to the wake-up timer

Return values:

WUT_K_STATE_CHANGE_YES

References LCI_CUE_TIMEDOUT.

Referenced by LCI_waitCue().

void LCI_clearCue

(

LCI_cue *

cue

)

Clear a cue.

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

Parameters:

cue	Pointer to an allocated, initialised cue structure (from LCI_newCue)

References LCI_CUE_UNSET.

Referenced by LCI_collect().

void LCI_clearCueCounts

(

LCI_cue *

cue

)

Clear cue counters.

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

Parameters:

cue	Pointer to a cue being used.

Referenced by LCI_collClearCounts().

unsigned LCI_deleteCue

(

LCI_cue *

cue

)

Delete a cue.

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

Parameters:

cue	Pointer to an initialised cue structure (make sure that it is not currently running!)

Return values:

LCI_SUCCESS	if all goes well
LCI_WUTDFAIL	if the wake-up timer could not be destroyed, because it was in a bad state

References LCI_CUE_UNSET.

Referenced by LCI_collDelete().

void LCI_getCueCounts	(	LCI_cue *	cue,
		unsigned int *	nWait,
		unsigned int *	nSignal,
		unsigned int *	nTimeout
	)

Get cue counters.

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

Parameters:

cue	Pointer to a cue being used.
nWait	Address of an integer to receive the number of wait calls, or NULL if not needed.
nSignal	Address of an integer to receive the number of signal calls, or NULL if not needed.
nTimeout	Address of an integer to receive the number of timeouts, or NULL if not needed.

Referenced by LCI_collCounts().

LCI_cue* LCI_newCue

(

void

)

Create a new cue.

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

Returns:

Pointer to an allocated and initialised cue structure, or NULL if there is an error.

Referenced by LCI_collCreate().

void LCI_signalCue

(

LCI_cue *

cue

)

Signal cue completion.

This routine signals completion by setting the end state to LCI_CUE_SIGNALED and giving the semaphore

Parameters:

cue	Pointer to a cue that is being waited upon

References LCI_CUE_SIGNALED.

unsigned LCI_waitCue	(	LCI_cue *	cue,
		unsigned	timeout
	)

Wait for a cue to complete or time out.

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

Parameters:

cue	Pointer to an allocated, initialised cue structure (from LCI_newCue)
timeout	Time, in microseconds, until the call times out.

Return values:

LCI_CUE_SIGNALED	Another task called signal
LCI_CUE_TIMEDOUT	If the timer expired before the cue was signalled.
LCI_CUE_FAILED	Timer failed to start (because of incorrect state)

References cue_wut_cb(), and LCI_CUE_FAILED.

Referenced by LCI_collect().