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