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#ifndef UTILS_LOOPER_H
18#define UTILS_LOOPER_H
19
20#include <utils/threads.h>
21#include <utils/RefBase.h>
22#include <utils/KeyedVector.h>
23#include <utils/Timers.h>
24
25#include <sys/epoll.h>
26
27namespace android {
28
29/*
30 * NOTE: Since Looper is used to implement the NDK ALooper, the Looper
31 * enums and the signature of Looper_callbackFunc need to align with
32 * that implementation.
33 */
34
35/**
36 * For callback-based event loops, this is the prototype of the function
37 * that is called when a file descriptor event occurs.
38 * It is given the file descriptor it is associated with,
39 * a bitmask of the poll events that were triggered (typically EVENT_INPUT),
40 * and the data pointer that was originally supplied.
41 *
42 * Implementations should return 1 to continue receiving callbacks, or 0
43 * to have this file descriptor and callback unregistered from the looper.
44 */
45typedef int (*Looper_callbackFunc)(int fd, int events, void* data);
46
47/**
48 * A message that can be posted to a Looper.
49 */
50struct Message {
51    Message() : what(0) { }
52    Message(int what) : what(what) { }
53
54    /* The message type. (interpretation is left up to the handler) */
55    int what;
56};
57
58
59/**
60 * Interface for a Looper message handler.
61 *
62 * The Looper holds a strong reference to the message handler whenever it has
63 * a message to deliver to it.  Make sure to call Looper::removeMessages
64 * to remove any pending messages destined for the handler so that the handler
65 * can be destroyed.
66 */
67class MessageHandler : public virtual RefBase {
68protected:
69    virtual ~MessageHandler() { }
70
71public:
72    /**
73     * Handles a message.
74     */
75    virtual void handleMessage(const Message& message) = 0;
76};
77
78
79/**
80 * A simple proxy that holds a weak reference to a message handler.
81 */
82class WeakMessageHandler : public MessageHandler {
83protected:
84    virtual ~WeakMessageHandler();
85
86public:
87    WeakMessageHandler(const wp<MessageHandler>& handler);
88    virtual void handleMessage(const Message& message);
89
90private:
91    wp<MessageHandler> mHandler;
92};
93
94
95/**
96 * A looper callback.
97 */
98class LooperCallback : public virtual RefBase {
99protected:
100    virtual ~LooperCallback() { }
101
102public:
103    /**
104     * Handles a poll event for the given file descriptor.
105     * It is given the file descriptor it is associated with,
106     * a bitmask of the poll events that were triggered (typically EVENT_INPUT),
107     * and the data pointer that was originally supplied.
108     *
109     * Implementations should return 1 to continue receiving callbacks, or 0
110     * to have this file descriptor and callback unregistered from the looper.
111     */
112    virtual int handleEvent(int fd, int events, void* data) = 0;
113};
114
115/**
116 * Wraps a Looper_callbackFunc function pointer.
117 */
118class SimpleLooperCallback : public LooperCallback {
119protected:
120    virtual ~SimpleLooperCallback();
121
122public:
123    SimpleLooperCallback(Looper_callbackFunc callback);
124    virtual int handleEvent(int fd, int events, void* data);
125
126private:
127    Looper_callbackFunc mCallback;
128};
129
130/**
131 * A polling loop that supports monitoring file descriptor events, optionally
132 * using callbacks.  The implementation uses epoll() internally.
133 *
134 * A looper can be associated with a thread although there is no requirement that it must be.
135 */
136class Looper : public RefBase {
137protected:
138    virtual ~Looper();
139
140public:
141    enum {
142        /**
143         * Result from Looper_pollOnce() and Looper_pollAll():
144         * The poll was awoken using wake() before the timeout expired
145         * and no callbacks were executed and no other file descriptors were ready.
146         */
147        POLL_WAKE = -1,
148
149        /**
150         * Result from Looper_pollOnce() and Looper_pollAll():
151         * One or more callbacks were executed.
152         */
153        POLL_CALLBACK = -2,
154
155        /**
156         * Result from Looper_pollOnce() and Looper_pollAll():
157         * The timeout expired.
158         */
159        POLL_TIMEOUT = -3,
160
161        /**
162         * Result from Looper_pollOnce() and Looper_pollAll():
163         * An error occurred.
164         */
165        POLL_ERROR = -4,
166    };
167
168    /**
169     * Flags for file descriptor events that a looper can monitor.
170     *
171     * These flag bits can be combined to monitor multiple events at once.
172     */
173    enum {
174        /**
175         * The file descriptor is available for read operations.
176         */
177        EVENT_INPUT = 1 << 0,
178
179        /**
180         * The file descriptor is available for write operations.
181         */
182        EVENT_OUTPUT = 1 << 1,
183
184        /**
185         * The file descriptor has encountered an error condition.
186         *
187         * The looper always sends notifications about errors; it is not necessary
188         * to specify this event flag in the requested event set.
189         */
190        EVENT_ERROR = 1 << 2,
191
192        /**
193         * The file descriptor was hung up.
194         * For example, indicates that the remote end of a pipe or socket was closed.
195         *
196         * The looper always sends notifications about hangups; it is not necessary
197         * to specify this event flag in the requested event set.
198         */
199        EVENT_HANGUP = 1 << 3,
200
201        /**
202         * The file descriptor is invalid.
203         * For example, the file descriptor was closed prematurely.
204         *
205         * The looper always sends notifications about invalid file descriptors; it is not necessary
206         * to specify this event flag in the requested event set.
207         */
208        EVENT_INVALID = 1 << 4,
209    };
210
211    enum {
212        /**
213         * Option for Looper_prepare: this looper will accept calls to
214         * Looper_addFd() that do not have a callback (that is provide NULL
215         * for the callback).  In this case the caller of Looper_pollOnce()
216         * or Looper_pollAll() MUST check the return from these functions to
217         * discover when data is available on such fds and process it.
218         */
219        PREPARE_ALLOW_NON_CALLBACKS = 1<<0
220    };
221
222    /**
223     * Creates a looper.
224     *
225     * If allowNonCallbaks is true, the looper will allow file descriptors to be
226     * registered without associated callbacks.  This assumes that the caller of
227     * pollOnce() is prepared to handle callback-less events itself.
228     */
229    Looper(bool allowNonCallbacks);
230
231    /**
232     * Returns whether this looper instance allows the registration of file descriptors
233     * using identifiers instead of callbacks.
234     */
235    bool getAllowNonCallbacks() const;
236
237    /**
238     * Waits for events to be available, with optional timeout in milliseconds.
239     * Invokes callbacks for all file descriptors on which an event occurred.
240     *
241     * If the timeout is zero, returns immediately without blocking.
242     * If the timeout is negative, waits indefinitely until an event appears.
243     *
244     * Returns POLL_WAKE if the poll was awoken using wake() before
245     * the timeout expired and no callbacks were invoked and no other file
246     * descriptors were ready.
247     *
248     * Returns POLL_CALLBACK if one or more callbacks were invoked.
249     *
250     * Returns POLL_TIMEOUT if there was no data before the given
251     * timeout expired.
252     *
253     * Returns POLL_ERROR if an error occurred.
254     *
255     * Returns a value >= 0 containing an identifier if its file descriptor has data
256     * and it has no callback function (requiring the caller here to handle it).
257     * In this (and only this) case outFd, outEvents and outData will contain the poll
258     * events and data associated with the fd, otherwise they will be set to NULL.
259     *
260     * This method does not return until it has finished invoking the appropriate callbacks
261     * for all file descriptors that were signalled.
262     */
263    int pollOnce(int timeoutMillis, int* outFd, int* outEvents, void** outData);
264    inline int pollOnce(int timeoutMillis) {
265        return pollOnce(timeoutMillis, NULL, NULL, NULL);
266    }
267
268    /**
269     * Like pollOnce(), but performs all pending callbacks until all
270     * data has been consumed or a file descriptor is available with no callback.
271     * This function will never return POLL_CALLBACK.
272     */
273    int pollAll(int timeoutMillis, int* outFd, int* outEvents, void** outData);
274    inline int pollAll(int timeoutMillis) {
275        return pollAll(timeoutMillis, NULL, NULL, NULL);
276    }
277
278    /**
279     * Wakes the poll asynchronously.
280     *
281     * This method can be called on any thread.
282     * This method returns immediately.
283     */
284    void wake();
285
286    /**
287     * Adds a new file descriptor to be polled by the looper.
288     * If the same file descriptor was previously added, it is replaced.
289     *
290     * "fd" is the file descriptor to be added.
291     * "ident" is an identifier for this event, which is returned from pollOnce().
292     * The identifier must be >= 0, or POLL_CALLBACK if providing a non-NULL callback.
293     * "events" are the poll events to wake up on.  Typically this is EVENT_INPUT.
294     * "callback" is the function to call when there is an event on the file descriptor.
295     * "data" is a private data pointer to supply to the callback.
296     *
297     * There are two main uses of this function:
298     *
299     * (1) If "callback" is non-NULL, then this function will be called when there is
300     * data on the file descriptor.  It should execute any events it has pending,
301     * appropriately reading from the file descriptor.  The 'ident' is ignored in this case.
302     *
303     * (2) If "callback" is NULL, the 'ident' will be returned by Looper_pollOnce
304     * when its file descriptor has data available, requiring the caller to take
305     * care of processing it.
306     *
307     * Returns 1 if the file descriptor was added, 0 if the arguments were invalid.
308     *
309     * This method can be called on any thread.
310     * This method may block briefly if it needs to wake the poll.
311     *
312     * The callback may either be specified as a bare function pointer or as a smart
313     * pointer callback object.  The smart pointer should be preferred because it is
314     * easier to avoid races when the callback is removed from a different thread.
315     * See removeFd() for details.
316     */
317    int addFd(int fd, int ident, int events, Looper_callbackFunc callback, void* data);
318    int addFd(int fd, int ident, int events, const sp<LooperCallback>& callback, void* data);
319
320    /**
321     * Removes a previously added file descriptor from the looper.
322     *
323     * When this method returns, it is safe to close the file descriptor since the looper
324     * will no longer have a reference to it.  However, it is possible for the callback to
325     * already be running or for it to run one last time if the file descriptor was already
326     * signalled.  Calling code is responsible for ensuring that this case is safely handled.
327     * For example, if the callback takes care of removing itself during its own execution either
328     * by returning 0 or by calling this method, then it can be guaranteed to not be invoked
329     * again at any later time unless registered anew.
330     *
331     * A simple way to avoid this problem is to use the version of addFd() that takes
332     * a sp<LooperCallback> instead of a bare function pointer.  The LooperCallback will
333     * be released at the appropriate time by the Looper.
334     *
335     * Returns 1 if the file descriptor was removed, 0 if none was previously registered.
336     *
337     * This method can be called on any thread.
338     * This method may block briefly if it needs to wake the poll.
339     */
340    int removeFd(int fd);
341
342    /**
343     * Enqueues a message to be processed by the specified handler.
344     *
345     * The handler must not be null.
346     * This method can be called on any thread.
347     */
348    void sendMessage(const sp<MessageHandler>& handler, const Message& message);
349
350    /**
351     * Enqueues a message to be processed by the specified handler after all pending messages
352     * after the specified delay.
353     *
354     * The time delay is specified in uptime nanoseconds.
355     * The handler must not be null.
356     * This method can be called on any thread.
357     */
358    void sendMessageDelayed(nsecs_t uptimeDelay, const sp<MessageHandler>& handler,
359            const Message& message);
360
361    /**
362     * Enqueues a message to be processed by the specified handler after all pending messages
363     * at the specified time.
364     *
365     * The time is specified in uptime nanoseconds.
366     * The handler must not be null.
367     * This method can be called on any thread.
368     */
369    void sendMessageAtTime(nsecs_t uptime, const sp<MessageHandler>& handler,
370            const Message& message);
371
372    /**
373     * Removes all messages for the specified handler from the queue.
374     *
375     * The handler must not be null.
376     * This method can be called on any thread.
377     */
378    void removeMessages(const sp<MessageHandler>& handler);
379
380    /**
381     * Removes all messages of a particular type for the specified handler from the queue.
382     *
383     * The handler must not be null.
384     * This method can be called on any thread.
385     */
386    void removeMessages(const sp<MessageHandler>& handler, int what);
387
388    /**
389     * Returns whether this looper's thread is currently polling for more work to do.
390     * This is a good signal that the loop is still alive rather than being stuck
391     * handling a callback.  Note that this method is intrinsically racy, since the
392     * state of the loop can change before you get the result back.
393     */
394    bool isPolling() const;
395
396    /**
397     * Prepares a looper associated with the calling thread, and returns it.
398     * If the thread already has a looper, it is returned.  Otherwise, a new
399     * one is created, associated with the thread, and returned.
400     *
401     * The opts may be PREPARE_ALLOW_NON_CALLBACKS or 0.
402     */
403    static sp<Looper> prepare(int opts);
404
405    /**
406     * Sets the given looper to be associated with the calling thread.
407     * If another looper is already associated with the thread, it is replaced.
408     *
409     * If "looper" is NULL, removes the currently associated looper.
410     */
411    static void setForThread(const sp<Looper>& looper);
412
413    /**
414     * Returns the looper associated with the calling thread, or NULL if
415     * there is not one.
416     */
417    static sp<Looper> getForThread();
418
419private:
420    struct Request {
421        int fd;
422        int ident;
423        int events;
424        int seq;
425        sp<LooperCallback> callback;
426        void* data;
427
428        void initEventItem(struct epoll_event* eventItem) const;
429    };
430
431    struct Response {
432        int events;
433        Request request;
434    };
435
436    struct MessageEnvelope {
437        MessageEnvelope() : uptime(0) { }
438
439        MessageEnvelope(nsecs_t uptime, const sp<MessageHandler> handler,
440                const Message& message) : uptime(uptime), handler(handler), message(message) {
441        }
442
443        nsecs_t uptime;
444        sp<MessageHandler> handler;
445        Message message;
446    };
447
448    const bool mAllowNonCallbacks; // immutable
449
450    int mWakeEventFd;  // immutable
451    Mutex mLock;
452
453    Vector<MessageEnvelope> mMessageEnvelopes; // guarded by mLock
454    bool mSendingMessage; // guarded by mLock
455
456    // Whether we are currently waiting for work.  Not protected by a lock,
457    // any use of it is racy anyway.
458    volatile bool mPolling;
459
460    int mEpollFd; // guarded by mLock but only modified on the looper thread
461    bool mEpollRebuildRequired; // guarded by mLock
462
463    // Locked list of file descriptor monitoring requests.
464    KeyedVector<int, Request> mRequests;  // guarded by mLock
465    int mNextRequestSeq;
466
467    // This state is only used privately by pollOnce and does not require a lock since
468    // it runs on a single thread.
469    Vector<Response> mResponses;
470    size_t mResponseIndex;
471    nsecs_t mNextMessageUptime; // set to LLONG_MAX when none
472
473    int pollInner(int timeoutMillis);
474    int removeFd(int fd, int seq);
475    void awoken();
476    void pushResponse(int events, const Request& request);
477    void rebuildEpollLocked();
478    void scheduleEpollRebuildLocked();
479
480    static void initTLSKey();
481    static void threadDestructor(void *st);
482    static void initEpollEvent(struct epoll_event* eventItem);
483};
484
485} // namespace android
486
487#endif // UTILS_LOOPER_H
488