Commit | Line | Data |
---|---|---|
1e494cf4 JB |
1 | /* |
2 | * Copyright (C) 2007 The Android Open Source Project | |
3 | * | |
4 | * Licensed under the Apache License, Version 2.0 (the "License"); | |
5 | * you may not use this file except in compliance with the License. | |
6 | * You may obtain a copy of the License at | |
7 | * | |
8 | * http://www.apache.org/licenses/LICENSE-2.0 | |
9 | * | |
10 | * Unless required by applicable law or agreed to in writing, software | |
11 | * distributed under the License is distributed on an "AS IS" BASIS, | |
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
13 | * See the License for the specific language governing permissions and | |
14 | * limitations under the License. | |
15 | */ | |
16 | ||
17 | /** | |
18 | * Framework for multiplexing I/O. A selector manages a set of file | |
19 | * descriptors and calls out to user-provided callback functions to read and | |
20 | * write data and handle errors. | |
21 | */ | |
22 | ||
23 | #ifndef __SELECTOR_H | |
24 | #define __SELECTOR_H | |
25 | ||
26 | #ifdef __cplusplus | |
27 | extern "C" { | |
28 | #endif | |
29 | ||
30 | #include <stdbool.h> | |
31 | ||
32 | /** | |
33 | * Manages SelectableFds and invokes their callbacks at appropriate times. | |
34 | */ | |
35 | typedef struct Selector Selector; | |
36 | ||
37 | /** | |
38 | * A selectable descriptor. Contains callbacks which the selector can invoke | |
39 | * before calling select(), when the descriptor is readable or writable, and | |
40 | * when the descriptor contains out-of-band data. Simply set a callback to | |
41 | * NULL if you're not interested in that particular event. | |
42 | * | |
43 | * A selectable descriptor can indicate that it needs to be removed from the | |
44 | * selector by setting the 'remove' flag. The selector will remove the | |
45 | * descriptor at a later time and invoke the onRemove() callback. | |
46 | * | |
47 | * SelectableFd fields should only be modified from the selector loop. | |
48 | */ | |
49 | typedef struct SelectableFd SelectableFd; | |
50 | struct SelectableFd { | |
51 | ||
52 | /** The file descriptor itself. */ | |
53 | int fd; | |
54 | ||
55 | /** Pointer to user-specific data. Can be NULL. */ | |
56 | void* data; | |
57 | ||
58 | /** | |
59 | * Set this flag when you no longer wish to be selected. The selector | |
60 | * will invoke onRemove() when the descriptor is actually removed. | |
61 | */ | |
62 | bool remove; | |
63 | ||
64 | /** | |
65 | * Invoked by the selector before calling select. You can set up other | |
66 | * callbacks from here as necessary. | |
67 | */ | |
68 | void (*beforeSelect)(SelectableFd* self); | |
69 | ||
70 | /** | |
71 | * Invoked by the selector when the descriptor has data available. Set to | |
72 | * NULL to indicate that you're not interested in reading. | |
73 | */ | |
74 | void (*onReadable)(SelectableFd* self); | |
75 | ||
76 | /** | |
77 | * Invoked by the selector when the descriptor can accept data. Set to | |
78 | * NULL to indicate that you're not interested in writing. | |
79 | */ | |
80 | void (*onWritable)(SelectableFd* self); | |
81 | ||
82 | /** | |
83 | * Invoked by the selector when out-of-band (OOB) data is available. Set to | |
84 | * NULL to indicate that you're not interested in OOB data. | |
85 | */ | |
86 | void (*onExcept)(SelectableFd* self); | |
87 | ||
88 | /** | |
89 | * Invoked by the selector after the descriptor is removed from the | |
90 | * selector but before the selector frees the SelectableFd memory. | |
91 | */ | |
92 | void (*onRemove)(SelectableFd* self); | |
93 | ||
94 | /** | |
95 | * The selector which selected this fd. Set by the selector itself. | |
96 | */ | |
97 | Selector* selector; | |
98 | }; | |
99 | ||
100 | /** | |
101 | * Creates a new selector. | |
102 | */ | |
103 | Selector* selectorCreate(void); | |
104 | ||
105 | /** | |
106 | * Creates a new selectable fd, adds it to the given selector and returns a | |
107 | * pointer. Outside of 'selector' and 'fd', all fields are set to 0 or NULL | |
108 | * by default. | |
109 | * | |
110 | * The selectable fd should only be modified from the selector loop thread. | |
111 | */ | |
112 | SelectableFd* selectorAdd(Selector* selector, int fd); | |
113 | ||
114 | /** | |
115 | * Wakes up the selector even though no I/O events occurred. Use this | |
116 | * to indicate that you're ready to write to a descriptor. | |
117 | */ | |
118 | void selectorWakeUp(Selector* selector); | |
119 | ||
120 | /** | |
121 | * Loops continuously selecting file descriptors and firing events. | |
122 | * Does not return. | |
123 | */ | |
124 | void selectorLoop(Selector* selector); | |
125 | ||
126 | #ifdef __cplusplus | |
127 | } | |
128 | #endif | |
129 | ||
130 | #endif /* __SELECTOR_H */ |