\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciRate}{3}
\manSection{NAME}
{\tt \manName{rciRate}}, 
{\tt \manName{rciTimeout}}
 -- RCI timing primitives.
\manSection{USAGE}
\cverbatim
#include <rci.h>

rciRate (td, interval, offset)
   RCI_DESC *td;
   int interval, offset;

rciTimeout (td, blkTime, lagCount, lagWindow)
   RCI_DESC *td;
   int blkTime, lagCount, lagWindow; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt td} --}
Pointer to task descriptor.
\manItem{{\tt interval} --}
Scheduling interval for the task (milliseconds).
\manItem{{\tt offset} --}
Scheduling interval offset for the task (milliseconds).
\manItem{{\tt blkCount} --}
Specifies the maximum time allowed to elapse before a task ``times out''.
\manItem{{\tt lagCount} --}
Specifies the number of control cycles that a task is permitted to
``lag behind'' its idealized schedule.
\manItem{{\tt lagWindow} --}
Specifies the number of cycles over which the ``lag'' is
computed.
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
\manSection{DESCRIPTION}
{\tt rciRate()} is used to specify the execution timing when the task
is driven by the RCI clock (as is the case with either the {\tt ON_CLOCK} or
{\tt ON_TRIGGER} scheduling disciplines). Interval and offset information is
also used by all tasks to determine timeout information, regardless
of scheduling discipline. If the task is using the {\tt ON_FUNCTION}
discipline, it may be desirable to communicate the rate information
to the external controlling process.

{\tt rciRate()} may be called at any time. If the task is active and
using either the {\tt ON_CLOCK} or {\tt ON_TRIGGER} disciplines, the RCI
task monitor is advised of the rate change. When the task is next run 
(with the new rate in effect), the field {\tt tcb->newRate} in the
task control block is set to {\tt YES}. The user application software
(control or robot interface functions) can use this information
to act accordingly, and notify external processes if necessary. 
{\tt tcb->newRate} is cleared automatically at the end of the control cycle. 
{\tt newRate} is always set for the first control cycle after a task
starts.

{\tt rciTimeout()} sets the timeout characteristics associated with a
task. 

{\tt blkCount} is used to determine the {\it block timeout} time:
this is set equal to {\tt blkCount * interval},
where {\tt interval} is the value specified by {\tt rciRate()}.
If an {\tt interval} has not been specified for the task (only
tasks running {\tt ON_CLOCK} or {\tt ON_TRIGGER} {\it must}
have an interval specified), the constant {\tt DEFAULT_INTERVAL}
is used. 
The block timeout time is the timeout period associated with the
task: if the task does not run in this length of time, the RCI monitor calls
{\tt rciAbort()} and calls the task's release function with the code
{\tt BLK_TIMEOUT}.
Specifying a {\tt blkCount} of {\tt 0} shuts off the block timeout
mechanism. Specifying
a {\tt blkCount} of {\tt DEFAULTVALUE} sets the block count
to the default value of
{\tt DEFAULT_BLK_COUNT}, and specifying {\tt UNDEF} 
leaves the existing block count unchanged.

\manInset{{\bf NOTE}: The lag timeout mechanism described below
is not implemented is the current version of RCI.}

{\tt lagCount} is used to determine the {\it lag timeout}:
When enabled, the RCI monitor computes a running average, over a window
of {\tt lagWindow} control cycles, of the number of cycles that
the task is lagging behind schedule (as specified by {\tt interval}).
When this average hits .63 of {\tt lagCount}, the RCI monitor calls
{\tt rciAbort()} and calls the task's release function with the code
{\tt LAG_TIMEOUT}.
Specifying a {\tt lagCount} of {\tt 0} turns
the lag timeout off; specifying {\tt lagCount} as {\tt DEFAULTVALUE}
causes the lag count {\tt DEFAULT_LAGCOUNT} to be selected,
and specifying {\tt UNDEF} leaves the lag count unchanged.
{\tt DEFAULT_LAGCOUNT} is normally 0, so lag
timeouts are disabled by default.
If {\tt lagWindow} is specified as {\tt DEFAULTVALUE},
then the lag window is set to the default value of
{\tt DEFAULT_LAG_WINDOW}, and if it is specified
as {\tt UNDEF}, the lag window is unchanged.

\manSection{DIAGNOSTICS}
The functions return {\tt -1} in the event of an error.
Error information is reported on the {\it errorStack} (q.v.).

Returned error codes, accessible with {\tt getErrorCode()}, are:

\manItem{{\tt EDescriptor} --}
Invalid task descriptor.
\manItem{{\tt ERange} --}
{\tt interval} is less than 1, or {\tt offset} is less 
than 0.

These routines will abort the program if called from the control level.
\manSection{BUGS}
No check is implemented against having a task
execute for too long, although the release code {\tt RUN_TIMEOUT} has been
defined for this condition.
\manSection{SEE ALSO}
\raggedright
{\tt rciCreate(3)}, {\tt rciStart(3)}, {\tt errorStack(3)}.
\manEnd
\end
