rciWakeupOn(3)

NAME
rciWakeupOn, rciSetTrigger -- RCI control level scheduling functions.

USAGE
#include <rci.h>

rciWakeupOn (td, fxn, arg)
  RCI_DESC *td;
  int (*fxn)();
  int arg;

rciSetTrigger (fxn, arg)
  int (*fxn)();
  int arg;

ARGUMENTS

td --
    Pointer to task descriptor.

fxn --
    Pointer to function.

arg --
    Argument for function.

DESCRIPTION
These functions are used by RCI control functions for scheduling purposes.

rciWakeupOn() is usually called by the task's startup function (see controlFxns(7)) when the scheduling discipline is either ON_FUNCTION, ON_TRIGGER, or ON_SIGNAL. It specifies a wakeup function which the RCI monitor will poll to determine when the task should be executed; the task will be executed when the wakeup function returns true. rciWakeupOn() does not have to be called by the task itself; it can be called by any task with access to the task descriptor td. If this is done, however, and the specified argument is a pointer value, care must be taken to make sure the pointer value is portable across CPUs.

The RCI system supports several default wakeup functions. rciOnInterrupt() (q.v.) returns true once and only once when an interrupt associated with the task is delivered. At the moment, this function is only applicable to tasks running on the arbiter CPU, where the interrupt is provided either by an RCI device (using the ON_FUNCTION or ON_TRIGGER disciplines), or by a UNIX signal (using the ON_SIGNAL discipline). The function simRobotsReady() (q.v.) is applicable to tasks running robots in simulator mode (using the ON_SIGNAL discipline); it returns true when all the (simulated) robots connected to the task are ready for another control cycle, and otherwise resets the interrupt signal. The function readReady() associated with RCI I/O devices (see IOdevice(7)) is designed to be used as a wakeup function; it takes as an argument a pointer to the device and returns true when the device is ready to be read from.

rciSetTrigger() is used when a task is being run using the ON_TRIGGER discipline. It sets up a trigger function which will be executed at the next time appropriate to the task's interval/offset as specified by rciRate(). The purpose of the trigger is to wake up some external process, which will in turn (a little later) wake up the task itself through an event detected by the wakeup function. Only one trigger function can be specified at a time; subsequent calls to rciSetTrigger() will overwrite the previous trigger function. A value of NULLF for a trigger function will cancel the trigger.

DIAGNOSTICS
rciSetTrigger() will cause an RCI abort with an EBadTask code if called from the planning task.

rciWakeupOn() will cause an RCI abort with an EDescriptor code if the task descriptor is NULL.

SEE ALSO
rciScheduling(3), rciOnInterrupt(3), simRobotsReady(3), IOdevice(7), controlFxns(7).