\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{RCI TCB}{3}
\manSection{NAME}
{\tt \manName{RCI_TCB}}
-- RCI ``task control block''.
\manSection{DEFINITION}
We do not present the entire definition of the {\tt 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.
\cverbatim
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; @endcverbatim
\manSection{DESCRIPTION}
The {\tt 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 {\it 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 {\tt rciCreate()} routine.  It is used most directly by the 
RCI task monitor responsible for that task.

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

\manSection{FIELDS}

\manItem{{\tt controlMode} --}
Describes whether the task is active ({\tt ACTIVE}) or idle ({\tt IDLE}).
Control tasks are activated with {\tt rciStart()}, and ``idled'' with
{\tt rciRelease()}.
\manItem{{\tt 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.
\manItem{{\tt scheduleDisp} --}
{\tolerance=10000
The scheduling discipline of the task, as specified by
the primitive {\tt rciScheduling()}: {\tt ON_CLOCK} (task is run
at a fixed interval), 
{\tt ON_FUNCTION} (task is run on a condition detected by a 
polling function), 
{\tt ON_TRIGGER} (task is run on a condition detected by a polling function,
but that condition is previously encouraged by a {\it trigger} function
which is run at a regular interval), and {\tt ON_SIGNAL}
(task is run on a UNIX signal in normal user process context).

}
\manItem{{\tt maxBlkCount} --}
The {\it block timeout count} set by {\tt rciTimeout()}. 
\manItem{{\tt maxLagCount} --}
The {\it lag timeout count} set by {\tt rciTimeout()}. 
\manItem{{\tt lagWindow} --}
The {\it lag window} set by {\tt rciTimeout()}.
\manItem{{\tt interval} --}
Time interval (milliseconds) associated with the task. Set by {\tt rciRate()}.
\manItem{{\tt offset} --}
Time offset (milliseconds) associated with the task. Set by {\tt rciRate()}.
\manItem{{\tt triggerFxn}, {\tt triggerArg} --}
``Trigger'' function and its argument, called by the RCI monitor 
when the task is scheduled using the {\tt ON_TRIGGER} discipline.
These values are set by the control task using the primitive
{\tt rciSetTrigger()}.
\manItem{{\tt wakeupFxn}, {\tt wakeupArg} --}
Polling function called by the RCI monitor to see if the task is runnable
whenever it is scheduled using the {\tt ON_FUNCTION} or {\tt ON_TRIGGER}
disciplines.
These values are set using the primitive {\tt rciWakeupOn()}.
\manItem{{\tt startupFxn}, {\tt controlFxn}, {\tt releaseFxn} --}
Control functions set using {\tt rciControlFxns()}.
\manItem{{\tt controlArg} --}
Argument supplied to the task functions, supplied as the fourth argument to
{\tt rciControlFxns()}.
\manItem{{\tt lastTime} --}
The time value (in milliseconds) corresponding to the start of
the {\it previous} control cycle. It's value is {\tt UNDEF} during
the first control cycle.
\manItem{{\tt startTime} --}
{\tolerance=10000
The time value (in milliseconds) corresponding to when the task
was started (with the primitive {\tt rciStart()}). For the {\tt ON_CLOCK}
and {\tt ON_TRIGGER} disciplines the task run time is computed 
relative to this value, using the {\it interval} and {\it offset} specified
by {\tt rciRate()}.

}
\manItem{{\tt runTime} --}
{\tolerance=10000
The time value (in milliseconds) corresponding to when the task
should run {\it next}. This field is only maintained for the
{\tt ON_CLOCK} and {\tt ON_TRIGGER} disciplines, and is set by
the RCI monitor only at the end of each control cycle.
\manItem{{\tt newRate}, {\tt newInterval}, {\tt newOffset} --}
Variable set by the RCI task monitor to indicate that a new rate-determining 
interval/offset pair has been specified by {\tt rciRate()}, 
and the control function
should look in the fields {\tt newInterval} and {\tt newOffset}
to see what the new values are. The {\tt interval} and {\tt offset} fields
will have already been set to the new values, and if the task is scheduled
using either {\tt ON\_CLOCK} or 
{\tt 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.
{\tt newRate} is cleared automatically by the RCI monitor
after one cycle. It is always set for the duration of the
first control cycle.

}
\manItem{{\tt sharedMem}, {\tt globalMem}, {\tt 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, {\tt sharedMem} contains a
pointer obtained using {\tt getSharedMemory()}, {\tt globalMem}
contains a pointer obtained using {\tt getGlobalMemory()}, and
{\tt privateMem()} contains a pointer to a structure allocated locally
by either the control functions or {\tt rciLocalMemory()}.
\manItem{{\tt fxnNotice} --}
Scratch variable through which the control functions can pass information.

\manSection{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.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt TASKNUM(3)}, {\tt rciStart(3)}, {\tt rciScheduling(3)},
{\tt rciRate(3)}, {\tt rciWakeupOn(3)}, {\tt controlFxns(7)}, {\tt
getSharedMemory(3)}. 
\manEnd
\end
