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 */ 131