include/android/looper.h

   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 when a file descriptor event occurs.
 152  * It is given the file descriptor it is associated with,
 153  * a bitmask of the poll events that were triggered (typically ALOOPER_EVENT_INPUT),
 154  * and the data pointer that was originally supplied.
 155  *
 156  * Implementations should return 1 to continue receiving callbacks, or 0
 157  * to have this file descriptor and callback unregistered from the looper.
 158  */
 159 typedef int (*ALooper_callbackFunc)(int fd, int events, void* data);
 160
 161 /**
 162  * Waits for events to be available, with optional timeout in milliseconds.
 163  * Invokes callbacks for all file descriptors on which an event occurred.
 164  *
 165  * If the timeout is zero, returns immediately without blocking.
 166  * If the timeout is negative, waits indefinitely until an event appears.
 167  *
 168  * Returns ALOOPER_POLL_WAKE if the poll was awoken using wake() before
 169  * the timeout expired and no callbacks were invoked and no other file
 170  * descriptors were ready.
 171  *
 172  * Returns ALOOPER_POLL_CALLBACK if one or more callbacks were invoked.
 173  *
 174  * Returns ALOOPER_POLL_TIMEOUT if there was no data before the given
 175  * timeout expired.
 176  *
 177  * Returns ALOOPER_POLL_ERROR if an error occurred.
 178  *
 179  * Returns a value >= 0 containing an identifier if its file descriptor has data
 180  * and it has no callback function (requiring the caller here to handle it).
 181  * In this (and only this) case outFd, outEvents and outData will contain the poll
 182  * events and data associated with the fd, otherwise they will be set to NULL.
 183  *
 184  * This method does not return until it has finished invoking the appropriate callbacks
 185  * for all file descriptors that were signalled.
 186  */
 187 int ALooper_pollOnce(int timeoutMillis, int* outFd, int* outEvents, void** outData);
 188
 189 /**
 190  * Like ALooper_pollOnce(), but performs all pending callbacks until all
 191  * data has been consumed or a file descriptor is available with no callback.
 192  * This function will never return ALOOPER_POLL_CALLBACK.
 193  */
 194 int ALooper_pollAll(int timeoutMillis, int* outFd, int* outEvents, void** outData);
 195
 196 /**
 197  * Wakes the poll asynchronously.
 198  *
 199  * This method can be called on any thread.
 200  * This method returns immediately.
 201  */
 202 void ALooper_wake(ALooper* looper);
 203
 204 /**
 205  * Adds a new file descriptor to be polled by the looper.
 206  * If the same file descriptor was previously added, it is replaced.
 207  *
 208  * "fd" is the file descriptor to be added.
 209  * "ident" is an identifier for this event, which is returned from ALooper_pollOnce().
 210  * The identifier must be >= 0, or ALOOPER_POLL_CALLBACK if providing a non-NULL callback.
 211  * "events" are the poll events to wake up on.  Typically this is ALOOPER_EVENT_INPUT.
 212  * "callback" is the function to call when there is an event on the file descriptor.
 213  * "data" is a private data pointer to supply to the callback.
 214  *
 215  * There are two main uses of this function:
 216  *
 217  * (1) If "callback" is non-NULL, then this function will be called when there is
 218  * data on the file descriptor.  It should execute any events it has pending,
 219  * appropriately reading from the file descriptor.  The 'ident' is ignored in this case.
 220  *
 221  * (2) If "callback" is NULL, the 'ident' will be returned by ALooper_pollOnce
 222  * when its file descriptor has data available, requiring the caller to take
 223  * care of processing it.
 224  *
 225  * Returns 1 if the file descriptor was added or -1 if an error occurred.
 226  *
 227  * This method can be called on any thread.
 228  * This method may block briefly if it needs to wake the poll.
 229  */
 230 int ALooper_addFd(ALooper* looper, int fd, int ident, int events,
 231         ALooper_callbackFunc callback, void* data);
 232
 233 /**
 234  * Removes a previously added file descriptor from the looper.
 235  *
 236  * When this method returns, it is safe to close the file descriptor since the looper
 237  * will no longer have a reference to it.  However, it is possible for the callback to
 238  * already be running or for it to run one last time if the file descriptor was already
 239  * signalled.  Calling code is responsible for ensuring that this case is safely handled.
 240  * For example, if the callback takes care of removing itself during its own execution either
 241  * by returning 0 or by calling this method, then it can be guaranteed to not be invoked
 242  * again at any later time unless registered anew.
 243  *
 244  * Returns 1 if the file descriptor was removed, 0 if none was previously registered
 245  * or -1 if an error occurred.
 246  *
 247  * This method can be called on any thread.
 248  * This method may block briefly if it needs to wake the poll.
 249  */
 250 int ALooper_removeFd(ALooper* looper, int fd);
 251
 252 #ifdef __cplusplus
 253 };
 254 #endif
 255
 256 #endif // ANDROID_NATIVE_WINDOW_H