Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 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 | #include <poll.h> |
| 22 | |
| 23 | #ifdef __cplusplus |
| 24 | extern "C" { |
| 25 | #endif |
| 26 | |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 27 | /** |
| 28 | * ALooper |
| 29 | * |
| 30 | * A looper is the state tracking an event loop for a thread. |
| 31 | * Loopers do not define event structures or other such things; rather |
| 32 | * they are a lower-level facility to attach one or more discrete objects |
| 33 | * listening for an event. An "event" here is simply data available on |
| 34 | * a file descriptor: each attached object has an associated file descriptor, |
| 35 | * and waiting for "events" means (internally) polling on all of these file |
| 36 | * descriptors until one or more of them have data available. |
| 37 | * |
| 38 | * A thread can have only one ALooper associated with it. |
| 39 | */ |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 40 | struct ALooper; |
| 41 | typedef struct ALooper ALooper; |
| 42 | |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 43 | /** |
| 44 | * For callback-based event loops, this is the prototype of the function |
| 45 | * that is called. It is given the file descriptor it is associated with, |
| 46 | * a bitmask of the poll events that were triggered (typically POLLIN), and |
| 47 | * the data pointer that was originally supplied. |
| 48 | * |
| 49 | * Implementations should return 1 to continue receiving callbacks, or 0 |
| 50 | * to have this file descriptor and callback unregistered from the looper. |
| 51 | */ |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 52 | typedef int ALooper_callbackFunc(int fd, int events, void* data); |
| 53 | |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 54 | /** |
| 55 | * Return the ALooper associated with the calling thread, or NULL if |
| 56 | * there is not one. |
| 57 | */ |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 58 | ALooper* ALooper_forThread(); |
| 59 | |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 60 | enum { |
| 61 | /** |
| 62 | * Option for ALooper_prepare: this ALooper will accept calls to |
| 63 | * ALooper_addFd() that do not have a callback (that is provide NULL |
| 64 | * for the callback). In this case the caller of ALooper_pollOnce() |
| 65 | * or ALooper_pollAll() MUST check the return from these functions to |
| 66 | * discover when data is available on such fds and process it. |
| 67 | */ |
| 68 | ALOOPER_PREPARE_ALLOW_NON_CALLBACKS = 1<<0 |
| 69 | }; |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 70 | |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 71 | /** |
| 72 | * Prepare an ALooper associated with the calling thread, and return it. |
| 73 | * If the thread already has an ALooper, it is returned. Otherwise, a new |
| 74 | * one is created, associated with the thread, and returned. |
| 75 | * |
| 76 | * The opts may be ALOOPER_PREPARE_ALLOW_NON_CALLBACKS or 0. |
| 77 | */ |
| 78 | ALooper* ALooper_prepare(int32_t opts); |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 79 | |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 80 | enum { |
| 81 | /** |
| 82 | * Result from ALooper_pollOnce() and ALooper_pollAll(): one or |
| 83 | * more callbacks were executed. |
| 84 | */ |
| 85 | ALOOPER_POLL_CALLBACK = -1, |
| 86 | |
| 87 | /** |
| 88 | * Result from ALooper_pollOnce() and ALooper_pollAll(): the |
| 89 | * timeout expired. |
| 90 | */ |
| 91 | ALOOPER_POLL_TIMEOUT = -2, |
| 92 | |
| 93 | /** |
| 94 | * Result from ALooper_pollOnce() and ALooper_pollAll(): an error |
| 95 | * occurred. |
| 96 | */ |
| 97 | ALOOPER_POLL_ERROR = -3, |
| 98 | }; |
| 99 | |
| 100 | /** |
| 101 | * Wait for events to be available, with optional timeout in milliseconds. |
| 102 | * Invokes callbacks for all file descriptors on which an event occurred. |
| 103 | * |
| 104 | * If the timeout is zero, returns immediately without blocking. |
| 105 | * If the timeout is negative, waits indefinitely until an event appears. |
| 106 | * |
| 107 | * Returns ALOOPER_POLL_CALLBACK if a callback was invoked. |
| 108 | * |
| 109 | * Returns ALOOPER_POLL_TIMEOUT if there was no data before the given |
| 110 | * timeout expired. |
| 111 | * |
| 112 | * Returns ALOPER_POLL_ERROR if an error occurred. |
| 113 | * |
| 114 | * Returns a value >= 0 containing a file descriptor if it has data |
| 115 | * and it has no callback function (requiring the caller here to handle it). |
| 116 | * In this (and only this) case outEvents and outData will contain the poll |
| 117 | * events and data associated with the fd. |
| 118 | * |
| 119 | * This method does not return until it has finished invoking the appropriate callbacks |
| 120 | * for all file descriptors that were signalled. |
| 121 | */ |
| 122 | int32_t ALooper_pollOnce(int timeoutMillis, int* outEvents, void** outData); |
| 123 | |
| 124 | /** |
| 125 | * Like ALooper_pollOnce(), but performs all pending callbacks until all |
| 126 | * data has been consumed or a file descriptor is available with no callback. |
| 127 | * This function will never return ALOOPER_POLL_CALLBACK. |
| 128 | */ |
| 129 | int32_t ALooper_pollAll(int timeoutMillis, int* outEvents, void** outData); |
| 130 | |
| 131 | /** |
| 132 | * Acquire a reference on the given ALooper object. This prevents the object |
| 133 | * from being deleted until the reference is removed. This is only needed |
| 134 | * to safely hand an ALooper from one thread to another. |
| 135 | */ |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 136 | void ALooper_acquire(ALooper* looper); |
| 137 | |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 138 | /** |
| 139 | * Remove a reference that was previously acquired with ALooper_acquire(). |
| 140 | */ |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 141 | void ALooper_release(ALooper* looper); |
| 142 | |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 143 | /** |
| 144 | * Add a new file descriptor to be polled by the looper. If the same file |
| 145 | * descriptor was previously added, it is replaced. |
| 146 | * |
| 147 | * "fd" is the file descriptor to be added. |
| 148 | * "events" are the poll events to wake up on. Typically this is POLLIN. |
| 149 | * "callback" is the function to call when there is an event on the file |
| 150 | * descriptor. |
| 151 | * "id" is an identifier to associated with this file descriptor, or 0. |
| 152 | * "data" is a private data pointer to supply to the callback. |
| 153 | * |
| 154 | * There are two main uses of this function: |
| 155 | * |
| 156 | * (1) If "callback" is non-NULL, then |
| 157 | * this function will be called when there is data on the file descriptor. It |
| 158 | * should execute any events it has pending, appropriately reading from the |
| 159 | * file descriptor. |
| 160 | * |
| 161 | * (2) If "callback" is NULL, the fd will be returned by ALooper_pollOnce |
| 162 | * when it has data available, requiring the caller to take care of processing |
| 163 | * it. |
| 164 | */ |
| 165 | void ALooper_addFd(ALooper* looper, int fd, int events, |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 166 | ALooper_callbackFunc* callback, void* data); |
| 167 | |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 168 | /** |
| 169 | * Remove a previously added file descriptor from the looper. |
| 170 | */ |
| 171 | int32_t ALooper_removeFd(ALooper* looper, int fd); |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 172 | |
| 173 | #ifdef __cplusplus |
| 174 | }; |
| 175 | #endif |
| 176 | |
| 177 | #endif // ANDROID_NATIVE_WINDOW_H |