NAME

cxInputAdd - register a file descripter for monitoring
#include <cx/ModuleCommand.h>

void *cxInputAdd( int fd, cxInputMask condition, cxInputCallbackProc callback, void *client_data)
None
fd
The Unix file descripter to monitor. Unix file descriptors are small integers zero or greater and are generally the return value from an open() system call.
condition
This routine can be used to monitor a file descripter for any combination of conditions: available input, writability, or an exception condition. The value of the condition argument can be cx_InputReadMask , cx_InputWriteMask , or cx_InputExceptMask. These correspond to the read set, write set, and exception set in the Unix select(2) system call. Though these values contain the word Mask, they cannot be combined with an inclusive ``or'' operation.
callback
The user callback routine. This subroutine is called by the control wrapper when one of the conditions is satisfied. See below for the calling sequence used by cxInputAdd.
client_data
Arbitrary client data. This value is passed to the user callback routine when the condition occurs.
cxInputAdd implements a facility whereby a module can request that it be informed when a particular Unix file descripter is ready for reading or writing, or has suffered some exception condition. This gives the module writer access to the module scheduler, allowing modification of the scheduler's select(2) Unix system call.

The return value of this function is an opaque handle that can be used in a subsequent call to cxInputRemove for removing the monitoring function.

When the specified condition occurs, the Control Wrapper will call the function named in the callback argument to cxInputAdd. This function is assumed to have three formal arguments, as follows:

void (*cxInputCallbackProc)( void *client_data,
     int fd,
     void *handle)

The argument client_data is the value passed in to cxInputAdd. Argument fd is the Unix file descripter that is affected. Argument handle is the return value from cxInputAdd that corresponds to this activity. It may be used in a call to cxInputRemove if conditions warrant.

The action of calling a callback procedure is not equivalent to actually firing the module. If the callback routine decides that the module should be fired based on new information resulting from the file descriptor activity, it should use cxFireASAP to schedule the future firing of the module.

Because of the synchronous nature of the firing behavior of IRIS Explorer modules, a file descripter callback procedure will never be called when the module is firing. These callbacks are only called when the module is quiescent.

This facility works for both X and non-X modules.

The following code fragment shows an example of how this routine might be used within a module:

#include <cx/Typedefs.h>
#include <cx/ModuleCommand.h>
      ...
      FILE *fd;
      void *handle;
      void haveData();
      ...
      /*
       * Use "popen(3E)" to start some external shell command.
       */
      if ( (fd=popen( command, "r" )) == NULL) {
            cxModAlert( "Command failed." );
            return;
      }
      /*
       * Now attach the file descripter to the scheduler.
       */
      handle = cxInputAdd( fileno(fd), cx_InputReadMask,
            haveData, (void *)fd );
      ...
/*
 * User callback -- called whenever data can be read.
 */
void haveData( client_data, fd, handle )
void *client_data;
int fd;
void *handle;
{
      char buf[BUFSIZ];
      int len;
      len = read( fd, buf, sizeof buf );
      /*
       * If EOF or error was encountered, close the pipe and remove the
       * descripter from the scheduler.
       */
      if (len <= 0) {
            pclose( (FILE *)client_data );
            cxInputRemove( handle );
      }
      /*
       * If conditions warrent, schedule the module for firing.
       */
      if ( /* some condition */ ) {
            cxFireASAP();
      }
}
select(2), cxInputRemove(3E), XtAddInput(3X)
Last modified: Mon Nov 6 16:33:21 GMT 2000
[ Documentation Home ]
© The Numerical Algorithms Group Ltd, Oxford UK. 1996