Home | History | Annotate | Download | only in cutils 
      1 /*
      2  * Copyright (C) 2007 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  * Framework for multiplexing I/O. A selector manages a set of file
     19  * descriptors and calls out to user-provided callback functions to read and
     20  * write data and handle errors.
     21  */
     22 
     23 #ifndef __SELECTOR_H
     24 #define __SELECTOR_H
     25 
     26 #ifdef __cplusplus
     27 extern "C" {
     28 #endif
     29 
     30 #include <stdbool.h>
     31 
     32 /**
     33  * Manages SelectableFds and invokes their callbacks at appropriate times.
     34  */
     35 typedef struct Selector Selector;
     36 
     37 /**
     38  * A selectable descriptor. Contains callbacks which the selector can invoke
     39  * before calling select(), when the descriptor is readable or writable, and
     40  * when the descriptor contains out-of-band data. Simply set a callback to
     41  * NULL if you're not interested in that particular event.
     42  *
     43  * A selectable descriptor can indicate that it needs to be removed from the
     44  * selector by setting the 'remove' flag. The selector will remove the
     45  * descriptor at a later time and invoke the onRemove() callback.
     46  *
     47  * SelectableFd fields should only be modified from the selector loop.
     48  */
     49 typedef struct SelectableFd SelectableFd;
     50 struct SelectableFd {
     51 
     52     /** The file descriptor itself. */
     53     int fd;
     54 
     55     /** Pointer to user-specific data. Can be NULL. */
     56     void* data;
     57 
     58     /**
     59      * Set this flag when you no longer wish to be selected. The selector
     60      * will invoke onRemove() when the descriptor is actually removed.
     61      */
     62     bool remove;
     63 
     64     /**
     65      * Invoked by the selector before calling select. You can set up other
     66      * callbacks from here as necessary.
     67      */
     68     void (*beforeSelect)(SelectableFd* self);
     69 
     70     /**
     71      * Invoked by the selector when the descriptor has data available. Set to
     72      * NULL to indicate that you're not interested in reading.
     73      */
     74     void (*onReadable)(SelectableFd* self);
     75 
     76     /**
     77      * Invoked by the selector when the descriptor can accept data. Set to
     78      * NULL to indicate that you're not interested in writing.
     79      */
     80     void (*onWritable)(SelectableFd* self);
     81 
     82     /**
     83      * Invoked by the selector when out-of-band (OOB) data is available. Set to
     84      * NULL to indicate that you're not interested in OOB data.
     85      */
     86     void (*onExcept)(SelectableFd* self);
     87 
     88     /**
     89      * Invoked by the selector after the descriptor is removed from the
     90      * selector but before the selector frees the SelectableFd memory.
     91      */
     92     void (*onRemove)(SelectableFd* self);
     93 
     94     /**
     95      * The selector which selected this fd. Set by the selector itself.
     96      */
     97     Selector* selector;
     98 };
     99 
    100 /**
    101  * Creates a new selector.
    102  */
    103 Selector* selectorCreate(void);
    104 
    105 /**
    106  * Creates a new selectable fd, adds it to the given selector and returns a
    107  * pointer. Outside of 'selector' and 'fd', all fields are set to 0 or NULL
    108  * by default.
    109  *
    110  * The selectable fd should only be modified from the selector loop thread.
    111  */
    112 SelectableFd* selectorAdd(Selector* selector, int fd);
    113 
    114 /**
    115  * Wakes up the selector even though no I/O events occurred. Use this
    116  * to indicate that you're ready to write to a descriptor.
    117  */
    118 void selectorWakeUp(Selector* selector);
    119 
    120 /**
    121  * Loops continuously selecting file descriptors and firing events.
    122  * Does not return.
    123  */
    124 void selectorLoop(Selector* selector);
    125 
    126 #ifdef __cplusplus
    127 }
    128 #endif
    129 
    130 #endif /* __SELECTOR_H */
    131