\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciScheduling}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{rciScheduling}}
-- set scheduling discipline for RCI task.
}
\manSection{USAGE}
\cverbatim
#include <rci.h>

rciScheduling (td, disp, dev)
  RCI_DESC *td;
  int disp;
  int dev; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt td} --}
Pointer to task descriptor.
\manItem{{\tt disp} --}
Scheduling discipline.
\manItem{{\tt dev} --}
Used only for tasks running on the arbiter CPU. If the scheduling discipline
is {\tt ON_FUNCTION} or {\tt ON_TRIGGER}, then this is the 
file descriptor for the UNIX device which provides the polling interrupt.
If the scheduling discipline is {\tt ON_SIGNAL}, then this is the
signal number. Ignored in other cases.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
This primitive sets the scheduling discipline associated with
an RCI control task. There are presently four disciplines, which describe
how the task will be scheduled after it has been started by a
call to {\tt rciStart()}:

\manItem{{\tt ON_CLOCK} --}
Causes the task to be executed periodically at the sample interval/offset
specified  by {\tt rciRate()}.

\manItem{{\tt ON_FUNCTION} --}
Causes the task to be executed whenever a specified {\it wakeup} function
returns true. This wakeup function must be specified from the control
level by the task's {\tt startup} function, using the call
{\tt rciWakeupOn()} (q.v.). If no function is specified, then the task will
never be woken up.

\manItem{{\tt ON_TRIGGER} --}
This is similar to {\tt ON_FUNCTION} in that a
wakeup function must be specified, in the {\tt startup} routine, which
will be used as the basis for executing the task.
The {\tt ON_TRIGGER} discipline extends this by making it
possible to set up a {\tt trigger}
function which executes at the sample interval/offset specified by
{\tt rciRate()} and which can be used to signal some external process
which will (shortly thereafter) wake up the task itself by setting a condition
detected by the wakeup function. The {\tt ON_TRIGGER} discipline
hence provides control task timing which is indirectly bound to the system
clock; this allows a programmer to exploit parallelism between an external
process and the RCI tasks. The trigger itself must be set up by the
control functions before each cycle (i.e., during the startup function and
every cycle therafter). This is done using the primitive 
{\tt rciSetTrigger()} (q.v.).

\manItem{{\tt ON_SIGNAL} --}
This discipline is somewhat different from the others in that it
causes the task to execute every time a particular UNIX signal
is delivered. The task is actually 
executed by a handler bound to that signal, from within
the context of the planning task's UNIX process. This discipline is
mainly used for simulation purposes. Tasks using this discipline must
be resident on the arbiter CPU. The task {\it startup} function
must also specify a wakeup function that ``notices'' the signal, 
using {\tt rciWakeupOn()}.

\manItem{}
{\bf NOTE}: There are support functions available for using the
the {\tt ON_\-SIG\-NAL} to do task simulation. See {\tt simSupport()}.

The {\tt dev} argument is used only in the following cases:

\manItemIndent{6}
\manItem{1.} 
The control task is resident on the arbiter CPU, and either
the {\tt ON_FUNCTION} or {\tt ON_TRIGGER} disciplines have been specified.
In this case, {\tt dev} should be the file descriptor of a valid RCI device
whose interrupt will be used in conjunction with the specified task
wakeup function to execute the task. The reason this is necessary is that
the arbiter cannot always use the wakeup functions to 
poll for task execution, since it is busy running UNIX. An RCI device
is a UNIX device (driver) which implements a few special RCI
{\tt ioctls()} which give the driver the ability to run an
RCI task.

\manItem{2.}
The {\tt ON_SIGNAL} discipline is specified. In this case, {\tt dev} is
the number of the UNIX signal to which the task is connected. This signal
must not be used for other purposes by the program, since RCI will
attach its own signal handler to it. The signal number must be a valid UNIX
signal number, and may not be {\tt SIGHUP} or
{\tt SIGXCPU} since these are reserved by RCI.

\manItemReset

\manSection{DIAGNOSTICS}
The function returns {\tt -1} in the event of failure. Error information
is reported on the {\it errorStack} (q.v.). Returned error codes
are accessible with {\tt getErrorCode()}. Possible error codes
include:

\manItem{{\tt ETaskActive} --}
The RCI task is presently active.
\manItem{{\tt ENotDefined} --}
Invalid scheduling discipline specified.
\manItem{{\tt ENotAvail} --}
Attempt to set up {\tt ON_SIGNAL} discipline for a task not running on
the arbiter CPU.
\manItem{{\tt EBadDev} --}
Illegal device specified (bad signal number or device is not a valid
RCI device).
\manItem{{\tt EMemory} --}
Process is out of memory.
\manItem{{\tt EInternal} --}
Internal error condition.

The routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\raggedright
{\tt rciRate(3)}, {\tt rciStart(3)}, {\tt rciWakeupOn(3)}, 
{\tt simSupport(3)}.
\manEnd
\end
