innfeed/endpoint.h

   1 /*  $Id: endpoint.h 6648 2004-01-25 20:07:11Z rra $
   2 **
   3 **  The public interface to the Endpoint class.
   4 **
   5 **  Written by James Brister <brister@vix.com>
   6 **
   7 **  The EndPoint objects are encapsulations of file descriptors that normally
   8 **  do blocking i/o (i.e. NOT fd's hooked to a disk file).  The EndPoint class
   9 **  provides methods for reqesting read/writes to happen when next possible
  10 **  and for the requestor to be notified when the i/o is complete (or failed
  11 **  for some reason).  Facilities for timeout notifications are provided too.
  12 **
  13 **  We should add a way to cancel prepared read/write.
  14 */
  15
  16 #if ! defined ( endpoint_h__ )
  17 #define endpoint_h__
  18
  19 #include "misc.h"
  20
  21
  22 #define clearTimer(timerId) \
  23         do {\
  24                 if((timerId)!=0) { \
  25                         removeTimeout(timerId); \
  26                         timerId=0; \
  27                 } \
  28         }while(0)
  29
  30
  31
  32 /* These typedefs really lives in misc.h
  33  *
  34  *****************************************
  35  *
  36  * The basic (opqaue to the outside world) type.
  37  *
  38  *      typedef struct endpoint_s *EndPoint ;
  39  *
  40  *****************************************
  41  *
  42  * The returns status of an IO request
  43  *
  44  *      typedef enum {
  45  *          IoDone,                     i/o completed successfully
  46  *          IoIncomplete,               i/o still got more to read/write
  47  *          IoProgress,                 i/o still got more to read/write
  48  *          IoFailed                    i/o failed
  49  *      } IoStatus ;
  50  *
  51  * The completion callbacks are never called with the status IoIncomplete or
  52  * IoProgress.
  53  *
  54  *****************************************
  55  *
  56  * typedef for function callback when IO is complete (or failed).
  57  *      E is the EndPoint
  58  *      I is the status of the IO
  59  *      B is the buffer the IO was to read to or write from.
  60  *      D is the client data originally given to prepare{Write,Read}
  61  *
  62  * typedef void (*EndpRWCB) (EndPoint e, IoStatus i, Buffer b, void *d) ;
  63  *
  64  *****************************************
  65  *
  66  * typedef for function callback when a timer has gone off. D is the client
  67  * data given to prepare{Sleep,Wake}
  68  *
  69  * typedef void (*EndpTCB) (void *d) ;
  70  *
  71  */
  72
  73 /* create a new EndPoint hooked up to the given file descriptor */
  74 EndPoint newEndPoint (int fd) ;
  75
  76 /* shutdown the file descriptor and delete the endpoint. */
  77 void delEndPoint (EndPoint endp) ;
  78
  79 /* return the file descriptor the endpoint is managing */
  80 int endPointFd (EndPoint endp) ;
  81
  82 /* Request a read when available. Reads MINLEN bytes into the
  83  * buffers in BUFFS. BUFFS is an array of Buffers, the last of which
  84  * must be NULL. Note that ownership of BUFFS is never asserted, but
  85  * the ownership of the Buffers in it is. So if an EndPoint is
  86  * deleted while a read is pending the Buffers will be released, but
  87  * the array won't be. If MINLEN is 0 then the buffers must be
  88  * filled. The FUNC function gets called when the read is
  89  * complete. CLIENTDATA is simply passed back to the
  90  * callback. Returns non-zero if can be scheduled for processing.
  91  */
  92 int prepareRead (EndPoint endp,
  93                  Buffer *buffs,
  94                  EndpRWCB func,
  95                  void *clientData,
  96                  int minlen) ;
  97
  98 /* Request a write when possible. All the data in the buffers in
  99  * BUFFS will be written out the endpoint. BUFFS is a NULL
 100  * terminated array of Buffers. See prepareWrite for a discussion on
 101  * the ownership of BUFFS and the Buffers inside BUFFS. The PROGRESS
 102  * callback function will be called and the CLIENTDATA value will be
 103  * passed through to it whenever any data is written except for the
 104  * final write.  The DONE callback function will be called and the
 105  * CLIENTDATA value will be passed through to it after the final write.
 106  * Returns non-zero if scheduled succesfully.
 107  */
 108 int prepareWrite (EndPoint endp,
 109                   Buffer *buffs,
 110                   EndpRWCB progress,
 111                   EndpRWCB done,
 112                   void *clientData) ;
 113
 114 /* cancel any outstanding reads. */
 115 void cancelRead (EndPoint endp) ;
 116
 117 /* cancel any outstanding writes. */
 118 void cancelWrite (EndPoint endp, char *buffer, size_t *len) ;
 119
 120 /* return true if prepareRead has been called, but not serviced yet */
 121 bool readIsPending (EndPoint endp) ;
 122
 123 /* Request a wakeup at a given time. */
 124 TimeoutId prepareWake (EndpTCB func,
 125                        time_t timeToWake,
 126                        void *clientData) ;
 127
 128 /* return true if prepareWrite has been called, but not serviced yet */
 129 bool writeIsPending (EndPoint endp) ;
 130
 131 /* Requests a wakeup TIMETOSLEEP seconds from now. */
 132 TimeoutId prepareSleep (EndpTCB func,
 133                         int timeToSleep,
 134                         void *clientData) ;
 135
 136 /* Updates tid to wakeup TIMETOSLEEP seconds from now. */
 137 TimeoutId updateSleep (TimeoutId tid,
 138                        EndpTCB func,
 139                        int timeToSleep,
 140                        void *clientData) ;
 141
 142   /* Set up a function to be called whenever the endpoint's file descriptor
 143      is NOT ready. This is called after all other fd-ready endpoints have
 144      been serviced. */
 145 void *addWorkCallback (EndPoint endp, EndpWorkCbk cbk, void *data) ;
 146
 147 void setSigHandler (int sig, void (*)(int)) ;
 148
 149 /* remove the timeout that was previously requested. Retuesn true if
 150    succesfully removed, false otherwise. 0 is a legal parameter value, in
 151    which case the function simply returns. */
 152 bool removeTimeout (TimeoutId tid) ;
 153
 154 /* start the select loop. An initial prepare(Read|Write) or a timeout
 155    better have been setup. Doesn't return unless stopRun called */
 156 void Run (void) ;
 157
 158 /* stops the Run loop and makes Run() return */
 159 void stopRun (void) ;
 160
 161 /* returns the errno the endpoint got. */
 162 int endPointErrno (EndPoint endp) ;
 163
 164 /* Tell the EndPoint class that the given EndPoint should always be
 165    considered first for servicing (i.e. the EndPoint connectied to innd) */
 166 void setMainEndPoint (EndPoint endp) ;
 167
 168 /* returns the fd of the main endpoint */
 169 int getMainEndPointFd (void) ;
 170
 171 void freeTimeoutQueue (void) ;
 172
 173 int endpointConfigLoadCbk (void *data) ;
 174
 175
 176 /*
 177  * kre's cool idea for reducing the number of times time() is called.
 178  */
 179 extern time_t  PrivateTime;
 180
 181 #define theTime()       (PrivateTime ? PrivateTime : time(&PrivateTime))
 182 #define timePasses()    (PrivateTime = 0)
 183
 184 #endif /* endpoint_h__ */