97f65b00 |
1 | /* -*-c-*- |
2 | * |
a3ddb778 |
3 | * $Id: sel.h,v 1.2 1999/05/15 10:33:32 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 $ |
a3ddb778 |
33 | * Revision 1.2 1999/05/15 10:33:32 mdw |
34 | * Fix copyright notices. |
35 | * |
97f65b00 |
36 | * Revision 1.1 1999/05/14 21:01:15 mdw |
37 | * Integrated `select' handling bits from the background resolver project. |
38 | * |
39 | */ |
40 | |
41 | #ifndef SEL_H |
42 | #define SEL_H |
43 | |
44 | #ifdef __cplusplus |
45 | extern "C" { |
46 | #endif |
47 | |
48 | /*----- Theory lesson -----------------------------------------------------* |
49 | * |
50 | * Things which are expecting to do I/O or go off at a certain time are |
51 | * called `selectors'. There are two types of selectors: `file selectors' |
52 | * wait patiently for a file to become readable or writable; `timeout |
53 | * selectors' wait for a certain amount of time to elapse. There is also a |
54 | * `multiplexor' which copes with managing all of this stuff. |
55 | * |
56 | * Multiplexors aren't actually very interesting. You initialize them with |
57 | * @sel_init@, and then add and remove selectors as you go. When you want to |
58 | * wait for something to happen, call @sel_select@. |
59 | * |
60 | * A file selector can *either* read *or* write. It can't do both. This is |
61 | * because you quite often want to read a socket but not write it; during |
62 | * those times you don't want to write, you just don't install a write |
63 | * selector. |
64 | * |
65 | * File selectors are called when their files are available for reading or |
66 | * writing as appropriate, and given their file descriptor, the state of the |
67 | * file, and a pointer that was registered along with the selector. |
68 | * |
69 | * File selectors are set up in two phases. First, they're `initialized' |
70 | * with @sel_initfile@. An initialized file selector doesn't do anything. |
71 | * It needs to be added to a multiplexor using `sel_addfile'. It can later |
72 | * be removed using `sel_rmfile'. You can carry on adding and removing as |
73 | * you wish. Just don't try adding it twice in a row. |
74 | * |
75 | * Timeout selectors are called at a certain time. (Actually, they're called |
76 | * *after* a certain time.) There's no separate initialization step with |
77 | * timouts: you just add them and they work. If you decide you don't want a |
78 | * timeout to go off, then you just remove it. (Adding and removing the |
79 | * *same* timeout isn't something you do very often. You usually use a |
80 | * different expiry time each time.) |
81 | */ |
82 | |
83 | /*----- Header files ------------------------------------------------------*/ |
84 | |
85 | #include <sys/types.h> |
86 | #include <sys/time.h> |
87 | #include <unistd.h> |
88 | |
89 | /*----- Data structures ---------------------------------------------------*/ |
90 | |
91 | /* --- Listening for a file --- */ |
92 | |
93 | typedef struct sel_file { |
94 | struct sel_file *next; |
95 | struct sel_file *prev; |
96 | struct sel_state *s; |
97 | int fd; |
98 | unsigned mode; |
99 | void (*func)(int /*fd*/, unsigned /*mode*/, void */*p*/); |
100 | void *p; |
101 | } sel_file; |
102 | |
103 | #define SEL_READ 0 |
104 | #define SEL_WRITE 1 |
105 | #define SEL_EXC 2 |
106 | #define SEL_MODES 3 |
107 | |
108 | /* --- Waiting for a timeout --- */ |
109 | |
110 | typedef struct sel_timer { |
111 | struct sel_timer *next; |
112 | struct sel_timer *prev; |
113 | struct timeval tv; |
114 | void (*func)(struct timeval *tv, void *p); |
115 | void *p; |
116 | } sel_timer; |
117 | |
118 | /* --- A multiplexer --- * |
119 | * |
120 | * The files are sorted in reverse order of file descriptor number; the |
121 | * timers are in normal order of occurrence. Thus, the interesting one |
122 | * is always at the front of the list. |
123 | */ |
124 | |
125 | typedef struct sel_state { |
126 | struct sel_file *files; |
127 | struct sel_timer *timers; |
128 | fd_set fd[SEL_MODES]; |
129 | struct timeval tv; |
130 | } sel_state; |
131 | |
132 | /*----- Functions provided ------------------------------------------------*/ |
133 | |
134 | /* --- @sel_init@ --- * |
135 | * |
136 | * Arguments: @sel_state *s@ = pointer to a state block to initialize |
137 | * |
138 | * Returns: --- |
139 | * |
140 | * Use: Initializes a select state block. |
141 | */ |
142 | |
143 | extern void sel_init(sel_state */*s*/); |
144 | |
145 | /* --- @sel_initfile@ --- * |
146 | * |
147 | * Arguments: @sel_state *s@ = select state to attach to |
148 | * @sel_file *f@ = pointer to a file block to initialize |
149 | * @int fd@ = the file descriptor to listen to |
150 | * @unsigned mode@ = what to listen for |
151 | * @void (*func)(int fd, unsigned mode, void *p)@ = handler |
152 | * @void *p@ = argument to pass to handler |
153 | * |
154 | * Returns: --- |
155 | * |
156 | * Use: Initializes a file block ready for use. The file block |
157 | * isn't added to the list of things to do until a call to |
158 | * @sel_addfile@. |
159 | */ |
160 | |
161 | extern void sel_initfile(sel_state */*s*/, sel_file */*f*/, |
162 | int /*fd*/, unsigned /*mode*/, |
163 | void (*/*func*/)(int /*fd*/, |
164 | unsigned /*mode*/, |
165 | void */*p*/), |
166 | void */*p*/); |
167 | |
168 | /* --- @sel_addfile@ --- * |
169 | * |
170 | * Arguments: @sel_file *f@ = pointer to a file block |
171 | * |
172 | * Returns: --- |
173 | * |
174 | * Use: Adds a file block into the list of things to listen to. |
175 | */ |
176 | |
177 | extern void sel_addfile(sel_file */*f*/); |
178 | |
179 | /* --- @sel_rmfile@ --- * |
180 | * |
181 | * Arguments: @sel_file *f@ = pointer to a file block |
182 | * |
183 | * Returns: --- |
184 | * |
185 | * Use: Removes a file block from the list of things to listen to. |
186 | */ |
187 | |
188 | extern void sel_rmfile(sel_file */*f*/); |
189 | |
190 | /* --- @sel_addtimer@ --- * |
191 | * |
192 | * Arguments: @sel_state *s@ = pointer to a state block |
193 | * @sel_timer *t@ = pointer to a timer block |
194 | * @struct timeval *tv@ = pointer to time to activate |
195 | * @void (*func)(struct timeval *tv, void *p)@ = handler |
196 | * @void *p@ = argument for handler function |
197 | * |
198 | * Returns: --- |
199 | * |
200 | * Use: Registers and sets up a timer. |
201 | */ |
202 | |
203 | extern void sel_addtimer(sel_state */*s*/, sel_timer */*t*/, |
204 | struct timeval */*tv*/, |
205 | void (*/*func*/)(struct timeval */*tv*/, |
206 | void */*p*/), |
207 | void */*p*/); |
208 | |
209 | /* --- @sel_rmtimer@ --- * |
210 | * |
211 | * Arguments: @sel_timer *t@ = pointer to timer block |
212 | * |
213 | * Returns: --- |
214 | * |
215 | * Use: Removes a timer from the list of timers. |
216 | */ |
217 | |
218 | extern void sel_rmtimer(sel_timer */*t*/); |
219 | |
220 | /* --- @sel_select@ --- * |
221 | * |
222 | * Arguments: @sel_state *s@ = pointer to state block |
223 | * |
224 | * Returns: Zero if all OK, -1 on error. |
225 | * |
226 | * Use: Does a @select@ call (or equivalent @poll@). |
227 | */ |
228 | |
229 | extern int sel_select(sel_state */*s*/); |
230 | |
231 | /*----- That's all, folks -------------------------------------------------*/ |
232 | |
233 | #ifdef __cplusplus |
234 | } |
235 | #endif |
236 | |
237 | #endif |