Home | History | Annotate | Download | only in utils
      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 
     27 namespace 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  */
     45 typedef int (*Looper_callbackFunc)(int fd, int events, void* data);
     46 
     47 /**
     48  * A message that can be posted to a Looper.
     49  */
     50 struct 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  */
     67 class MessageHandler : public virtual RefBase {
     68 protected:
     69     virtual ~MessageHandler() { }
     70 
     71 public:
     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  */
     82 class WeakMessageHandler : public MessageHandler {
     83 protected:
     84     virtual ~WeakMessageHandler();
     85 
     86 public:
     87     WeakMessageHandler(const wp<MessageHandler>& handler);
     88     virtual void handleMessage(const Message& message);
     89 
     90 private:
     91     wp<MessageHandler> mHandler;
     92 };
     93 
     94 
     95 /**
     96  * A looper callback.
     97  */
     98 class LooperCallback : public virtual RefBase {
     99 protected:
    100     virtual ~LooperCallback() { }
    101 
    102 public:
    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  */
    118 class SimpleLooperCallback : public LooperCallback {
    119 protected:
    120     virtual ~SimpleLooperCallback();
    121 
    122 public:
    123     SimpleLooperCallback(Looper_callbackFunc callback);
    124     virtual int handleEvent(int fd, int events, void* data);
    125 
    126 private:
    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  */
    136 class Looper : public RefBase {
    137 protected:
    138     virtual ~Looper();
    139 
    140 public:
    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 
    419 private:
    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