00001 #ifndef PROTON_SELECTABLE_H 00002 #define PROTON_SELECTABLE_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <proton/object.h> 00027 #include <proton/io.h> 00028 #include <proton/type_compat.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** 00035 * @file 00036 * 00037 * The selectable API provides an interface for integration with third 00038 * party event loops. 00039 * 00040 * @defgroup selectable Selectable 00041 * @{ 00042 */ 00043 00044 /** 00045 * An iterator for selectables. 00046 */ 00047 typedef pn_iterator_t pn_selectables_t; 00048 00049 /** 00050 * A selectable object provides an interface that can be used to 00051 * incorporate proton's I/O into third party event loops. 00052 * 00053 * Every selectable is associated with exactly one file descriptor. 00054 * Selectables may be interested in three kinds of events, read 00055 * events, write events, and timer events. A selectable will express 00056 * its interest in these events through the ::pn_selectable_capacity(), 00057 * ::pn_selectable_pending(), and ::pn_selectable_deadline() calls. 00058 * 00059 * When a read, write, or timer event occurs, the selectable must be 00060 * notified by calling ::pn_selectable_readable(), 00061 * ::pn_selectable_writable(), and ::pn_selectable_expired() as 00062 * appropriate. 00063 * 00064 * Once a selectable reaches a terminal state (see 00065 * ::pn_selectable_is_terminal()), it will never be interested in 00066 * events of any kind. When this occurs it should be removed from the 00067 * external event loop and discarded using ::pn_selectable_free(). 00068 */ 00069 typedef struct pn_selectable_t pn_selectable_t; 00070 00071 /** 00072 * Construct a new selectables iterator. 00073 * 00074 * @return a pointer to a new selectables iterator 00075 */ 00076 PN_EXTERN pn_selectables_t *pn_selectables(void); 00077 00078 /** 00079 * Get the next selectable from an iterator. 00080 * 00081 * @param[in] selectables a selectable iterator 00082 * @return the next selectable from the iterator 00083 */ 00084 PN_EXTERN pn_selectable_t *pn_selectables_next(pn_selectables_t *selectables); 00085 00086 /** 00087 * Free a selectables iterator. 00088 * 00089 * @param[in] selectables a selectables iterator (or NULL) 00090 */ 00091 PN_EXTERN void pn_selectables_free(pn_selectables_t *selectables); 00092 00093 /** 00094 * Get the file descriptor associated with a selectable. 00095 * 00096 * @param[in] selectable a selectable object 00097 * @return the file descriptor associated with the selectable 00098 */ 00099 PN_EXTERN pn_socket_t pn_selectable_fd(pn_selectable_t *selectable); 00100 00101 /** 00102 * Get the capacity of a selectable. 00103 * 00104 * A selectable with a positive capacity is interested in being 00105 * notified of read events. A negative capacity indicates that the 00106 * selectable will never be interested in read events ever again. 00107 * 00108 * @param[in] selectable a selectable object 00109 * @return the selectables capacity 00110 */ 00111 PN_EXTERN ssize_t pn_selectable_capacity(pn_selectable_t *selectable); 00112 00113 /** 00114 * Get the number of bytes pending for a selectable. 00115 * 00116 * A selectable with pending bytes is interested in being notified of 00117 * write events. If this value is negative then the selectable will 00118 * never be interested in write events ever again. 00119 * 00120 * @param[in] selectable a selectable object 00121 * @return the number of bytes pending for the selectable 00122 */ 00123 PN_EXTERN ssize_t pn_selectable_pending(pn_selectable_t *selectable); 00124 00125 /** 00126 * Get the next deadline for a selectable. 00127 * 00128 * A selectable with a deadline is interested in being notified when 00129 * that deadline expires. Zero indicates there is currently no 00130 * deadline. 00131 * 00132 * @param[in] selectable a selectable object 00133 * @return the next deadline or zero 00134 */ 00135 PN_EXTERN pn_timestamp_t pn_selectable_deadline(pn_selectable_t *selectable); 00136 00137 /** 00138 * Notify a selectable that the file descriptor is readable. 00139 * 00140 * @param[in] selectable a selectable object 00141 */ 00142 PN_EXTERN void pn_selectable_readable(pn_selectable_t *selectable); 00143 00144 /** 00145 * Notify a selectable that the file descriptor is writable. 00146 * 00147 * @param[in] selectable a selectable object 00148 */ 00149 PN_EXTERN void pn_selectable_writable(pn_selectable_t *selectable); 00150 00151 /** 00152 * Notify a selectable that its deadline has expired. 00153 * 00154 * @param[in] selectable a selectable object 00155 */ 00156 PN_EXTERN void pn_selectable_expired(pn_selectable_t *selectable); 00157 00158 /** 00159 * Check if a selectable is registered. 00160 * 00161 * This flag is set via ::pn_selectable_set_registered() and can be 00162 * used for tracking whether a given selectable has been registerd 00163 * with an external event loop. 00164 * 00165 * @param[in] selectable 00166 * @return true if the selectable is registered 00167 */ 00168 PN_EXTERN bool pn_selectable_is_registered(pn_selectable_t *selectable); 00169 00170 /** 00171 * Set the registered flag for a selectable. 00172 * 00173 * See ::pn_selectable_is_registered() for details. 00174 * 00175 * @param[in] selectable a selectable object 00176 * @param[in] registered the registered flag 00177 */ 00178 PN_EXTERN void pn_selectable_set_registered(pn_selectable_t *selectable, bool registered); 00179 00180 /** 00181 * Check if a selectable is in the terminal state. 00182 * 00183 * A selectable that is in the terminal state will never be interested 00184 * in being notified of events of any kind ever again. Once a 00185 * selectable reaches this state it should be removed from any 00186 * external I/O loops and freed in order to reclaim any resources 00187 * associated with it. 00188 * 00189 * @param[in] selectable a selectable object 00190 * @return true if the selectable is in the terminal state, false otherwise 00191 */ 00192 PN_EXTERN bool pn_selectable_is_terminal(pn_selectable_t *selectable); 00193 00194 /** 00195 * Free a selectable object. 00196 * 00197 * @param[in] selectable a selectable object (or NULL) 00198 */ 00199 PN_EXTERN void pn_selectable_free(pn_selectable_t *selectable); 00200 00201 /** 00202 * @} 00203 */ 00204 00205 #ifdef __cplusplus 00206 } 00207 #endif 00208 00209 #endif /* selectable.h */