\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciWakeupOn}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{rciWakeupOn}},
{\tt \manName{rciSetTrigger}} --
RCI control level scheduling functions.
}
\manSection{USAGE}
\cverbatim
#include <rci.h>

rciWakeupOn (td, fxn, arg)
  RCI_DESC *td;  
  int (*fxn)();
  int arg;

rciSetTrigger (fxn, arg)
  int (*fxn)();
  int arg; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt td} --}
Pointer to task descriptor.
\manItem{{\tt fxn} --}
Pointer to function.
\manItem{{\tt arg} --}
Argument for function.
\manSection{DESCRIPTION}
These functions are used by RCI control functions for scheduling purposes.

{\tt rciWakeupOn()} is usually called by the task's startup function (see
{\tt controlFxns(7)}) when the scheduling discipline is either
{\tt ON_FUNCTION}, {\tt ON_TRIGGER}, or {\tt ON_SIGNAL}.
It specifies a wakeup function which the RCI monitor
will poll to determine when the task should be executed; the task
will be executed when the wakeup function returns true. {\tt rciWakeupOn()}
does not have to be called by the task itself; it can be called by
any task with access to the task descriptor {\tt td}. If this is done,
however, and the specified
argument is a pointer value, care must be taken to make sure the pointer
value is portable across CPUs.

The RCI system supports several default wakeup functions.
{\tt rciOnInterrupt()} (q.v.) returns true once and only once
when an interrupt associated with the task is delivered. At the moment,
this function is only applicable to tasks running on the arbiter CPU,
where the interrupt is provided either by an RCI device (using
the {\tt ON_FUNCTION} or {\tt ON_TRIGGER} disciplines), or by a UNIX 
signal (using the {\tt ON_SIGNAL} discipline). The
function {\tt simRobotsReady()} (q.v.) is applicable to tasks running
robots in simulator mode (using the {\tt ON_SIGNAL} discipline);
it returns true when all the (simulated) 
robots connected to the task are ready for another control cycle, and
otherwise resets the interrupt signal. The function {\tt readReady()}
associated with RCI I/O devices (see {\tt IOdevice(7)}) is designed to be used
as a wakeup function; it takes as an argument a pointer
to the device and returns true when the device is ready to be read
from.

{\tt rciSetTrigger()} is used when a task is being run using
the {\tt ON_TRIGGER} discipline. It sets up a trigger function
which will be executed at the next time appropriate to the task's
interval/offset as specified by {\tt rciRate()}. The purpose
of the trigger is to wake up some external process, which will in turn
(a little later) wake up the task itself through an event detected
by the wakeup function.
Only one trigger function can be specified at a time; subsequent
calls to {\tt rciSetTrigger()} will overwrite the previous
trigger function. A value of {\tt NULLF} for a trigger function will
cancel the trigger.

\manSection{DIAGNOSTICS}
{\tt rciSetTrigger()} will cause an RCI abort with an 
{\tt EBadTask} code if called from the
planning task.

{\tt rciWakeupOn()} will cause an RCI abort with an {\tt EDescriptor}
code if the task descriptor is {\tt NULL}.

\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rciScheduling(3)}, {\tt rciOnInterrupt(3)}, {\tt simRobotsReady(3)}, 
{\tt IOdevice(7)}, {\tt controlFxns(7)}.
\manEnd
\end
