Looper.h revision dd1b0378cec939e7c90f8e8d8216b481f9f2035a
1b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar/* 2b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Copyright (C) 2010 The Android Open Source Project 3b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 4b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Licensed under the Apache License, Version 2.0 (the "License"); 59ad441ffec97db647fee3725b3424284fb913e14Howard Hinnant * you may not use this file except in compliance with the License. 69ad441ffec97db647fee3725b3424284fb913e14Howard Hinnant * You may obtain a copy of the License at 7b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 8b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * http://www.apache.org/licenses/LICENSE-2.0 9b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 10b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Unless required by applicable law or agreed to in writing, software 11b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * distributed under the License is distributed on an "AS IS" BASIS, 12b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * See the License for the specific language governing permissions and 14b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * limitations under the License. 15b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 16b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 17b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar#ifndef UTILS_LOOPER_H 18b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar#define UTILS_LOOPER_H 19b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 20b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar#include <utils/threads.h> 21b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar#include <utils/RefBase.h> 22b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar#include <utils/KeyedVector.h> 23cdce50bda3603770cc4ef80cbb613c78b8e47a17Pirama Arumuga Nainar#include <utils/Timers.h> 24b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 25b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar#include <android/looper.h> 26b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 27b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar#include <sys/epoll.h> 28b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 29b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar/* 30b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Declare a concrete type for the NDK's looper forward declaration. 31b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 32b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarstruct ALooper { 33b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar}; 34b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 35b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarnamespace android { 36b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 37b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar/** 38b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * A message that can be posted to a Looper. 39b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 40b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarstruct Message { 41b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar Message() : what(0) { } 42b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar Message(int what) : what(what) { } 43b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 44b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /* The message type. (interpretation is left up to the handler) */ 45b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int what; 46b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar}; 47b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 48b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 49b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar/** 50b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Interface for a Looper message handler. 51b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 52b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The Looper holds a strong reference to the message handler whenever it has 53b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * a message to deliver to it. Make sure to call Looper::removeMessages 54b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * to remove any pending messages destined for the handler so that the handler 55b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * can be destroyed. 56b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 57b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarclass MessageHandler : public virtual RefBase { 58b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarprotected: 59b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar virtual ~MessageHandler() { } 60b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 61b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarpublic: 62b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 63b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Handles a message. 64b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 65b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar virtual void handleMessage(const Message& message) = 0; 66b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar}; 67b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 68b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 69b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar/** 70b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * A simple proxy that holds a weak reference to a message handler. 71b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 72b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarclass WeakMessageHandler : public MessageHandler { 73b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarprotected: 74b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar virtual ~WeakMessageHandler(); 75b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 76b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarpublic: 77b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar WeakMessageHandler(const wp<MessageHandler>& handler); 78b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar virtual void handleMessage(const Message& message); 79b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 80b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarprivate: 81b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar wp<MessageHandler> mHandler; 82b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar}; 83b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 84b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 85b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar/** 86b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * A looper callback. 87b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 88b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarclass LooperCallback : public virtual RefBase { 89b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarprotected: 90b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar virtual ~LooperCallback() { } 91b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 92b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarpublic: 93b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 94b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Handles a poll event for the given file descriptor. 95b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * It is given the file descriptor it is associated with, 96b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * a bitmask of the poll events that were triggered (typically ALOOPER_EVENT_INPUT), 97b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * and the data pointer that was originally supplied. 98b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 99b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Implementations should return 1 to continue receiving callbacks, or 0 100b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * to have this file descriptor and callback unregistered from the looper. 101b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 102b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar virtual int handleEvent(int fd, int events, void* data) = 0; 103b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar}; 104b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 105b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 106b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar/** 107b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Wraps a ALooper_callbackFunc function pointer. 108b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 109b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarclass SimpleLooperCallback : public LooperCallback { 110b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarprotected: 111b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar virtual ~SimpleLooperCallback(); 112b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 113b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarpublic: 114b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar SimpleLooperCallback(ALooper_callbackFunc callback); 115b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar virtual int handleEvent(int fd, int events, void* data); 116b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 117b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarprivate: 118b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar ALooper_callbackFunc mCallback; 119b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar}; 120b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 121b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 122b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar/** 123b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * A polling loop that supports monitoring file descriptor events, optionally 124b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * using callbacks. The implementation uses epoll() internally. 125b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 126b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * A looper can be associated with a thread although there is no requirement that it must be. 127b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 128b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarclass Looper : public ALooper, public RefBase { 129b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarprotected: 130b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar virtual ~Looper(); 131b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 132b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarpublic: 133b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 134b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Creates a looper. 135b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 136b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * If allowNonCallbaks is true, the looper will allow file descriptors to be 137b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * registered without associated callbacks. This assumes that the caller of 138b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * pollOnce() is prepared to handle callback-less events itself. 139b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 140b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar Looper(bool allowNonCallbacks); 141b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 142b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 143b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Returns whether this looper instance allows the registration of file descriptors 144b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * using identifiers instead of callbacks. 145b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 146b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar bool getAllowNonCallbacks() const; 147b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 148b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 149b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Waits for events to be available, with optional timeout in milliseconds. 150b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Invokes callbacks for all file descriptors on which an event occurred. 151b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 152b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * If the timeout is zero, returns immediately without blocking. 153b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * If the timeout is negative, waits indefinitely until an event appears. 154b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 155b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Returns ALOOPER_POLL_WAKE if the poll was awoken using wake() before 156b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * the timeout expired and no callbacks were invoked and no other file 157b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * descriptors were ready. 158b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 159b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Returns ALOOPER_POLL_CALLBACK if one or more callbacks were invoked. 160b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 161b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Returns ALOOPER_POLL_TIMEOUT if there was no data before the given 162b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * timeout expired. 163b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 164b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Returns ALOOPER_POLL_ERROR if an error occurred. 165b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 166b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Returns a value >= 0 containing an identifier if its file descriptor has data 167b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * and it has no callback function (requiring the caller here to handle it). 168b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * In this (and only this) case outFd, outEvents and outData will contain the poll 169b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * events and data associated with the fd, otherwise they will be set to NULL. 170b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 171b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method does not return until it has finished invoking the appropriate callbacks 172b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * for all file descriptors that were signalled. 173b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 174b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int pollOnce(int timeoutMillis, int* outFd, int* outEvents, void** outData); 175b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar inline int pollOnce(int timeoutMillis) { 176b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar return pollOnce(timeoutMillis, NULL, NULL, NULL); 177b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar } 178b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 179b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 180b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Like pollOnce(), but performs all pending callbacks until all 181b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * data has been consumed or a file descriptor is available with no callback. 182b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This function will never return ALOOPER_POLL_CALLBACK. 183b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 184b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int pollAll(int timeoutMillis, int* outFd, int* outEvents, void** outData); 185b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar inline int pollAll(int timeoutMillis) { 186b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar return pollAll(timeoutMillis, NULL, NULL, NULL); 187b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar } 188b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 189b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 190b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Wakes the poll asynchronously. 191b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 192b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method can be called on any thread. 193b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method returns immediately. 194b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 195b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar void wake(); 196b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 197b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 198b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Adds a new file descriptor to be polled by the looper. 199b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * If the same file descriptor was previously added, it is replaced. 200b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 201b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * "fd" is the file descriptor to be added. 202b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * "ident" is an identifier for this event, which is returned from pollOnce(). 203b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The identifier must be >= 0, or ALOOPER_POLL_CALLBACK if providing a non-NULL callback. 204b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * "events" are the poll events to wake up on. Typically this is ALOOPER_EVENT_INPUT. 205b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * "callback" is the function to call when there is an event on the file descriptor. 206b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * "data" is a private data pointer to supply to the callback. 207b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 208b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * There are two main uses of this function: 209b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 210b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * (1) If "callback" is non-NULL, then this function will be called when there is 211b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * data on the file descriptor. It should execute any events it has pending, 212b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * appropriately reading from the file descriptor. The 'ident' is ignored in this case. 213b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 214b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * (2) If "callback" is NULL, the 'ident' will be returned by ALooper_pollOnce 215b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * when its file descriptor has data available, requiring the caller to take 216b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * care of processing it. 217b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 218b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Returns 1 if the file descriptor was added, 0 if the arguments were invalid. 219b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 220b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method can be called on any thread. 221b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method may block briefly if it needs to wake the poll. 222b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 223b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The callback may either be specified as a bare function pointer or as a smart 224b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * pointer callback object. The smart pointer should be preferred because it is 225b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * easier to avoid races when the callback is removed from a different thread. 226b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * See removeFd() for details. 227b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 228b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int addFd(int fd, int ident, int events, ALooper_callbackFunc callback, void* data); 229b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int addFd(int fd, int ident, int events, const sp<LooperCallback>& callback, void* data); 230b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 231b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 232b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Removes a previously added file descriptor from the looper. 233b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 234b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * When this method returns, it is safe to close the file descriptor since the looper 235b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * will no longer have a reference to it. However, it is possible for the callback to 236b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * already be running or for it to run one last time if the file descriptor was already 237b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * signalled. Calling code is responsible for ensuring that this case is safely handled. 238b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * For example, if the callback takes care of removing itself during its own execution either 239b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * by returning 0 or by calling this method, then it can be guaranteed to not be invoked 240b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * again at any later time unless registered anew. 241b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 242b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * A simple way to avoid this problem is to use the version of addFd() that takes 243b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * a sp<LooperCallback> instead of a bare function pointer. The LooperCallback will 244b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * be released at the appropriate time by the Looper. 245b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 246b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Returns 1 if the file descriptor was removed, 0 if none was previously registered. 247b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 248b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method can be called on any thread. 249b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method may block briefly if it needs to wake the poll. 250b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 251b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int removeFd(int fd); 252b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 253b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 254b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Enqueues a message to be processed by the specified handler. 255b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 256b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The handler must not be null. 257b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method can be called on any thread. 258b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 259b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar void sendMessage(const sp<MessageHandler>& handler, const Message& message); 260b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 261b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 262b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Enqueues a message to be processed by the specified handler after all pending messages 263b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * after the specified delay. 264b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 265b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The time delay is specified in uptime nanoseconds. 266b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The handler must not be null. 267b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method can be called on any thread. 268b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 269b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar void sendMessageDelayed(nsecs_t uptimeDelay, const sp<MessageHandler>& handler, 270b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar const Message& message); 271b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 272b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 273b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Enqueues a message to be processed by the specified handler after all pending messages 274b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * at the specified time. 275b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 276b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The time is specified in uptime nanoseconds. 277b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The handler must not be null. 278b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method can be called on any thread. 279b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 280b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar void sendMessageAtTime(nsecs_t uptime, const sp<MessageHandler>& handler, 281b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar const Message& message); 282b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 283b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 284b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Removes all messages for the specified handler from the queue. 285b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 286b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The handler must not be null. 287b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method can be called on any thread. 288b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 289b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar void removeMessages(const sp<MessageHandler>& handler); 290b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 291b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 292b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Removes all messages of a particular type for the specified handler from the queue. 293b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 294b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The handler must not be null. 295b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * This method can be called on any thread. 296b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 297b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar void removeMessages(const sp<MessageHandler>& handler, int what); 298b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 299b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 300b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Prepares a looper associated with the calling thread, and returns it. 301b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * If the thread already has a looper, it is returned. Otherwise, a new 302b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * one is created, associated with the thread, and returned. 303b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 304b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * The opts may be ALOOPER_PREPARE_ALLOW_NON_CALLBACKS or 0. 305b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 306b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar static sp<Looper> prepare(int opts); 307b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 308b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 309b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Sets the given looper to be associated with the calling thread. 310b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * If another looper is already associated with the thread, it is replaced. 311b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * 312b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * If "looper" is NULL, removes the currently associated looper. 313b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 314b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar static void setForThread(const sp<Looper>& looper); 315b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 316b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar /** 317b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * Returns the looper associated with the calling thread, or NULL if 318b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar * there is not one. 319b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar */ 320b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar static sp<Looper> getForThread(); 321b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 322b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbarprivate: 323b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar struct Request { 324b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int fd; 325b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int ident; 326b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar sp<LooperCallback> callback; 327b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar void* data; 328b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar }; 329b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 330b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar struct Response { 331b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int events; 332b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar Request request; 333b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar }; 334b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 335b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar struct MessageEnvelope { 336b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar MessageEnvelope() : uptime(0) { } 337b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 338b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar MessageEnvelope(nsecs_t uptime, const sp<MessageHandler> handler, 339b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar const Message& message) : uptime(uptime), handler(handler), message(message) { 340b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar } 341b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 342b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar nsecs_t uptime; 343b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar sp<MessageHandler> handler; 344b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar Message message; 345b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar }; 346b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 347b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar const bool mAllowNonCallbacks; // immutable 348b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 349b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int mWakeReadPipeFd; // immutable 350b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int mWakeWritePipeFd; // immutable 351b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar Mutex mLock; 352b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 353b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar Vector<MessageEnvelope> mMessageEnvelopes; // guarded by mLock 354b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar bool mSendingMessage; // guarded by mLock 355b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 356b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int mEpollFd; // immutable 357b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 358b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar // Locked list of file descriptor monitoring requests. 359b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar KeyedVector<int, Request> mRequests; // guarded by mLock 360b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 361b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar // This state is only used privately by pollOnce and does not require a lock since 362b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar // it runs on a single thread. 363b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar Vector<Response> mResponses; 364b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar size_t mResponseIndex; 365b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar nsecs_t mNextMessageUptime; // set to LLONG_MAX when none 366b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 367b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar int pollInner(int timeoutMillis); 368b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar void awoken(); 369b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar void pushResponse(int events, const Request& request); 370b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 3717482815716cd9b87931d82dca7298fc3c707229fJoerg Sonnenberger static void initTLSKey(); 3727482815716cd9b87931d82dca7298fc3c707229fJoerg Sonnenberger static void threadDestructor(void *st); 373b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar}; 374b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar 375b3a6901e66f55b35aa9e01bcb24134e6a65ea004Daniel Dunbar} // namespace android 376 377#endif // UTILS_LOOPER_H 378