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