1 /* 2 * Copyright (C) 2010 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 * @addtogroup Looper 19 * @{ 20 */ 21 22 /** 23 * @file looper.h 24 */ 25 26 #ifndef ANDROID_LOOPER_H 27 #define ANDROID_LOOPER_H 28 29 #include <sys/cdefs.h> 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 // This file may also be built on glibc or on Windows/MacOS libc's, so 36 // deprecated definitions are provided. 37 #if !defined(__REMOVED_IN) 38 #define __REMOVED_IN(__api_level, msg) __attribute__((__deprecated__(msg))) 39 #endif 40 41 struct ALooper; 42 /** 43 * ALooper 44 * 45 * A looper is the state tracking an event loop for a thread. 46 * Loopers do not define event structures or other such things; rather 47 * they are a lower-level facility to attach one or more discrete objects 48 * listening for an event. An "event" here is simply data available on 49 * a file descriptor: each attached object has an associated file descriptor, 50 * and waiting for "events" means (internally) polling on all of these file 51 * descriptors until one or more of them have data available. 52 * 53 * A thread can have only one ALooper associated with it. 54 */ 55 typedef struct ALooper ALooper; 56 57 /** 58 * Returns the looper associated with the calling thread, or NULL if 59 * there is not one. 60 */ 61 ALooper* ALooper_forThread(); 62 63 /** Option for for ALooper_prepare(). */ 64 enum { 65 /** 66 * This looper will accept calls to ALooper_addFd() that do not 67 * have a callback (that is provide NULL for the callback). In 68 * this case the caller of ALooper_pollOnce() or ALooper_pollAll() 69 * MUST check the return from these functions to discover when 70 * data is available on such fds and process it. 71 */ 72 ALOOPER_PREPARE_ALLOW_NON_CALLBACKS = 1<<0 73 }; 74 75 /** 76 * Prepares a looper associated with the calling thread, and returns it. 77 * If the thread already has a looper, it is returned. Otherwise, a new 78 * one is created, associated with the thread, and returned. 79 * 80 * The opts may be ALOOPER_PREPARE_ALLOW_NON_CALLBACKS or 0. 81 */ 82 ALooper* ALooper_prepare(int opts); 83 84 /** Result from ALooper_pollOnce() and ALooper_pollAll(). */ 85 enum { 86 /** 87 * The poll was awoken using wake() before the timeout expired 88 * and no callbacks were executed and no other file descriptors were ready. 89 */ 90 ALOOPER_POLL_WAKE = -1, 91 92 /** 93 * Result from ALooper_pollOnce() and ALooper_pollAll(): 94 * One or more callbacks were executed. 95 */ 96 ALOOPER_POLL_CALLBACK = -2, 97 98 /** 99 * Result from ALooper_pollOnce() and ALooper_pollAll(): 100 * The timeout expired. 101 */ 102 ALOOPER_POLL_TIMEOUT = -3, 103 104 /** 105 * Result from ALooper_pollOnce() and ALooper_pollAll(): 106 * An error occurred. 107 */ 108 ALOOPER_POLL_ERROR = -4, 109 }; 110 111 /** 112 * Acquire a reference on the given ALooper object. This prevents the object 113 * from being deleted until the reference is removed. This is only needed 114 * to safely hand an ALooper from one thread to another. 115 */ 116 void ALooper_acquire(ALooper* looper); 117 118 /** 119 * Remove a reference that was previously acquired with ALooper_acquire(). 120 */ 121 void ALooper_release(ALooper* looper); 122 123 /** 124 * Flags for file descriptor events that a looper can monitor. 125 * 126 * These flag bits can be combined to monitor multiple events at once. 127 */ 128 enum { 129 /** 130 * The file descriptor is available for read operations. 131 */ 132 ALOOPER_EVENT_INPUT = 1 << 0, 133 134 /** 135 * The file descriptor is available for write operations. 136 */ 137 ALOOPER_EVENT_OUTPUT = 1 << 1, 138 139 /** 140 * The file descriptor has encountered an error condition. 141 * 142 * The looper always sends notifications about errors; it is not necessary 143 * to specify this event flag in the requested event set. 144 */ 145 ALOOPER_EVENT_ERROR = 1 << 2, 146 147 /** 148 * The file descriptor was hung up. 149 * For example, indicates that the remote end of a pipe or socket was closed. 150 * 151 * The looper always sends notifications about hangups; it is not necessary 152 * to specify this event flag in the requested event set. 153 */ 154 ALOOPER_EVENT_HANGUP = 1 << 3, 155 156 /** 157 * The file descriptor is invalid. 158 * For example, the file descriptor was closed prematurely. 159 * 160 * The looper always sends notifications about invalid file descriptors; it is not necessary 161 * to specify this event flag in the requested event set. 162 */ 163 ALOOPER_EVENT_INVALID = 1 << 4, 164 }; 165 166 /** 167 * For callback-based event loops, this is the prototype of the function 168 * that is called when a file descriptor event occurs. 169 * It is given the file descriptor it is associated with, 170 * a bitmask of the poll events that were triggered (typically ALOOPER_EVENT_INPUT), 171 * and the data pointer that was originally supplied. 172 * 173 * Implementations should return 1 to continue receiving callbacks, or 0 174 * to have this file descriptor and callback unregistered from the looper. 175 */ 176 typedef int (*ALooper_callbackFunc)(int fd, int events, void* data); 177 178 /** 179 * Waits for events to be available, with optional timeout in milliseconds. 180 * Invokes callbacks for all file descriptors on which an event occurred. 181 * 182 * If the timeout is zero, returns immediately without blocking. 183 * If the timeout is negative, waits indefinitely until an event appears. 184 * 185 * Returns ALOOPER_POLL_WAKE if the poll was awoken using ALooper_wake() before 186 * the timeout expired and no callbacks were invoked and no other file 187 * descriptors were ready. **All return values may also imply 188 * ALOOPER_POLL_WAKE.** 189 * 190 * Returns ALOOPER_POLL_CALLBACK if one or more callbacks were invoked. The poll 191 * may also have been explicitly woken by ALooper_wake. 192 * 193 * Returns ALOOPER_POLL_TIMEOUT if there was no data before the given timeout 194 * expired. The poll may also have been explicitly woken by ALooper_wake. 195 * 196 * Returns ALOOPER_POLL_ERROR if the calling thread has no associated Looper or 197 * for unrecoverable internal errors. The poll may also have been explicitly 198 * woken by ALooper_wake. 199 * 200 * Returns a value >= 0 containing an identifier (the same identifier `ident` 201 * passed to ALooper_addFd()) if its file descriptor has data and it has no 202 * callback function (requiring the caller here to handle it). In this (and 203 * only this) case outFd, outEvents and outData will contain the poll events and 204 * data associated with the fd, otherwise they will be set to NULL. The poll may 205 * also have been explicitly woken by ALooper_wake. 206 * 207 * This method does not return until it has finished invoking the appropriate callbacks 208 * for all file descriptors that were signalled. 209 */ 210 int ALooper_pollOnce(int timeoutMillis, int* outFd, int* outEvents, void** outData); 211 212 /** 213 * Like ALooper_pollOnce(), but performs all pending callbacks until all 214 * data has been consumed or a file descriptor is available with no callback. 215 * This function will never return ALOOPER_POLL_CALLBACK. 216 * 217 * This API cannot be used safely, but a safe alternative exists (see below). As 218 * such, new builds will not be able to call this API and must migrate to the 219 * safe API. Binary compatibility is preserved to support already-compiled apps. 220 * 221 * \bug ALooper_pollAll will not wake in response to ALooper_wake calls if it 222 * also handles another event at the same time. 223 * 224 * \deprecated Calls to ALooper_pollAll should be replaced with 225 * ALooper_pollOnce. If you call ALooper_pollOnce in a loop, you *must* treat 226 * all return values as if they also indicate ALOOPER_POLL_WAKE. 227 */ 228 int ALooper_pollAll(int timeoutMillis, int* outFd, int* outEvents, void** outData) 229 __REMOVED_IN(1, 230 "ALooper_pollAll may ignore wakes. Use ALooper_pollOnce instead. See " 231 "The API documentation for more information"); 232 233 /** 234 * Wakes the poll asynchronously. 235 * 236 * This method can be called on any thread. 237 * This method returns immediately. 238 */ 239 void ALooper_wake(ALooper* looper); 240 241 /** 242 * Adds a new file descriptor to be polled by the looper. 243 * If the same file descriptor was previously added, it is replaced. 244 * 245 * "fd" is the file descriptor to be added. 246 * "ident" is an identifier for this event, which is returned from ALooper_pollOnce(). 247 * The identifier must be >= 0, or ALOOPER_POLL_CALLBACK if providing a non-NULL callback. 248 * "events" are the poll events to wake up on. Typically this is ALOOPER_EVENT_INPUT. 249 * "callback" is the function to call when there is an event on the file descriptor. 250 * "data" is a private data pointer to supply to the callback. 251 * 252 * There are two main uses of this function: 253 * 254 * (1) If "callback" is non-NULL, then this function will be called when there is 255 * data on the file descriptor. It should execute any events it has pending, 256 * appropriately reading from the file descriptor. The 'ident' is ignored in this case. 257 * 258 * (2) If "callback" is NULL, the 'ident' will be returned by ALooper_pollOnce 259 * when its file descriptor has data available, requiring the caller to take 260 * care of processing it. 261 * 262 * Returns 1 if the file descriptor was added or -1 if an error occurred. 263 * 264 * This method can be called on any thread. 265 * This method may block briefly if it needs to wake the poll. 266 */ 267 int ALooper_addFd(ALooper* looper, int fd, int ident, int events, 268 ALooper_callbackFunc callback, void* data); 269 270 /** 271 * Removes a previously added file descriptor from the looper. 272 * 273 * When this method returns, it is safe to close the file descriptor since the looper 274 * will no longer have a reference to it. However, it is possible for the callback to 275 * already be running or for it to run one last time if the file descriptor was already 276 * signalled. Calling code is responsible for ensuring that this case is safely handled. 277 * For example, if the callback takes care of removing itself during its own execution either 278 * by returning 0 or by calling this method, then it can be guaranteed to not be invoked 279 * again at any later time unless registered anew. 280 * 281 * Returns 1 if the file descriptor was removed, 0 if none was previously registered 282 * or -1 if an error occurred. 283 * 284 * This method can be called on any thread. 285 * This method may block briefly if it needs to wake the poll. 286 */ 287 int ALooper_removeFd(ALooper* looper, int fd); 288 289 #ifdef __cplusplus 290 }; 291 #endif 292 293 #endif // ANDROID_LOOPER_H 294 295 /** @} */ 296