runMonitorFxn(3)

NAME
runMonitorFxn, deleteMonitorFxn, runMotionFxn -- RCCL routines for controlling monitor functions.

USAGE
#include <rccl.h>

id = runMonitorFxn (mnp, fxn, arg)
  int id;
  MANIP *mnp;
  int (*fxn)();
  int arg;

deleteMonitorFxn (mnp, id)
  MANIP *mnp;
  int id;

runMotionFxn (mnp, fxn, arg)
  MANIP *mnp;
  int (*fxn)();
  int arg;

ARGUMENTS

mnp --
    Manipulator with which the function is to be associated.

fxn --
    Pointer to function.

arg --
    Application supplied argument for the function.

id --
    Handle for removing monitor function.

RESTRICTIONS
These routines must be called from the planning level.

DESCRIPTION
These routines control the execution of application specific monitor functions. A monitor function, when active, is called by the trajectory generator once every control cycle (so the function executes at the same rate as the trajectory generator itself; see rcclSetInterval(3)). A monitor function will execute only while the trajectory generator is running.

runMonitorFxn() establishes a permanent monitor function that remains active until either it is explicitly deleted with deleteMonitorFxn(), or the trajectory generator is turned off (through either a call to rcclRelease() or an RCI abort condition). It returns an id which is used by deleteMonitorFxn(). The associated manipulator mnp indicates which CPU the function should execute on; it runs on the same CPU as the trajectory generator for mnp. The maximum number of permanent monitor functions that can be associated with a manipulator at one time is MAX_MONITOR_FXNS.

deleteMonitorFxn() deletes the permanent monitor function specified by id.

runMotionFxn() establishes a motion monitor function that will be active only for the duration of the next motion requested for the manipulator mnp. It is executed on the same CPU as the trajectory generator for mnp. The maximum number of motion monitors that can be run for any given motion is MAX_MONITOR_FXNS.

When executed, monitor functions are called by the trajectory generator with the following arguments:

        (*fxn)(arg, mnp)
        int arg;
        MANIP *mnp;
        {
        }

where arg and mnp are the application argument and manipulator specified by either runMonitorFxn() or runMotionFunction(). Note that the actual address of mnp may be different from that used by the planning level.

Monitor functions must be part of the program's control segment; i.e., they must be contained in modules specified to the right of the CTRL keyword in the rcc command (q.v.) used to compile/load the program. Since the functions are executed at the control level, their execution times need to be contained within a single control cycle. They also do not have access to the UNIX system services. Some RCI utility routines provide such things as diagnostic printing (rciPrintf()), memory allocation (rciMalloc()), and sending UNIX signals to the planning task (rciSignal()). This is discussed in more detail in the "Mulit-RCCL User's Guide".

DIAGNOSTICS
These functions return -1 in the event of an error. They will automatically abort the program if the option RCCL_ERROR_EXIT is set (see rcclSetOptions(3)). Error codes and messages are placed on the errorStack (q.v.).

Error codes set by runMonitorFxn() include:

ETaskActive --
    The trajectory generator is not running.

ETooMany --
    The number of permanent monitors would exceed MAX_MONITOR_FXNS.

Error codes set by deleteMonitorFxn() include:

ETaskActive --
    The trajectory generator is not running.

Error codes set by runMotionFxn() include:

ETooMany --
    The number of motion monitors for the next motion would exceed MAX_MONITOR_FXNS.

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

SEE ALSO
rcclCreate(3), rcclStart(3), rcclSetInterval(3), transEval(3), errorStack(3).