97f65b00 |
1 | /* -*-c-*- |
2 | * |
4790f418 |
3 | * $Id: sel.h,v 1.9 2003/05/17 10:34:04 mdw Exp $ |
97f65b00 |
4 | * |
5 | * I/O multiplexing support |
6 | * |
a3ddb778 |
7 | * (c) 1999 Straylight/Edgeware |
97f65b00 |
8 | */ |
9 | |
10 | /*----- Licensing notice --------------------------------------------------* |
11 | * |
12 | * This file is part of the mLib utilities library. |
13 | * |
14 | * mLib is free software; you can redistribute it and/or modify |
15 | * it under the terms of the GNU Library General Public License as |
16 | * published by the Free Software Foundation; either version 2 of the |
17 | * License, or (at your option) any later version. |
18 | * |
19 | * mLib is distributed in the hope that it will be useful, |
20 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
21 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22 | * GNU Library General Public License for more details. |
23 | * |
24 | * You should have received a copy of the GNU Library General Public |
25 | * License along with mLib; if not, write to the Free |
26 | * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, |
27 | * MA 02111-1307, USA. |
28 | */ |
29 | |
30 | /*----- Revision history --------------------------------------------------* |
31 | * |
32 | * $Log: sel.h,v $ |
4790f418 |
33 | * Revision 1.9 2003/05/17 10:34:04 mdw |
34 | * Tidying and bugfixing. |
35 | * |
0a2a19b4 |
36 | * Revision 1.8 2001/06/22 19:35:58 mdw |
37 | * Fix a large number of bugs. |
38 | * |
c6e0eaf0 |
39 | * Revision 1.7 1999/12/10 23:42:04 mdw |
40 | * Change header file guard names. |
41 | * |
1101f87a |
42 | * Revision 1.6 1999/08/31 17:42:22 mdw |
43 | * New function `sel_force' to force a descriptor to be `selected'. |
44 | * |
1226c514 |
45 | * Revision 1.5 1999/08/19 18:30:26 mdw |
46 | * Implement hooks for foreign select-using systems (currently not well |
47 | * tested). |
48 | * |
d6232a7a |
49 | * Revision 1.4 1999/05/22 13:39:15 mdw |
50 | * Change spelling of `multiplexor'. ;-) |
51 | * |
e32dabae |
52 | * Revision 1.3 1999/05/17 20:36:36 mdw |
53 | * Make the selector type symbols an enumeration rather than a bunch of |
54 | * #defines. |
55 | * |
a3ddb778 |
56 | * Revision 1.2 1999/05/15 10:33:32 mdw |
57 | * Fix copyright notices. |
58 | * |
97f65b00 |
59 | * Revision 1.1 1999/05/14 21:01:15 mdw |
60 | * Integrated `select' handling bits from the background resolver project. |
61 | * |
62 | */ |
63 | |
c6e0eaf0 |
64 | #ifndef MLIB_SEL_H |
65 | #define MLIB_SEL_H |
97f65b00 |
66 | |
67 | #ifdef __cplusplus |
68 | extern "C" { |
69 | #endif |
70 | |
71 | /*----- Theory lesson -----------------------------------------------------* |
72 | * |
73 | * Things which are expecting to do I/O or go off at a certain time are |
74 | * called `selectors'. There are two types of selectors: `file selectors' |
75 | * wait patiently for a file to become readable or writable; `timeout |
76 | * selectors' wait for a certain amount of time to elapse. There is also a |
77 | * `multiplexor' which copes with managing all of this stuff. |
78 | * |
79 | * Multiplexors aren't actually very interesting. You initialize them with |
80 | * @sel_init@, and then add and remove selectors as you go. When you want to |
81 | * wait for something to happen, call @sel_select@. |
82 | * |
83 | * A file selector can *either* read *or* write. It can't do both. This is |
84 | * because you quite often want to read a socket but not write it; during |
85 | * those times you don't want to write, you just don't install a write |
86 | * selector. |
87 | * |
88 | * File selectors are called when their files are available for reading or |
89 | * writing as appropriate, and given their file descriptor, the state of the |
90 | * file, and a pointer that was registered along with the selector. |
91 | * |
92 | * File selectors are set up in two phases. First, they're `initialized' |
93 | * with @sel_initfile@. An initialized file selector doesn't do anything. |
94 | * It needs to be added to a multiplexor using `sel_addfile'. It can later |
95 | * be removed using `sel_rmfile'. You can carry on adding and removing as |
96 | * you wish. Just don't try adding it twice in a row. |
97 | * |
98 | * Timeout selectors are called at a certain time. (Actually, they're called |
99 | * *after* a certain time.) There's no separate initialization step with |
100 | * timouts: you just add them and they work. If you decide you don't want a |
101 | * timeout to go off, then you just remove it. (Adding and removing the |
102 | * *same* timeout isn't something you do very often. You usually use a |
103 | * different expiry time each time.) |
104 | */ |
105 | |
106 | /*----- Header files ------------------------------------------------------*/ |
107 | |
108 | #include <sys/types.h> |
109 | #include <sys/time.h> |
110 | #include <unistd.h> |
111 | |
112 | /*----- Data structures ---------------------------------------------------*/ |
113 | |
1226c514 |
114 | /* --- A multiplexor --- * |
115 | * |
116 | * The files are sorted in reverse order of file descriptor number; the |
117 | * timers are in normal order of occurrence. Thus, the interesting one |
118 | * is always at the front of the list. |
119 | */ |
120 | |
121 | enum { |
1101f87a |
122 | SEL_READ, /* File is ready to read */ |
123 | SEL_WRITE, /* File is ready to write */ |
124 | SEL_EXC, /* Something odd has happened */ |
125 | SEL_MODES /* Number of modes available */ |
1226c514 |
126 | }; |
127 | |
128 | typedef struct sel_state { |
1101f87a |
129 | struct sel_file *files[SEL_MODES]; /* Lists of interesting files */ |
130 | struct sel_timer *timers; /* List of timers */ |
131 | struct sel_hook *hooks; /* List of hook functions applied */ |
132 | fd_set fd[SEL_MODES]; /* Quick reference table for files */ |
133 | struct sel_args *args; /* Pointer to arguments */ |
1226c514 |
134 | } sel_state; |
135 | |
97f65b00 |
136 | /* --- Listening for a file --- */ |
137 | |
138 | typedef struct sel_file { |
1101f87a |
139 | struct sel_file *next; /* Next file in the list */ |
4790f418 |
140 | struct sel_file **prev; /* Previous file in the list */ |
1101f87a |
141 | struct sel_state *s; /* Pointer to select multiplexor */ |
142 | int fd; /* File descriptor */ |
143 | unsigned mode; /* Interesting event for file */ |
144 | void (*func)(int /*fd*/, unsigned /*mode*/, void */*p*/); /* Handler */ |
145 | void *p; /* Argument for the handler */ |
0a2a19b4 |
146 | struct sel_pendfile *pend; /* Pending file information */ |
97f65b00 |
147 | } sel_file; |
148 | |
97f65b00 |
149 | /* --- Waiting for a timeout --- */ |
150 | |
151 | typedef struct sel_timer { |
1101f87a |
152 | struct sel_timer *next; /* Next timer in the list */ |
4790f418 |
153 | struct sel_timer **prev; /* Previous timer in the list */ |
1101f87a |
154 | struct timeval tv; /* Real time when timer should go */ |
155 | void (*func)(struct timeval */*tv*/, void */*p*/); /* Handler function */ |
156 | void *p; /* Argument for the handler */ |
0a2a19b4 |
157 | struct sel_pendtimer *pend; /* Pending timer information */ |
97f65b00 |
158 | } sel_timer; |
159 | |
1226c514 |
160 | /* --- A select argument block --- */ |
161 | |
162 | typedef struct sel_args { |
1101f87a |
163 | int maxfd; /* Highest-numbered file */ |
164 | fd_set fd[SEL_MODES]; /* Bit flags for all the files */ |
165 | struct timeval tv, *tvp; /* Time to return */ |
166 | struct timeval now; /* Current time */ |
1226c514 |
167 | } sel_args; |
168 | |
169 | /* --- A selector hook --- * |
97f65b00 |
170 | * |
1226c514 |
171 | * The hooks are called (in arbitrary order) on each select. |
97f65b00 |
172 | */ |
173 | |
1226c514 |
174 | typedef void (*sel_hookfn)(sel_state */*s*/, |
175 | sel_args */*a*/, |
176 | void */*p*/); |
177 | |
178 | typedef struct sel_hook { |
1101f87a |
179 | struct sel_hook *next; /* Next hook in the list */ |
4790f418 |
180 | struct sel_hook **prev; /* Previous hook in the list */ |
1101f87a |
181 | sel_hookfn before, after; /* Hook functions */ |
182 | void *p; /* Argument for the hook functions */ |
1226c514 |
183 | } sel_hook; |
97f65b00 |
184 | |
185 | /*----- Functions provided ------------------------------------------------*/ |
186 | |
187 | /* --- @sel_init@ --- * |
188 | * |
189 | * Arguments: @sel_state *s@ = pointer to a state block to initialize |
190 | * |
191 | * Returns: --- |
192 | * |
193 | * Use: Initializes a select state block. |
194 | */ |
195 | |
196 | extern void sel_init(sel_state */*s*/); |
197 | |
198 | /* --- @sel_initfile@ --- * |
199 | * |
200 | * Arguments: @sel_state *s@ = select state to attach to |
201 | * @sel_file *f@ = pointer to a file block to initialize |
202 | * @int fd@ = the file descriptor to listen to |
203 | * @unsigned mode@ = what to listen for |
204 | * @void (*func)(int fd, unsigned mode, void *p)@ = handler |
205 | * @void *p@ = argument to pass to handler |
206 | * |
207 | * Returns: --- |
208 | * |
209 | * Use: Initializes a file block ready for use. The file block |
210 | * isn't added to the list of things to do until a call to |
211 | * @sel_addfile@. |
212 | */ |
213 | |
214 | extern void sel_initfile(sel_state */*s*/, sel_file */*f*/, |
215 | int /*fd*/, unsigned /*mode*/, |
216 | void (*/*func*/)(int /*fd*/, |
217 | unsigned /*mode*/, |
218 | void */*p*/), |
219 | void */*p*/); |
220 | |
221 | /* --- @sel_addfile@ --- * |
222 | * |
223 | * Arguments: @sel_file *f@ = pointer to a file block |
224 | * |
225 | * Returns: --- |
226 | * |
227 | * Use: Adds a file block into the list of things to listen to. |
228 | */ |
229 | |
230 | extern void sel_addfile(sel_file */*f*/); |
231 | |
232 | /* --- @sel_rmfile@ --- * |
233 | * |
234 | * Arguments: @sel_file *f@ = pointer to a file block |
235 | * |
236 | * Returns: --- |
237 | * |
238 | * Use: Removes a file block from the list of things to listen to. |
239 | */ |
240 | |
241 | extern void sel_rmfile(sel_file */*f*/); |
242 | |
1101f87a |
243 | /* --- @sel_force@ --- * |
244 | * |
245 | * Arguments: @sel_file *f@ = pointer to file selector |
246 | * |
247 | * Returns: --- |
248 | * |
249 | * Use: Forces a file selector to be considered ready. This is only |
250 | * useful during a call to @sel_select@. Of particular use is |
251 | * forcing a write selector when there's something interesting |
252 | * ready for it. |
253 | */ |
254 | |
255 | extern void sel_force(sel_file */*f*/); |
256 | |
97f65b00 |
257 | /* --- @sel_addtimer@ --- * |
258 | * |
259 | * Arguments: @sel_state *s@ = pointer to a state block |
260 | * @sel_timer *t@ = pointer to a timer block |
261 | * @struct timeval *tv@ = pointer to time to activate |
97f65b00 |
262 | * @void *p@ = argument for handler function |
263 | * |
264 | * Returns: --- |
265 | * |
266 | * Use: Registers and sets up a timer. |
267 | */ |
268 | |
269 | extern void sel_addtimer(sel_state */*s*/, sel_timer */*t*/, |
270 | struct timeval */*tv*/, |
271 | void (*/*func*/)(struct timeval */*tv*/, |
272 | void */*p*/), |
273 | void */*p*/); |
274 | |
275 | /* --- @sel_rmtimer@ --- * |
276 | * |
277 | * Arguments: @sel_timer *t@ = pointer to timer block |
278 | * |
279 | * Returns: --- |
280 | * |
281 | * Use: Removes a timer from the list of timers. |
282 | */ |
283 | |
284 | extern void sel_rmtimer(sel_timer */*t*/); |
285 | |
1226c514 |
286 | /* --- @sel_addhook@ --- * |
287 | * |
288 | * Arguments: @sel_state *s@ = pointer to state block |
289 | * @sel_hook *h@ = pointer to hook block |
290 | * @sel_hookfn before, after@ = hook functions |
291 | * @void *p@ = pointer argument to pass to hook functions |
292 | * |
293 | * Returns: --- |
294 | * |
295 | * Use: Registers hook functions to be called on each select call. |
296 | */ |
297 | |
298 | extern void sel_addhook(sel_state */*s*/, sel_hook */*h*/, |
299 | sel_hookfn /*before*/, sel_hookfn /*after*/, |
300 | void */*p*/); |
301 | |
302 | /* --- @sel_rmhook@ --- * |
303 | * |
304 | * Arguments: @sel_hook *h@ = pointer to hook block |
305 | * |
306 | * Returns: --- |
307 | * |
308 | * Use: Removes hook functions. |
309 | */ |
310 | |
311 | extern void sel_rmhook(sel_hook */*h*/); |
312 | |
313 | /* --- @sel_fdmerge@ --- * |
314 | * |
315 | * Arguments: @fd_set *dest@ = destination FD set |
316 | * @fd_set *fd@ = pointer to set to merge |
317 | * @int maxfd@ = highest numbered descriptor in @fd@ + 1 |
318 | * |
319 | * Returns: Actual highest numbered descriptor. |
320 | * |
321 | * Use: Merges file descriptor sets, and returns an accurate @maxfd@ |
322 | * value. |
323 | */ |
324 | |
325 | extern int sel_fdmerge(fd_set */*dest*/, fd_set */*fd*/, int /*maxfd*/); |
326 | |
97f65b00 |
327 | /* --- @sel_select@ --- * |
328 | * |
329 | * Arguments: @sel_state *s@ = pointer to state block |
330 | * |
331 | * Returns: Zero if all OK, -1 on error. |
332 | * |
333 | * Use: Does a @select@ call (or equivalent @poll@). |
334 | */ |
335 | |
336 | extern int sel_select(sel_state */*s*/); |
337 | |
338 | /*----- That's all, folks -------------------------------------------------*/ |
339 | |
340 | #ifdef __cplusplus |
341 | } |
342 | #endif |
343 | |
344 | #endif |