Document:     events

Purpose:      Describes routines for event-driven programs.

Category:     SYSTEM

File:         events.src

Author:       J.P. Terlouw

Description:  The eventhandler routines allow a program to specify ("schedule")
              one or more functions to be called when a specified event
              occurs. An event can be one of the following:
              - data can be read from a specified file descriptor;
              - data can be written to a specified file descriptor;
              - a specified period of time has elapsed.

              The following elementary routines are available:

                ScheduleRead  -  Schedule function for reading. 
                ScheduleWrite -  Schedule function for writing.
                ScheduleTimer -  Schedule function to be called periodically.
                Deschedule    -  Deschedule function.
                DescheduleAll -  Deschedule all scheduled functions.
                MainLoop      -  Wait for events and call scheduled functions.
                BreakMainLoop -  Terminate current MainLoop invocation.

              The following function is related to the X toolkit:

                AttachXt      -  Required when program uses the X toolkit.

              Each routine is described in the appropriate document.

Example:      The following program writes every second a dash to the screen.
              It does this 10 times. During the same time it also reads
              characters from the keyboard and writes these to the screen.
              When a dot has been typed, it stops looking for more characters.

          #include "stddef.h"
          #include "stdio.h"
          #include <fcntl.h>   
          #include <sgtty.h>
          #include "events.h"
          
          void timefun(ident id, void *arg)
          {
             static int count=10;
             
             write(1,(char*)arg,1);
             count--;
             if (!count) Deschedule(&id);   /* deschedule after 10 dashes */
          }

          void readfun(ident id, int fd, void *arg)
          {
             char c;
              
             read(0,&c,1);
             if (c=='.') Deschedule(&id);   /* deschedule when dot seen   */
             write(1,&c,1);                 /* echo character read        */
          }
          
          void main(void)
          {
             struct sgttyb tt;
          
             ioctl(0,TIOCGETP,&tt);
             tt.sg_flags |=  RAW;
             tt.sg_flags &= ~ECHO;
             ioctl(0,TIOCSETP,&tt);       /* set modes for keyboard input  */
          
             (void)ScheduleRead(readfun, 0, NULL);     /* read from stdin  */
             (void)ScheduleTimer(timefun, 1000, "-");  /* every 1000 ms    */
             MainLoop();                               /* handle events    */
             write(1,"\n",1); /* all functions descheduled - MainLoop returns */
          }

Related Docs: ScheduleRead.dc3, ScheduleWrite.dc3, ScheduleTimer.dc3,
              Deschedule.dc3, DescheduleAll.dc3, MainLoop.dc2
              BreakMainLoop.dc2, AttachXt.dc2, ScheduleX.dc2

Still to do:  This software would also be a logical place to handle signals
              and exceptional conditions on file descriptors.

Updates:      Apr  8, 1997: JPT, Document created.
              Apr 22, 1997: JPT, ScheduleX added.
              Aug  4, 1999: JPT, BreakMainLoop added.