1 /* $Id: endpoint.h 6648 2004-01-25 20:07:11Z rra $
3 ** The public interface to the Endpoint class.
5 ** Written by James Brister <brister@vix.com>
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.
13 ** We should add a way to cancel prepared read/write.
16 #if ! defined ( endpoint_h__ )
22 #define clearTimer(timerId) \
25 removeTimeout(timerId); \
32 /* These typedefs really lives in misc.h
34 *****************************************
36 * The basic (opqaue to the outside world) type.
38 * typedef struct endpoint_s *EndPoint ;
40 *****************************************
42 * The returns status of an IO request
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
51 * The completion callbacks are never called with the status IoIncomplete or
54 *****************************************
56 * typedef for function callback when IO is complete (or failed).
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}
62 * typedef void (*EndpRWCB) (EndPoint e, IoStatus i, Buffer b, void *d) ;
64 *****************************************
66 * typedef for function callback when a timer has gone off. D is the client
67 * data given to prepare{Sleep,Wake}
69 * typedef void (*EndpTCB) (void *d) ;
73 /* create a new EndPoint hooked up to the given file descriptor */
74 EndPoint newEndPoint (int fd) ;
76 /* shutdown the file descriptor and delete the endpoint. */
77 void delEndPoint (EndPoint endp) ;
79 /* return the file descriptor the endpoint is managing */
80 int endPointFd (EndPoint endp) ;
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.
92 int prepareRead (EndPoint endp,
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.
108 int prepareWrite (EndPoint endp,
114 /* cancel any outstanding reads. */
115 void cancelRead (EndPoint endp) ;
117 /* cancel any outstanding writes. */
118 void cancelWrite (EndPoint endp, char *buffer, size_t *len) ;
120 /* return true if prepareRead has been called, but not serviced yet */
121 bool readIsPending (EndPoint endp) ;
123 /* Request a wakeup at a given time. */
124 TimeoutId prepareWake (EndpTCB func,
128 /* return true if prepareWrite has been called, but not serviced yet */
129 bool writeIsPending (EndPoint endp) ;
131 /* Requests a wakeup TIMETOSLEEP seconds from now. */
132 TimeoutId prepareSleep (EndpTCB func,
136 /* Updates tid to wakeup TIMETOSLEEP seconds from now. */
137 TimeoutId updateSleep (TimeoutId tid,
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
145 void *addWorkCallback (EndPoint endp, EndpWorkCbk cbk, void *data) ;
147 void setSigHandler (int sig, void (*)(int)) ;
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) ;
154 /* start the select loop. An initial prepare(Read|Write) or a timeout
155 better have been setup. Doesn't return unless stopRun called */
158 /* stops the Run loop and makes Run() return */
159 void stopRun (void) ;
161 /* returns the errno the endpoint got. */
162 int endPointErrno (EndPoint endp) ;
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) ;
168 /* returns the fd of the main endpoint */
169 int getMainEndPointFd (void) ;
171 void freeTimeoutQueue (void) ;
173 int endpointConfigLoadCbk (void *data) ;
177 * kre's cool idea for reducing the number of times time() is called.
179 extern time_t PrivateTime;
181 #define theTime() (PrivateTime ? PrivateTime : time(&PrivateTime))
182 #define timePasses() (PrivateTime = 0)
184 #endif /* endpoint_h__ */