Looper.h revision dd1b0378cec939e7c90f8e8d8216b481f9f2035a
17901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown/* 27901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Copyright (C) 2010 The Android Open Source Project 37901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 47901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Licensed under the Apache License, Version 2.0 (the "License"); 57901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * you may not use this file except in compliance with the License. 67901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * You may obtain a copy of the License at 77901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 87901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * http://www.apache.org/licenses/LICENSE-2.0 97901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 107901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Unless required by applicable law or agreed to in writing, software 117901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * distributed under the License is distributed on an "AS IS" BASIS, 127901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 137901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * See the License for the specific language governing permissions and 147901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * limitations under the License. 157901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 167901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 177901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown#ifndef UTILS_LOOPER_H 187901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown#define UTILS_LOOPER_H 197901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 207901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown#include <utils/threads.h> 217901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown#include <utils/RefBase.h> 227901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown#include <utils/KeyedVector.h> 238d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown#include <utils/Timers.h> 247901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 257901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown#include <android/looper.h> 267901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 278d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown#include <sys/epoll.h> 288d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown 297901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown/* 307901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Declare a concrete type for the NDK's looper forward declaration. 317901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 327901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brownstruct ALooper { 337901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown}; 347901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 357901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brownnamespace android { 367901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 377901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown/** 383e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * A message that can be posted to a Looper. 393e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown */ 403e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brownstruct Message { 413e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown Message() : what(0) { } 423e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown Message(int what) : what(what) { } 433e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 443e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown /* The message type. (interpretation is left up to the handler) */ 453e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown int what; 463e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown}; 473e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 483e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 493e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown/** 503e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * Interface for a Looper message handler. 513e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * 523e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * The Looper holds a strong reference to the message handler whenever it has 533e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * a message to deliver to it. Make sure to call Looper::removeMessages 543e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * to remove any pending messages destined for the handler so that the handler 553e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * can be destroyed. 563e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown */ 573e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brownclass MessageHandler : public virtual RefBase { 583e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brownprotected: 593e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown virtual ~MessageHandler() { } 603e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 613e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brownpublic: 623e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown /** 633e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * Handles a message. 643e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown */ 653e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown virtual void handleMessage(const Message& message) = 0; 663e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown}; 673e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 683e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 693e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown/** 703e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * A simple proxy that holds a weak reference to a message handler. 713e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown */ 723e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brownclass WeakMessageHandler : public MessageHandler { 73dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brownprotected: 74dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown virtual ~WeakMessageHandler(); 75dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown 763e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brownpublic: 773e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown WeakMessageHandler(const wp<MessageHandler>& handler); 783e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown virtual void handleMessage(const Message& message); 793e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 803e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brownprivate: 813e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown wp<MessageHandler> mHandler; 823e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown}; 833e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 843e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 853e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown/** 86dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * A looper callback. 87dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown */ 88dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brownclass LooperCallback : public virtual RefBase { 89dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brownprotected: 90dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown virtual ~LooperCallback() { } 91dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown 92dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brownpublic: 93dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown /** 94dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * Handles a poll event for the given file descriptor. 95dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * It is given the file descriptor it is associated with, 96dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * a bitmask of the poll events that were triggered (typically ALOOPER_EVENT_INPUT), 97dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * and the data pointer that was originally supplied. 98dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * 99dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * Implementations should return 1 to continue receiving callbacks, or 0 100dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * to have this file descriptor and callback unregistered from the looper. 101dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown */ 102dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown virtual int handleEvent(int fd, int events, void* data) = 0; 103dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown}; 104dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown 105dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown 106dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown/** 107dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * Wraps a ALooper_callbackFunc function pointer. 108dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown */ 109dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brownclass SimpleLooperCallback : public LooperCallback { 110dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brownprotected: 111dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown virtual ~SimpleLooperCallback(); 112dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown 113dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brownpublic: 114dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown SimpleLooperCallback(ALooper_callbackFunc callback); 115dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown virtual int handleEvent(int fd, int events, void* data); 116dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown 117dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brownprivate: 118dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown ALooper_callbackFunc mCallback; 119dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown}; 120dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown 121dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown 122dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown/** 1237901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * A polling loop that supports monitoring file descriptor events, optionally 1247901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * using callbacks. The implementation uses epoll() internally. 1257901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1267901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * A looper can be associated with a thread although there is no requirement that it must be. 1277901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 1287901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brownclass Looper : public ALooper, public RefBase { 1297901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brownprotected: 1307901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown virtual ~Looper(); 1317901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 1327901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brownpublic: 1337901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 1347901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Creates a looper. 1357901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1367901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * If allowNonCallbaks is true, the looper will allow file descriptors to be 1377901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * registered without associated callbacks. This assumes that the caller of 1387901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * pollOnce() is prepared to handle callback-less events itself. 1397901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 1407901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown Looper(bool allowNonCallbacks); 1417901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 1427901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 1437901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Returns whether this looper instance allows the registration of file descriptors 1447901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * using identifiers instead of callbacks. 1457901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 1467901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown bool getAllowNonCallbacks() const; 1477901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 1487901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 1497901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Waits for events to be available, with optional timeout in milliseconds. 1507901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Invokes callbacks for all file descriptors on which an event occurred. 1517901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1527901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * If the timeout is zero, returns immediately without blocking. 1537901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * If the timeout is negative, waits indefinitely until an event appears. 1547901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1557901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Returns ALOOPER_POLL_WAKE if the poll was awoken using wake() before 1567901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * the timeout expired and no callbacks were invoked and no other file 1577901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * descriptors were ready. 1587901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1597901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Returns ALOOPER_POLL_CALLBACK if one or more callbacks were invoked. 1607901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1617901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Returns ALOOPER_POLL_TIMEOUT if there was no data before the given 1627901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * timeout expired. 1637901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1647901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Returns ALOOPER_POLL_ERROR if an error occurred. 1657901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1667901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Returns a value >= 0 containing an identifier if its file descriptor has data 1677901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * and it has no callback function (requiring the caller here to handle it). 1687901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * In this (and only this) case outFd, outEvents and outData will contain the poll 1697901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * events and data associated with the fd, otherwise they will be set to NULL. 1707901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1717901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * This method does not return until it has finished invoking the appropriate callbacks 1727901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * for all file descriptors that were signalled. 1737901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 174905682a19609e862633f01e69bec58384df2cdf7Jeff Brown int pollOnce(int timeoutMillis, int* outFd, int* outEvents, void** outData); 175905682a19609e862633f01e69bec58384df2cdf7Jeff Brown inline int pollOnce(int timeoutMillis) { 176905682a19609e862633f01e69bec58384df2cdf7Jeff Brown return pollOnce(timeoutMillis, NULL, NULL, NULL); 177905682a19609e862633f01e69bec58384df2cdf7Jeff Brown } 1787901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 1797901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 1807901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Like pollOnce(), but performs all pending callbacks until all 1817901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * data has been consumed or a file descriptor is available with no callback. 1827901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * This function will never return ALOOPER_POLL_CALLBACK. 1837901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 184905682a19609e862633f01e69bec58384df2cdf7Jeff Brown int pollAll(int timeoutMillis, int* outFd, int* outEvents, void** outData); 185905682a19609e862633f01e69bec58384df2cdf7Jeff Brown inline int pollAll(int timeoutMillis) { 186905682a19609e862633f01e69bec58384df2cdf7Jeff Brown return pollAll(timeoutMillis, NULL, NULL, NULL); 187905682a19609e862633f01e69bec58384df2cdf7Jeff Brown } 1887901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 1897901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 1907901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Wakes the poll asynchronously. 1917901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 1927901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * This method can be called on any thread. 1937901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * This method returns immediately. 1947901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 1957901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown void wake(); 1967901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 1977901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 1987901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Adds a new file descriptor to be polled by the looper. 1997901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * If the same file descriptor was previously added, it is replaced. 2007901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 2017901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * "fd" is the file descriptor to be added. 202dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * "ident" is an identifier for this event, which is returned from pollOnce(). 2037901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * The identifier must be >= 0, or ALOOPER_POLL_CALLBACK if providing a non-NULL callback. 2047901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * "events" are the poll events to wake up on. Typically this is ALOOPER_EVENT_INPUT. 2057901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * "callback" is the function to call when there is an event on the file descriptor. 2067901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * "data" is a private data pointer to supply to the callback. 2077901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 2087901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * There are two main uses of this function: 2097901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 2107901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * (1) If "callback" is non-NULL, then this function will be called when there is 2117901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * data on the file descriptor. It should execute any events it has pending, 2127901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * appropriately reading from the file descriptor. The 'ident' is ignored in this case. 2137901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 2147901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * (2) If "callback" is NULL, the 'ident' will be returned by ALooper_pollOnce 2157901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * when its file descriptor has data available, requiring the caller to take 2167901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * care of processing it. 2177901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 2187901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Returns 1 if the file descriptor was added, 0 if the arguments were invalid. 2197901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 2207901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * This method can be called on any thread. 2217901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * This method may block briefly if it needs to wake the poll. 222dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * 223dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * The callback may either be specified as a bare function pointer or as a smart 224dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * pointer callback object. The smart pointer should be preferred because it is 225dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * easier to avoid races when the callback is removed from a different thread. 226dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * See removeFd() for details. 2277901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 228905682a19609e862633f01e69bec58384df2cdf7Jeff Brown int addFd(int fd, int ident, int events, ALooper_callbackFunc callback, void* data); 229dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown int addFd(int fd, int ident, int events, const sp<LooperCallback>& callback, void* data); 2307901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 2317901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 2327901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Removes a previously added file descriptor from the looper. 2337901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 2347901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * When this method returns, it is safe to close the file descriptor since the looper 2357901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * will no longer have a reference to it. However, it is possible for the callback to 2367901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * already be running or for it to run one last time if the file descriptor was already 2377901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * signalled. Calling code is responsible for ensuring that this case is safely handled. 2387901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * For example, if the callback takes care of removing itself during its own execution either 2397901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * by returning 0 or by calling this method, then it can be guaranteed to not be invoked 2407901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * again at any later time unless registered anew. 2417901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 242dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * A simple way to avoid this problem is to use the version of addFd() that takes 243dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * a sp<LooperCallback> instead of a bare function pointer. The LooperCallback will 244dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * be released at the appropriate time by the Looper. 245dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown * 2467901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Returns 1 if the file descriptor was removed, 0 if none was previously registered. 2477901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 2487901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * This method can be called on any thread. 2497901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * This method may block briefly if it needs to wake the poll. 2507901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 2517901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown int removeFd(int fd); 2527901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 2537901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 2543e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * Enqueues a message to be processed by the specified handler. 2553e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * 2563e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * The handler must not be null. 2573e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * This method can be called on any thread. 2583e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown */ 2593e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown void sendMessage(const sp<MessageHandler>& handler, const Message& message); 2603e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 2613e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown /** 2623e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * Enqueues a message to be processed by the specified handler after all pending messages 2633e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * after the specified delay. 2643e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * 2653e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * The time delay is specified in uptime nanoseconds. 2663e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * The handler must not be null. 2673e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * This method can be called on any thread. 2683e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown */ 2693e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown void sendMessageDelayed(nsecs_t uptimeDelay, const sp<MessageHandler>& handler, 2703e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown const Message& message); 2713e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 2723e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown /** 2733e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * Enqueues a message to be processed by the specified handler after all pending messages 2743e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * at the specified time. 2753e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * 2763e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * The time is specified in uptime nanoseconds. 2773e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * The handler must not be null. 2783e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * This method can be called on any thread. 2793e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown */ 2803e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown void sendMessageAtTime(nsecs_t uptime, const sp<MessageHandler>& handler, 2813e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown const Message& message); 2823e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 2833e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown /** 2843e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * Removes all messages for the specified handler from the queue. 2853e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * 2863e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * The handler must not be null. 2873e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * This method can be called on any thread. 2883e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown */ 2893e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown void removeMessages(const sp<MessageHandler>& handler); 2903e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 2913e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown /** 2923e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * Removes all messages of a particular type for the specified handler from the queue. 2933e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * 2943e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * The handler must not be null. 2953e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown * This method can be called on any thread. 2963e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown */ 2973e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown void removeMessages(const sp<MessageHandler>& handler, int what); 2983e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 2993e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown /** 3007901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Prepares a looper associated with the calling thread, and returns it. 3017901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * If the thread already has a looper, it is returned. Otherwise, a new 3027901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * one is created, associated with the thread, and returned. 3037901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 3047901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * The opts may be ALOOPER_PREPARE_ALLOW_NON_CALLBACKS or 0. 3057901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 3067901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown static sp<Looper> prepare(int opts); 3077901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3087901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 3097901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Sets the given looper to be associated with the calling thread. 3107901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * If another looper is already associated with the thread, it is replaced. 3117901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * 3127901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * If "looper" is NULL, removes the currently associated looper. 3137901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 3147901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown static void setForThread(const sp<Looper>& looper); 3157901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3167901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown /** 3177901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * Returns the looper associated with the calling thread, or NULL if 3187901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown * there is not one. 3197901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown */ 3207901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown static sp<Looper> getForThread(); 3217901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3227901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brownprivate: 3237901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown struct Request { 3247901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown int fd; 3257901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown int ident; 326dd1b0378cec939e7c90f8e8d8216b481f9f2035aJeff Brown sp<LooperCallback> callback; 3277901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown void* data; 3287901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown }; 3297901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3307901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown struct Response { 3317901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown int events; 3327901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown Request request; 3337901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown }; 3347901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3353e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown struct MessageEnvelope { 3363e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown MessageEnvelope() : uptime(0) { } 3373e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 3383e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown MessageEnvelope(nsecs_t uptime, const sp<MessageHandler> handler, 3393e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown const Message& message) : uptime(uptime), handler(handler), message(message) { 3403e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown } 3413e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 3423e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown nsecs_t uptime; 3433e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown sp<MessageHandler> handler; 3443e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown Message message; 3453e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown }; 3463e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 3477901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown const bool mAllowNonCallbacks; // immutable 3487901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3497901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown int mWakeReadPipeFd; // immutable 3507901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown int mWakeWritePipeFd; // immutable 3518d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown Mutex mLock; 3528d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown 3533e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown Vector<MessageEnvelope> mMessageEnvelopes; // guarded by mLock 3543e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown bool mSendingMessage; // guarded by mLock 3553e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown 3568d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown int mEpollFd; // immutable 3577901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3587901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown // Locked list of file descriptor monitoring requests. 3598d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown KeyedVector<int, Request> mRequests; // guarded by mLock 3608d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown 3617901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown // This state is only used privately by pollOnce and does not require a lock since 3627901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown // it runs on a single thread. 3637901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown Vector<Response> mResponses; 3647901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown size_t mResponseIndex; 3653e2e38bc5bbf658eb9940f72974270b11c5b84e1Jeff Brown nsecs_t mNextMessageUptime; // set to LLONG_MAX when none 3667901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3677901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown int pollInner(int timeoutMillis); 3688d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown void awoken(); 3698d15c74d50fd01d6e63970aadd261a9d3bed27e7Jeff Brown void pushResponse(int events, const Request& request); 3707901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 371d18051870e8e2a5f55237a2c11fde75f46082639Jeff Brown static void initTLSKey(); 3727901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown static void threadDestructor(void *st); 3737901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown}; 3747901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3757901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown} // namespace android 3767901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown 3777901eb25c60b1df00050d6c3772505d8dcfcdab9Jeff Brown#endif // UTILS_LOOPER_H 378