blob: 24e3967b9bebfd28d016423ddc37110b727819da [file] [log] [blame]
Dianne Hackborn68267412010-07-02 18:52:01 -07001/*
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
Dianne Hackborn68267412010-07-02 18:52:01 -070021#ifdef __cplusplus
22extern "C" {
23#endif
24
Dianne Hackborn85448bb2010-07-07 14:27:31 -070025/**
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 */
Dianne Hackborn68267412010-07-02 18:52:01 -070038struct ALooper;
39typedef struct ALooper ALooper;
40
Dianne Hackborn85448bb2010-07-07 14:27:31 -070041/**
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070042 * Returns the looper associated with the calling thread, or NULL if
Dianne Hackborn85448bb2010-07-07 14:27:31 -070043 * there is not one.
44 */
Dianne Hackborn68267412010-07-02 18:52:01 -070045ALooper* ALooper_forThread();
46
Dianne Hackborn85448bb2010-07-07 14:27:31 -070047enum {
48 /**
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070049 * Option for ALooper_prepare: this looper will accept calls to
Dianne Hackborn85448bb2010-07-07 14:27:31 -070050 * 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};
Dianne Hackborn68267412010-07-02 18:52:01 -070057
Dianne Hackborn85448bb2010-07-07 14:27:31 -070058/**
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070059 * 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
Dianne Hackborn85448bb2010-07-07 14:27:31 -070061 * one is created, associated with the thread, and returned.
62 *
63 * The opts may be ALOOPER_PREPARE_ALLOW_NON_CALLBACKS or 0.
64 */
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070065ALooper* ALooper_prepare(int opts);
Dianne Hackborn68267412010-07-02 18:52:01 -070066
Dianne Hackborn85448bb2010-07-07 14:27:31 -070067enum {
68 /**
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070069 * 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.
Dianne Hackborn85448bb2010-07-07 14:27:31 -070072 */
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070073 ALOOPER_POLL_WAKE = -1,
74
Dianne Hackborn85448bb2010-07-07 14:27:31 -070075 /**
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070076 * Result from ALooper_pollOnce() and ALooper_pollAll():
77 * One or more callbacks were executed.
Dianne Hackborn85448bb2010-07-07 14:27:31 -070078 */
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070079 ALOOPER_POLL_CALLBACK = -2,
80
Dianne Hackborn85448bb2010-07-07 14:27:31 -070081 /**
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070082 * Result from ALooper_pollOnce() and ALooper_pollAll():
83 * The timeout expired.
Dianne Hackborn85448bb2010-07-07 14:27:31 -070084 */
Jeff Brown4fe6c3e2010-09-13 23:17:30 -070085 ALOOPER_POLL_TIMEOUT = -3,
86
87 /**
88 * Result from ALooper_pollOnce() and ALooper_pollAll():
89 * An error occurred.
90 */
91 ALOOPER_POLL_ERROR = -4,
Dianne Hackborn85448bb2010-07-07 14:27:31 -070092};
93
94/**
Dianne Hackborn85448bb2010-07-07 14:27:31 -070095 * 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 */
Dianne Hackborn68267412010-07-02 18:52:01 -070099void ALooper_acquire(ALooper* looper);
100
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700101/**
102 * Remove a reference that was previously acquired with ALooper_acquire().
103 */
Dianne Hackborn68267412010-07-02 18:52:01 -0700104void ALooper_release(ALooper* looper);
105
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700106/**
Jeff Brown4fe6c3e2010-09-13 23:17:30 -0700107 * 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 */
111enum {
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,
Jeff Brown415d8c32010-10-05 15:35:37 -0700138
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,
Jeff Brown4fe6c3e2010-09-13 23:17:30 -0700147};
148
149/**
150 * For callback-based event loops, this is the prototype of the function
Jeff Brown05dc66a2011-03-02 14:41:58 -0800151 * that is called when a file descriptor event occurs.
152 * It is given the file descriptor it is associated with,
Jeff Brown4fe6c3e2010-09-13 23:17:30 -0700153 * 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 */
159typedef 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 */
187int 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 */
194int 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 */
202void 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.
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700207 *
208 * "fd" is the file descriptor to be added.
Jeff Brown4fe6c3e2010-09-13 23:17:30 -0700209 * "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.
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700213 * "data" is a private data pointer to supply to the callback.
214 *
215 * There are two main uses of this function:
216 *
Jeff Brown4fe6c3e2010-09-13 23:17:30 -0700217 * (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.
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700220 *
Dianne Hackborn42c03e52010-09-07 15:28:30 -0700221 * (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.
Jeff Brown4fe6c3e2010-09-13 23:17:30 -0700224 *
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.
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700229 */
Jeff Brown4fe6c3e2010-09-13 23:17:30 -0700230int ALooper_addFd(ALooper* looper, int fd, int ident, int events,
231 ALooper_callbackFunc callback, void* data);
Dianne Hackborn68267412010-07-02 18:52:01 -0700232
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700233/**
Jeff Brown4fe6c3e2010-09-13 23:17:30 -0700234 * 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.
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700249 */
Jeff Brown4fe6c3e2010-09-13 23:17:30 -0700250int ALooper_removeFd(ALooper* looper, int fd);
Dianne Hackborn68267412010-07-02 18:52:01 -0700251
252#ifdef __cplusplus
253};
254#endif
255
256#endif // ANDROID_NATIVE_WINDOW_H