Home | History | Annotate | Download | only in android
      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 
     18 #ifndef ANDROID_LOOPER_H
     19 #define ANDROID_LOOPER_H
     20 
     21 #ifdef __cplusplus
     22 extern "C" {
     23 #endif
     24 
     25 /**
     26  * ALooper
     27  *
     28  * A looper is the state tracking an event loop for a thread.
     29  * Loopers do not define event structures or other such things; rather
     30  * they are a lower-level facility to attach one or more discrete objects
     31  * listening for an event.  An "event" here is simply data available on
     32  * a file descriptor: each attached object has an associated file descriptor,
     33  * and waiting for "events" means (internally) polling on all of these file
     34  * descriptors until one or more of them have data available.
     35  *
     36  * A thread can have only one ALooper associated with it.
     37  */
     38 struct ALooper;
     39 typedef struct ALooper ALooper;
     40 
     41 /**
     42  * Returns the looper associated with the calling thread, or NULL if
     43  * there is not one.
     44  */
     45 ALooper* ALooper_forThread();
     46 
     47 enum {
     48     /**
     49      * Option for ALooper_prepare: this looper will accept calls to
     50      * ALooper_addFd() that do not have a callback (that is provide NULL
     51      * for the callback).  In this case the caller of ALooper_pollOnce()
     52      * or ALooper_pollAll() MUST check the return from these functions to
     53      * discover when data is available on such fds and process it.
     54      */
     55     ALOOPER_PREPARE_ALLOW_NON_CALLBACKS = 1<<0
     56 };
     57 
     58 /**
     59  * Prepares a looper associated with the calling thread, and returns it.
     60  * If the thread already has a looper, it is returned.  Otherwise, a new
     61  * one is created, associated with the thread, and returned.
     62  *
     63  * The opts may be ALOOPER_PREPARE_ALLOW_NON_CALLBACKS or 0.
     64  */
     65 ALooper* ALooper_prepare(int opts);
     66 
     67 enum {
     68     /**
     69      * Result from ALooper_pollOnce() and ALooper_pollAll():
     70      * The poll was awoken using wake() before the timeout expired
     71      * and no callbacks were executed and no other file descriptors were ready.
     72      */
     73     ALOOPER_POLL_WAKE = -1,
     74 
     75     /**
     76      * Result from ALooper_pollOnce() and ALooper_pollAll():
     77      * One or more callbacks were executed.
     78      */
     79     ALOOPER_POLL_CALLBACK = -2,
     80 
     81     /**
     82      * Result from ALooper_pollOnce() and ALooper_pollAll():
     83      * The timeout expired.
     84      */
     85     ALOOPER_POLL_TIMEOUT = -3,
     86 
     87     /**
     88      * Result from ALooper_pollOnce() and ALooper_pollAll():
     89      * An error occurred.
     90      */
     91     ALOOPER_POLL_ERROR = -4,
     92 };
     93 
     94 /**
     95  * Acquire a reference on the given ALooper object.  This prevents the object
     96  * from being deleted until the reference is removed.  This is only needed
     97  * to safely hand an ALooper from one thread to another.
     98  */
     99 void ALooper_acquire(ALooper* looper);
    100 
    101 /**
    102  * Remove a reference that was previously acquired with ALooper_acquire().
    103  */
    104 void ALooper_release(ALooper* looper);
    105 
    106 /**
    107  * Flags for file descriptor events that a looper can monitor.
    108  *
    109  * These flag bits can be combined to monitor multiple events at once.
    110  */
    111 enum {
    112     /**
    113      * The file descriptor is available for read operations.
    114      */
    115     ALOOPER_EVENT_INPUT = 1 << 0,
    116 
    117     /**
    118      * The file descriptor is available for write operations.
    119      */
    120     ALOOPER_EVENT_OUTPUT = 1 << 1,
    121 
    122     /**
    123      * The file descriptor has encountered an error condition.
    124      *
    125      * The looper always sends notifications about errors; it is not necessary
    126      * to specify this event flag in the requested event set.
    127      */
    128     ALOOPER_EVENT_ERROR = 1 << 2,
    129 
    130     /**
    131      * The file descriptor was hung up.
    132      * For example, indicates that the remote end of a pipe or socket was closed.
    133      *
    134      * The looper always sends notifications about hangups; it is not necessary
    135      * to specify this event flag in the requested event set.
    136      */
    137     ALOOPER_EVENT_HANGUP = 1 << 3,
    138 
    139     /**
    140      * The file descriptor is invalid.
    141      * For example, the file descriptor was closed prematurely.
    142      *
    143      * The looper always sends notifications about invalid file descriptors; it is not necessary
    144      * to specify this event flag in the requested event set.
    145      */
    146     ALOOPER_EVENT_INVALID = 1 << 4,
    147 };
    148 
    149 /**
    150  * For callback-based event loops, this is the prototype of the function
    151  * that is called when a file descriptor event occurs.
    152  * It is given the file descriptor it is associated with,
    153  * a bitmask of the poll events that were triggered (typically ALOOPER_EVENT_INPUT),
    154  * and the data pointer that was originally supplied.
    155  *
    156  * Implementations should return 1 to continue receiving callbacks, or 0
    157  * to have this file descriptor and callback unregistered from the looper.
    158  */
    159 typedef int (*ALooper_callbackFunc)(int fd, int events, void* data);
    160 
    161 /**
    162  * Waits for events to be available, with optional timeout in milliseconds.
    163  * Invokes callbacks for all file descriptors on which an event occurred.
    164  *
    165  * If the timeout is zero, returns immediately without blocking.
    166  * If the timeout is negative, waits indefinitely until an event appears.
    167  *
    168  * Returns ALOOPER_POLL_WAKE if the poll was awoken using wake() before
    169  * the timeout expired and no callbacks were invoked and no other file
    170  * descriptors were ready.
    171  *
    172  * Returns ALOOPER_POLL_CALLBACK if one or more callbacks were invoked.
    173  *
    174  * Returns ALOOPER_POLL_TIMEOUT if there was no data before the given
    175  * timeout expired.
    176  *
    177  * Returns ALOOPER_POLL_ERROR if an error occurred.
    178  *
    179  * Returns a value >= 0 containing an identifier if its file descriptor has data
    180  * and it has no callback function (requiring the caller here to handle it).
    181  * In this (and only this) case outFd, outEvents and outData will contain the poll
    182  * events and data associated with the fd, otherwise they will be set to NULL.
    183  *
    184  * This method does not return until it has finished invoking the appropriate callbacks
    185  * for all file descriptors that were signalled.
    186  */
    187 int ALooper_pollOnce(int timeoutMillis, int* outFd, int* outEvents, void** outData);
    188 
    189 /**
    190  * Like ALooper_pollOnce(), but performs all pending callbacks until all
    191  * data has been consumed or a file descriptor is available with no callback.
    192  * This function will never return ALOOPER_POLL_CALLBACK.
    193  */
    194 int ALooper_pollAll(int timeoutMillis, int* outFd, int* outEvents, void** outData);
    195 
    196 /**
    197  * Wakes the poll asynchronously.
    198  *
    199  * This method can be called on any thread.
    200  * This method returns immediately.
    201  */
    202 void ALooper_wake(ALooper* looper);
    203 
    204 /**
    205  * Adds a new file descriptor to be polled by the looper.
    206  * If the same file descriptor was previously added, it is replaced.
    207  *
    208  * "fd" is the file descriptor to be added.
    209  * "ident" is an identifier for this event, which is returned from ALooper_pollOnce().
    210  * The identifier must be >= 0, or ALOOPER_POLL_CALLBACK if providing a non-NULL callback.
    211  * "events" are the poll events to wake up on.  Typically this is ALOOPER_EVENT_INPUT.
    212  * "callback" is the function to call when there is an event on the file descriptor.
    213  * "data" is a private data pointer to supply to the callback.
    214  *
    215  * There are two main uses of this function:
    216  *
    217  * (1) If "callback" is non-NULL, then this function will be called when there is
    218  * data on the file descriptor.  It should execute any events it has pending,
    219  * appropriately reading from the file descriptor.  The 'ident' is ignored in this case.
    220  *
    221  * (2) If "callback" is NULL, the 'ident' will be returned by ALooper_pollOnce
    222  * when its file descriptor has data available, requiring the caller to take
    223  * care of processing it.
    224  *
    225  * Returns 1 if the file descriptor was added or -1 if an error occurred.
    226  *
    227  * This method can be called on any thread.
    228  * This method may block briefly if it needs to wake the poll.
    229  */
    230 int ALooper_addFd(ALooper* looper, int fd, int ident, int events,
    231         ALooper_callbackFunc callback, void* data);
    232 
    233 /**
    234  * Removes a previously added file descriptor from the looper.
    235  *
    236  * When this method returns, it is safe to close the file descriptor since the looper
    237  * will no longer have a reference to it.  However, it is possible for the callback to
    238  * already be running or for it to run one last time if the file descriptor was already
    239  * signalled.  Calling code is responsible for ensuring that this case is safely handled.
    240  * For example, if the callback takes care of removing itself during its own execution either
    241  * by returning 0 or by calling this method, then it can be guaranteed to not be invoked
    242  * again at any later time unless registered anew.
    243  *
    244  * Returns 1 if the file descriptor was removed, 0 if none was previously registered
    245  * or -1 if an error occurred.
    246  *
    247  * This method can be called on any thread.
    248  * This method may block briefly if it needs to wake the poll.
    249  */
    250 int ALooper_removeFd(ALooper* looper, int fd);
    251 
    252 #ifdef __cplusplus
    253 };
    254 #endif
    255 
    256 #endif // ANDROID_LOOPER_H
    257