cutils/selector.h

   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 */