rciRate(3)

NAME
rciRate, rciTimeout
 -- RCI timing primitives.

USAGE
#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;

ARGUMENTS

td --
    Pointer to task descriptor.

interval --
    Scheduling interval for the task (milliseconds).

offset --
    Scheduling interval offset for the task (milliseconds).

blkCount --
    Specifies the maximum time allowed to elapse before a task "times out".

lagCount --
    Specifies the number of control cycles that a task is permitted to "lag behind" its idealized schedule.

lagWindow --
    Specifies the number of cycles over which the "lag" is computed.

RESTRICTIONS
These routines must be called from the planning level.

DESCRIPTION
rciRate() is used to specify the execution timing when the task is driven by the RCI clock (as is the case with either the ON_CLOCK or 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 ON_FUNCTION discipline, it may be desirable to communicate the rate information to the external controlling process.

rciRate() may be called at any time. If the task is active and using either the ON_CLOCK or 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 tcb->newRate in the task control block is set to YES. The user application software (control or robot interface functions) can use this information to act accordingly, and notify external processes if necessary. tcb->newRate is cleared automatically at the end of the control cycle. newRate is always set for the first control cycle after a task starts.

rciTimeout() sets the timeout characteristics associated with a task.

blkCount is used to determine the block timeout time: this is set equal to blkCount * interval, where interval is the value specified by rciRate(). If an interval has not been specified for the task (only tasks running ON_CLOCK or ON_TRIGGER must have an interval specified), the constant 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 rciAbort() and calls the task's release function with the code BLK_TIMEOUT. Specifying a blkCount of 0 shuts off the block timeout mechanism. Specifying a blkCount of DEFAULTVALUE sets the block count to the default value of DEFAULT_BLK_COUNT, and specifying UNDEF leaves the existing block count unchanged.

NOTE: The lag timeout mechanism described below is not implemented is the current version of RCI.

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

DIAGNOSTICS
The functions return -1 in the event of an error. Error information is reported on the errorStack (q.v.).

Returned error codes, accessible with getErrorCode(), are:

EDescriptor --
    Invalid task descriptor.

ERange --
    interval is less than 1, or offset is less than 0.

These routines will abort the program if called from the control level.

BUGS
No check is implemented against having a task execute for too long, although the release code RUN_TIMEOUT has been defined for this condition.

SEE ALSO
rciCreate(3), rciStart(3), errorStack(3).