RCI TCB(3)

NAME
RCI_TCB -- RCI "task control block".

DEFINITION
We do not present the entire definition of the RCI_TCB here, but only those fields which are likely to be of interest to the programmer. Consult the relevant include files if you are masochistic (or desperate) enough to be interested in the complete definition.
typedef struct {

  /* ---- Fields accessible to the user ---- */

  /* state variables: */

  char controlMode;
   int cycleCount;

  /* control parameters */

   int scheduleDisp;
   int maxBlkCount;
   int maxLagCount;
   int lagWindow;

   int interval;
   int offset;

  /* control and robot interface functions */

   int (*triggerFxn)();
   int triggerArg;
   int (*wakeupFxn)();
   int wakeupArg;

   int (*startupFxn)();
   int (*controlFxn)();
   int (*releaseFxn)();
   int controlArg;

  /* information variables and flags */

   int lastTime;
   int startTime;
   int runTime;

  char newRate;
   int newInterval;
   int newOffset;

  /* user function support */

void *sharedMem;
void *globalMem;
void *privateMem;
   int fxnNotice;

  /* ---- fields used internally ---- */

             . . .

} RCI_TCB;

DESCRIPTION
The RCI_TCB structure contains most of the information associated with controlling an RCI task. This structure is made available to the programmer because the parameters it contains may be of value in developing applications. Unless otherwise stated, the contents of this structure should be treated as readonly quantities; many of the values are set directly by the various RCI primitives, and the structure provides a way to read these back. This could be important for developing library functions that need to save and restore context, since (at the moment) no primitives exist for otherwise obtaining this information.

The data structure is allocated and attached to a control task during the rciCreate() routine. It is used most directly by the RCI task monitor responsible for that task.

RCI_TCB is referenced by pointer. A pointer to the structure may be obtained from any task descriptor td by using the macro TASKTCB(td).

FIELDS

controlMode --
    Describes whether the task is active (ACTIVE) or idle (IDLE). Control tasks are activated with rciStart(), and "idled" with rciRelease().

cycleCount --
    The number of the current control cycle. This field is cleared when the task is created or released, and is incremented once every control cycle before the control function is called. The startup function hence sees a value of 0, and the first value seen by the control function is 1.

scheduleDisp --
    The scheduling discipline of the task, as specified by the primitive rciScheduling(): ON_CLOCK (task is run at a fixed interval), ON_FUNCTION (task is run on a condition detected by a polling function), ON_TRIGGER (task is run on a condition detected by a polling function, but that condition is previously encouraged by a trigger function which is run at a regular interval), and ON_SIGNAL (task is run on a UNIX signal in normal user process context).

maxBlkCount --
    The block timeout count set by rciTimeout().

maxLagCount --
    The lag timeout count set by rciTimeout().

lagWindow --
    The lag window set by rciTimeout().

interval --
    Time interval (milliseconds) associated with the task. Set by rciRate().

offset --
    Time offset (milliseconds) associated with the task. Set by rciRate().

triggerFxn, triggerArg --
    "Trigger" function and its argument, called by the RCI monitor when the task is scheduled using the ON_TRIGGER discipline. These values are set by the control task using the primitive rciSetTrigger().

wakeupFxn, wakeupArg --
    Polling function called by the RCI monitor to see if the task is runnable whenever it is scheduled using the ON_FUNCTION or ON_TRIGGER disciplines. These values are set using the primitive rciWakeupOn().

startupFxn, controlFxn, releaseFxn --
    Control functions set using rciControlFxns().

controlArg --
    Argument supplied to the task functions, supplied as the fourth argument to rciControlFxns().

lastTime --
    The time value (in milliseconds) corresponding to the start of the previous control cycle. It's value is UNDEF during the first control cycle.

startTime --
    The time value (in milliseconds) corresponding to when the task was started (with the primitive rciStart()). For the ON_CLOCK and ON_TRIGGER disciplines the task run time is computed relative to this value, using the interval and offset specified by rciRate().

runTime --
    The time value (in milliseconds) corresponding to when the task should run next. This field is only maintained for the ON_CLOCK and ON_TRIGGER disciplines, and is set by the RCI monitor only at the end of each control cycle.

newRate, newInterval, newOffset --
    Variable set by the RCI task monitor to indicate that a new rate-determining interval/offset pair has been specified by rciRate(), and the control function should look in the fields newInterval and newOffset to see what the new values are. The interval and offset fields will have already been set to the new values, and if the task is scheduled using either ON_CLOCK or ON_TRIGGER, then the RCI monitor will begin using the new rates (to schedule the task or the trigger function) from the time marking the beginning of the current cycle. newRate is cleared automatically by the RCI monitor after one cycle. It is always set for the duration of the first control cycle.

sharedMem, globalMem, privateMem --
    Scratch variables, available for reading and writing by the control functions, which are intended for saving pointers to shared and private memory areas. These pointers can be set up at the beginning of the control session: ideally, sharedMem contains a pointer obtained using getSharedMemory(), globalMem contains a pointer obtained using getGlobalMemory(), and privateMem() contains a pointer to a structure allocated locally by either the control functions or rciLocalMemory().

fxnNotice --
    Scratch variable through which the control functions can pass information.

BUGS
As was mentioned above, much of the information in this structure should be retrievable using special primitives (to ensure greater data hiding). Such primitives may be implemented at a later date.

SEE ALSO
TASKNUM(3), rciStart(3), rciScheduling(3), rciRate(3), rciWakeupOn(3), controlFxns(7), getSharedMemory(3).