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/event.h> 00028 #include <proton/io.h> 00029 #include <proton/type_compat.h> 00030 00031 #ifdef __cplusplus 00032 extern "C" { 00033 #endif 00034 00035 /** 00036 * @file 00037 * 00038 * The selectable API provides an interface for integration with third 00039 * party event loops. 00040 * 00041 * @defgroup selectable Selectable 00042 * @{ 00043 */ 00044 00045 /** 00046 * An iterator for selectables. 00047 */ 00048 typedef pn_iterator_t pn_selectables_t; 00049 00050 /** 00051 * A selectable object provides an interface that can be used to 00052 * incorporate proton's I/O into third party event loops. 00053 * 00054 * Every selectable is associated with exactly one file descriptor. 00055 * Selectables may be interested in three kinds of events, read 00056 * events, write events, and timer events. A selectable will express 00057 * its interest in these events through the ::pn_selectable_capacity(), 00058 * ::pn_selectable_pending(), and ::pn_selectable_deadline() calls. 00059 * 00060 * When a read, write, or timer event occurs, the selectable must be 00061 * notified by calling ::pn_selectable_readable(), 00062 * ::pn_selectable_writable(), and ::pn_selectable_expired() as 00063 * appropriate. 00064 * 00065 * Once a selectable reaches a terminal state (see 00066 * ::pn_selectable_is_terminal()), it will never be interested in 00067 * events of any kind. When this occurs it should be removed from the 00068 * external event loop and discarded using ::pn_selectable_free(). 00069 */ 00070 typedef struct pn_selectable_t pn_selectable_t; 00071 00072 /** 00073 * Construct a new selectables iterator. 00074 * 00075 * @return a pointer to a new selectables iterator 00076 */ 00077 PN_EXTERN pn_selectables_t *pn_selectables(void); 00078 00079 /** 00080 * Get the next selectable from an iterator. 00081 * 00082 * @param[in] selectables a selectable iterator 00083 * @return the next selectable from the iterator 00084 */ 00085 PN_EXTERN pn_selectable_t *pn_selectables_next(pn_selectables_t *selectables); 00086 00087 /** 00088 * Free a selectables iterator. 00089 * 00090 * @param[in] selectables a selectables iterator (or NULL) 00091 */ 00092 PN_EXTERN void pn_selectables_free(pn_selectables_t *selectables); 00093 00094 PN_EXTERN pn_selectable_t *pn_selectable(void); 00095 00096 PN_EXTERN void pn_selectable_on_readable(pn_selectable_t *sel, void (*readable)(pn_selectable_t *)); 00097 PN_EXTERN void pn_selectable_on_writable(pn_selectable_t *sel, void (*writable)(pn_selectable_t *)); 00098 PN_EXTERN void pn_selectable_on_expired(pn_selectable_t *sel, void (*expired)(pn_selectable_t *)); 00099 PN_EXTERN void pn_selectable_on_error(pn_selectable_t *sel, void (*error)(pn_selectable_t *)); 00100 PN_EXTERN void pn_selectable_on_release(pn_selectable_t *sel, void (*release)(pn_selectable_t *)); 00101 PN_EXTERN void pn_selectable_on_finalize(pn_selectable_t *sel, void (*finalize)(pn_selectable_t *)); 00102 00103 PN_EXTERN pn_record_t *pn_selectable_attachments(pn_selectable_t *sel); 00104 00105 /** 00106 * Get the file descriptor associated with a selectable. 00107 * 00108 * @param[in] selectable a selectable object 00109 * @return the file descriptor associated with the selectable 00110 */ 00111 PN_EXTERN pn_socket_t pn_selectable_get_fd(pn_selectable_t *selectable); 00112 00113 /** 00114 * Set the file descriptor associated with a selectable. 00115 * 00116 * @param[in] selectable a selectable object 00117 * @param[in] fd the file descriptor 00118 */ 00119 PN_EXTERN void pn_selectable_set_fd(pn_selectable_t *selectable, pn_socket_t fd); 00120 00121 /** 00122 * Check if a selectable is interested in readable events. 00123 * 00124 * @param[in] selectable a selectable object 00125 * @return true iff the selectable is interested in read events 00126 */ 00127 PN_EXTERN bool pn_selectable_is_reading(pn_selectable_t *selectable); 00128 00129 PN_EXTERN void pn_selectable_set_reading(pn_selectable_t *sel, bool reading); 00130 00131 /** 00132 * Check if a selectable is interested in writable events. 00133 * 00134 * @param[in] selectable a selectable object 00135 * @return true iff the selectable is interested in writable events 00136 */ 00137 PN_EXTERN bool pn_selectable_is_writing(pn_selectable_t *selectable); 00138 00139 PN_EXTERN void pn_selectable_set_writing(pn_selectable_t *sel, bool writing); 00140 00141 /** 00142 * Get the next deadline for a selectable. 00143 * 00144 * A selectable with a deadline is interested in being notified when 00145 * that deadline expires. Zero indicates there is currently no 00146 * deadline. 00147 * 00148 * @param[in] selectable a selectable object 00149 * @return the next deadline or zero 00150 */ 00151 PN_EXTERN pn_timestamp_t pn_selectable_get_deadline(pn_selectable_t *selectable); 00152 00153 PN_EXTERN void pn_selectable_set_deadline(pn_selectable_t *sel, pn_timestamp_t deadline); 00154 00155 /** 00156 * Notify a selectable that the file descriptor is readable. 00157 * 00158 * @param[in] selectable a selectable object 00159 */ 00160 PN_EXTERN void pn_selectable_readable(pn_selectable_t *selectable); 00161 00162 /** 00163 * Notify a selectable that the file descriptor is writable. 00164 * 00165 * @param[in] selectable a selectable object 00166 */ 00167 PN_EXTERN void pn_selectable_writable(pn_selectable_t *selectable); 00168 00169 /** 00170 * Notify a selectable that there is an error on the file descriptor. 00171 * 00172 * @param[in] selectable a selectable object 00173 */ 00174 PN_EXTERN void pn_selectable_error(pn_selectable_t *selectable); 00175 00176 /** 00177 * Notify a selectable that its deadline has expired. 00178 * 00179 * @param[in] selectable a selectable object 00180 */ 00181 PN_EXTERN void pn_selectable_expired(pn_selectable_t *selectable); 00182 00183 /** 00184 * Check if a selectable is registered. 00185 * 00186 * This flag is set via ::pn_selectable_set_registered() and can be 00187 * used for tracking whether a given selectable has been registerd 00188 * with an external event loop. 00189 * 00190 * @param[in] selectable 00191 * @return true if the selectable is registered 00192 */ 00193 PN_EXTERN bool pn_selectable_is_registered(pn_selectable_t *selectable); 00194 00195 /** 00196 * Set the registered flag for a selectable. 00197 * 00198 * See ::pn_selectable_is_registered() for details. 00199 * 00200 * @param[in] selectable a selectable object 00201 * @param[in] registered the registered flag 00202 */ 00203 PN_EXTERN void pn_selectable_set_registered(pn_selectable_t *selectable, bool registered); 00204 00205 /** 00206 * Check if a selectable is in the terminal state. 00207 * 00208 * A selectable that is in the terminal state will never be interested 00209 * in being notified of events of any kind ever again. Once a 00210 * selectable reaches this state it should be removed from any 00211 * external I/O loops and freed in order to reclaim any resources 00212 * associated with it. 00213 * 00214 * @param[in] selectable a selectable object 00215 * @return true if the selectable is in the terminal state, false otherwise 00216 */ 00217 PN_EXTERN bool pn_selectable_is_terminal(pn_selectable_t *selectable); 00218 00219 /** 00220 * Terminate a selectable. 00221 * 00222 * @param[in] selectable a selectable object 00223 */ 00224 PN_EXTERN void pn_selectable_terminate(pn_selectable_t *selectable); 00225 00226 PN_EXTERN void pn_selectable_release(pn_selectable_t *selectable); 00227 00228 /** 00229 * Free a selectable object. 00230 * 00231 * @param[in] selectable a selectable object (or NULL) 00232 */ 00233 PN_EXTERN void pn_selectable_free(pn_selectable_t *selectable); 00234 00235 /** 00236 * Configure a selectable with a set of callbacks that emit readable, 00237 * writable, and expired events into the supplied collector. 00238 * 00239 * @param[in] selectable a selectable objet 00240 */ 00241 PN_EXTERN void pn_selectable_collect(pn_selectable_t *selectable, pn_collector_t *collector); 00242 00243 /** 00244 * @} 00245 */ 00246 00247 #ifdef __cplusplus 00248 } 00249 #endif 00250 00251 #endif /* selectable.h */