apr_poll.h
Go to the documentation of this file.00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_POLL_H 00018 #define APR_POLL_H 00019 /** 00020 * @file apr_poll.h 00021 * @brief APR Poll interface 00022 */ 00023 #include "apr.h" 00024 #include "apr_pools.h" 00025 #include "apr_errno.h" 00026 #include "apr_inherit.h" 00027 #include "apr_file_io.h" 00028 #include "apr_network_io.h" 00029 00030 #if APR_HAVE_NETINET_IN_H 00031 #include <netinet/in.h> 00032 #endif 00033 00034 #ifdef __cplusplus 00035 extern "C" { 00036 #endif /* __cplusplus */ 00037 00038 /** 00039 * @defgroup apr_poll Poll Routines 00040 * @ingroup APR 00041 * @{ 00042 */ 00043 00044 /** 00045 * @defgroup pollopts Poll options 00046 * @ingroup apr_poll 00047 * @{ 00048 */ 00049 #define APR_POLLIN 0x001 /**< Can read without blocking */ 00050 #define APR_POLLPRI 0x002 /**< Priority data available */ 00051 #define APR_POLLOUT 0x004 /**< Can write without blocking */ 00052 #define APR_POLLERR 0x010 /**< Pending error */ 00053 #define APR_POLLHUP 0x020 /**< Hangup occurred */ 00054 #define APR_POLLNVAL 0x040 /**< Descriptor invalid */ 00055 /** @} */ 00056 00057 /** 00058 * @defgroup pollflags Pollset Flags 00059 * @ingroup apr_poll 00060 * @{ 00061 */ 00062 #define APR_POLLSET_THREADSAFE 0x001 /**< Adding or removing a descriptor is 00063 * thread-safe 00064 */ 00065 #define APR_POLLSET_NOCOPY 0x002 /**< Descriptors passed to apr_pollset_add() 00066 * are not copied 00067 */ 00068 #define APR_POLLSET_WAKEABLE 0x004 /**< Poll operations are interruptable by 00069 * apr_pollset_wakeup() 00070 */ 00071 #define APR_POLLSET_NODEFAULT 0x010 /**< Do not try to use the default method if 00072 * the specified non-default method cannot be 00073 * used 00074 */ 00075 /** @} */ 00076 00077 /** 00078 * Pollset Methods 00079 */ 00080 typedef enum { 00081 APR_POLLSET_DEFAULT, /**< Platform default poll method */ 00082 APR_POLLSET_SELECT, /**< Poll uses select method */ 00083 APR_POLLSET_KQUEUE, /**< Poll uses kqueue method */ 00084 APR_POLLSET_PORT, /**< Poll uses Solaris event port method */ 00085 APR_POLLSET_EPOLL, /**< Poll uses epoll method */ 00086 APR_POLLSET_POLL, /**< Poll uses poll method */ 00087 APR_POLLSET_AIO_MSGQ /**< Poll uses z/OS asio method */ 00088 } apr_pollset_method_e; 00089 00090 /** Used in apr_pollfd_t to determine what the apr_descriptor is */ 00091 typedef enum { 00092 APR_NO_DESC, /**< nothing here */ 00093 APR_POLL_SOCKET, /**< descriptor refers to a socket */ 00094 APR_POLL_FILE, /**< descriptor refers to a file */ 00095 APR_POLL_LASTDESC /**< @deprecated descriptor is the last one in the list */ 00096 } apr_datatype_e ; 00097 00098 /** Union of either an APR file or socket. */ 00099 typedef union { 00100 apr_file_t *f; /**< file */ 00101 apr_socket_t *s; /**< socket */ 00102 } apr_descriptor; 00103 00104 /** @see apr_pollfd_t */ 00105 typedef struct apr_pollfd_t apr_pollfd_t; 00106 00107 /** Poll descriptor set. */ 00108 struct apr_pollfd_t { 00109 apr_pool_t *p; /**< associated pool */ 00110 apr_datatype_e desc_type; /**< descriptor type */ 00111 apr_int16_t reqevents; /**< requested events */ 00112 apr_int16_t rtnevents; /**< returned events */ 00113 apr_descriptor desc; /**< @see apr_descriptor */ 00114 void *client_data; /**< allows app to associate context */ 00115 }; 00116 00117 00118 /* General-purpose poll API for arbitrarily large numbers of 00119 * file descriptors 00120 */ 00121 00122 /** Opaque structure used for pollset API */ 00123 typedef struct apr_pollset_t apr_pollset_t; 00124 00125 /** 00126 * Set up a pollset object 00127 * @param pollset The pointer in which to return the newly created object 00128 * @param size The maximum number of descriptors that this pollset can hold 00129 * @param p The pool from which to allocate the pollset 00130 * @param flags Optional flags to modify the operation of the pollset. 00131 * 00132 * @remark If flags contains APR_POLLSET_THREADSAFE, then a pollset is 00133 * created on which it is safe to make concurrent calls to 00134 * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() 00135 * from separate threads. This feature is only supported on some 00136 * platforms; the apr_pollset_create() call will fail with 00137 * APR_ENOTIMPL on platforms where it is not supported. 00138 * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollset is 00139 * created with an additional internal pipe object used for the 00140 * apr_pollset_wakeup() call. The actual size of pollset is 00141 * in that case @a size + 1. This feature is only supported on some 00142 * platforms; the apr_pollset_create() call will fail with 00143 * APR_ENOTIMPL on platforms where it is not supported. 00144 * @remark If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t 00145 * structures passed to apr_pollset_add() are not copied and 00146 * must have a lifetime at least as long as the pollset. 00147 * @remark Some poll methods (including APR_POLLSET_KQUEUE, 00148 * APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a 00149 * fixed limit on the size of the pollset. For these methods, 00150 * the size parameter controls the maximum number of 00151 * descriptors that will be returned by a single call to 00152 * apr_pollset_poll(). 00153 */ 00154 APR_DECLARE(apr_status_t) apr_pollset_create(apr_pollset_t **pollset, 00155 apr_uint32_t size, 00156 apr_pool_t *p, 00157 apr_uint32_t flags); 00158 00159 /** 00160 * Set up a pollset object 00161 * @param pollset The pointer in which to return the newly created object 00162 * @param size The maximum number of descriptors that this pollset can hold 00163 * @param p The pool from which to allocate the pollset 00164 * @param flags Optional flags to modify the operation of the pollset. 00165 * @param method Poll method to use. See #apr_pollset_method_e. If this 00166 * method cannot be used, the default method will be used unless the 00167 * APR_POLLSET_NODEFAULT flag has been specified. 00168 * 00169 * @remark If flags contains APR_POLLSET_THREADSAFE, then a pollset is 00170 * created on which it is safe to make concurrent calls to 00171 * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() 00172 * from separate threads. This feature is only supported on some 00173 * platforms; the apr_pollset_create_ex() call will fail with 00174 * APR_ENOTIMPL on platforms where it is not supported. 00175 * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollset is 00176 * created with additional internal pipe object used for the 00177 * apr_pollset_wakeup() call. The actual size of pollset is 00178 * in that case size + 1. This feature is only supported on some 00179 * platforms; the apr_pollset_create_ex() call will fail with 00180 * APR_ENOTIMPL on platforms where it is not supported. 00181 * @remark If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t 00182 * structures passed to apr_pollset_add() are not copied and 00183 * must have a lifetime at least as long as the pollset. 00184 * @remark Some poll methods (including APR_POLLSET_KQUEUE, 00185 * APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a 00186 * fixed limit on the size of the pollset. For these methods, 00187 * the size parameter controls the maximum number of 00188 * descriptors that will be returned by a single call to 00189 * apr_pollset_poll(). 00190 */ 00191 APR_DECLARE(apr_status_t) apr_pollset_create_ex(apr_pollset_t **pollset, 00192 apr_uint32_t size, 00193 apr_pool_t *p, 00194 apr_uint32_t flags, 00195 apr_pollset_method_e method); 00196 00197 /** 00198 * Destroy a pollset object 00199 * @param pollset The pollset to destroy 00200 */ 00201 APR_DECLARE(apr_status_t) apr_pollset_destroy(apr_pollset_t *pollset); 00202 00203 /** 00204 * Add a socket or file descriptor to a pollset 00205 * @param pollset The pollset to which to add the descriptor 00206 * @param descriptor The descriptor to add 00207 * @remark If you set client_data in the descriptor, that value 00208 * will be returned in the client_data field whenever this 00209 * descriptor is signalled in apr_pollset_poll(). 00210 * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 00211 * and thread T1 is blocked in a call to apr_pollset_poll() for 00212 * this same pollset that is being modified via apr_pollset_add() 00213 * in thread T2, the currently executing apr_pollset_poll() call in 00214 * T1 will either: (1) automatically include the newly added descriptor 00215 * in the set of descriptors it is watching or (2) return immediately 00216 * with APR_EINTR. Option (1) is recommended, but option (2) is 00217 * allowed for implementations where option (1) is impossible 00218 * or impractical. 00219 * @remark If the pollset has been created with APR_POLLSET_NOCOPY, the 00220 * apr_pollfd_t structure referenced by descriptor will not be copied 00221 * and must have a lifetime at least as long as the pollset. 00222 * @remark Do not add the same socket or file descriptor to the same pollset 00223 * multiple times, even if the requested events differ for the 00224 * different calls to apr_pollset_add(). If the events of interest 00225 * for a descriptor change, you must first remove the descriptor 00226 * from the pollset with apr_pollset_remove(), then add it again 00227 * specifying all requested events. 00228 */ 00229 APR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset, 00230 const apr_pollfd_t *descriptor); 00231 00232 /** 00233 * Remove a descriptor from a pollset 00234 * @param pollset The pollset from which to remove the descriptor 00235 * @param descriptor The descriptor to remove 00236 * @remark If the descriptor is not found, APR_NOTFOUND is returned. 00237 * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 00238 * and thread T1 is blocked in a call to apr_pollset_poll() for 00239 * this same pollset that is being modified via apr_pollset_remove() 00240 * in thread T2, the currently executing apr_pollset_poll() call in 00241 * T1 will either: (1) automatically exclude the newly added descriptor 00242 * in the set of descriptors it is watching or (2) return immediately 00243 * with APR_EINTR. Option (1) is recommended, but option (2) is 00244 * allowed for implementations where option (1) is impossible 00245 * or impractical. 00246 * @remark apr_pollset_remove() cannot be used to remove a subset of requested 00247 * events for a descriptor. The reqevents field in the apr_pollfd_t 00248 * parameter must contain the same value when removing as when adding. 00249 */ 00250 APR_DECLARE(apr_status_t) apr_pollset_remove(apr_pollset_t *pollset, 00251 const apr_pollfd_t *descriptor); 00252 00253 /** 00254 * Block for activity on the descriptor(s) in a pollset 00255 * @param pollset The pollset to use 00256 * @param timeout The amount of time in microseconds to wait. This is a 00257 * maximum, not a minimum. If a descriptor is signalled, the 00258 * function will return before this time. If timeout is 00259 * negative, the function will block until a descriptor is 00260 * signalled or until apr_pollset_wakeup() has been called. 00261 * @param num Number of signalled descriptors (output parameter) 00262 * @param descriptors Array of signalled descriptors (output parameter) 00263 * @remark APR_EINTR will be returned if the pollset has been created with 00264 * APR_POLLSET_WAKEABLE, apr_pollset_wakeup() has been called while 00265 * waiting for activity, and there were no signalled descriptors at the 00266 * time of the wakeup call. 00267 * @remark Multiple signalled conditions for the same descriptor may be reported 00268 * in one or more returned apr_pollfd_t structures, depending on the 00269 * implementation. 00270 */ 00271 APR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset, 00272 apr_interval_time_t timeout, 00273 apr_int32_t *num, 00274 const apr_pollfd_t **descriptors); 00275 00276 /** 00277 * Interrupt the blocked apr_pollset_poll() call. 00278 * @param pollset The pollset to use 00279 * @remark If the pollset was not created with APR_POLLSET_WAKEABLE the 00280 * return value is APR_EINIT. 00281 */ 00282 APR_DECLARE(apr_status_t) apr_pollset_wakeup(apr_pollset_t *pollset); 00283 00284 /** 00285 * Poll the descriptors in the poll structure 00286 * @param aprset The poll structure we will be using. 00287 * @param numsock The number of descriptors we are polling 00288 * @param nsds The number of descriptors signalled (output parameter) 00289 * @param timeout The amount of time in microseconds to wait. This is a 00290 * maximum, not a minimum. If a descriptor is signalled, the 00291 * function will return before this time. If timeout is 00292 * negative, the function will block until a descriptor is 00293 * signalled or until apr_pollset_wakeup() has been called. 00294 * @remark The number of descriptors signalled is returned in the third argument. 00295 * This is a blocking call, and it will not return until either a 00296 * descriptor has been signalled or the timeout has expired. 00297 * @remark The rtnevents field in the apr_pollfd_t array will only be filled- 00298 * in if the return value is APR_SUCCESS. 00299 */ 00300 APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock, 00301 apr_int32_t *nsds, 00302 apr_interval_time_t timeout); 00303 00304 /** 00305 * Return a printable representation of the pollset method. 00306 * @param pollset The pollset to use 00307 */ 00308 APR_DECLARE(const char *) apr_pollset_method_name(apr_pollset_t *pollset); 00309 00310 /** 00311 * Return a printable representation of the default pollset method 00312 * (APR_POLLSET_DEFAULT). 00313 */ 00314 APR_DECLARE(const char *) apr_poll_method_defname(void); 00315 00316 /** Opaque structure used for pollcb API */ 00317 typedef struct apr_pollcb_t apr_pollcb_t; 00318 00319 /** 00320 * Set up a pollcb object 00321 * @param pollcb The pointer in which to return the newly created object 00322 * @param size The maximum number of descriptors that a single _poll can return. 00323 * @param p The pool from which to allocate the pollcb 00324 * @param flags Optional flags to modify the operation of the pollcb. 00325 * 00326 * @remark Pollcb is only supported on some platforms; the apr_pollcb_create() 00327 * call will fail with APR_ENOTIMPL on platforms where it is not supported. 00328 */ 00329 APR_DECLARE(apr_status_t) apr_pollcb_create(apr_pollcb_t **pollcb, 00330 apr_uint32_t size, 00331 apr_pool_t *p, 00332 apr_uint32_t flags); 00333 00334 /** 00335 * Set up a pollcb object 00336 * @param pollcb The pointer in which to return the newly created object 00337 * @param size The maximum number of descriptors that a single _poll can return. 00338 * @param p The pool from which to allocate the pollcb 00339 * @param flags Optional flags to modify the operation of the pollcb. 00340 * @param method Poll method to use. See #apr_pollset_method_e. If this 00341 * method cannot be used, the default method will be used unless the 00342 * APR_POLLSET_NODEFAULT flag has been specified. 00343 * 00344 * @remark Pollcb is only supported on some platforms; the apr_pollcb_create_ex() 00345 * call will fail with APR_ENOTIMPL on platforms where it is not supported. 00346 */ 00347 APR_DECLARE(apr_status_t) apr_pollcb_create_ex(apr_pollcb_t **pollcb, 00348 apr_uint32_t size, 00349 apr_pool_t *p, 00350 apr_uint32_t flags, 00351 apr_pollset_method_e method); 00352 00353 /** 00354 * Add a socket or file descriptor to a pollcb 00355 * @param pollcb The pollcb to which to add the descriptor 00356 * @param descriptor The descriptor to add 00357 * @remark If you set client_data in the descriptor, that value will be 00358 * returned in the client_data field whenever this descriptor is 00359 * signalled in apr_pollcb_poll(). 00360 * @remark Unlike the apr_pollset API, the descriptor is not copied, and users 00361 * must retain the memory used by descriptor, as the same pointer will 00362 * be returned to them from apr_pollcb_poll. 00363 * @remark Do not add the same socket or file descriptor to the same pollcb 00364 * multiple times, even if the requested events differ for the 00365 * different calls to apr_pollcb_add(). If the events of interest 00366 * for a descriptor change, you must first remove the descriptor 00367 * from the pollcb with apr_pollcb_remove(), then add it again 00368 * specifying all requested events. 00369 */ 00370 APR_DECLARE(apr_status_t) apr_pollcb_add(apr_pollcb_t *pollcb, 00371 apr_pollfd_t *descriptor); 00372 /** 00373 * Remove a descriptor from a pollcb 00374 * @param pollcb The pollcb from which to remove the descriptor 00375 * @param descriptor The descriptor to remove 00376 * @remark apr_pollcb_remove() cannot be used to remove a subset of requested 00377 * events for a descriptor. The reqevents field in the apr_pollfd_t 00378 * parameter must contain the same value when removing as when adding. 00379 */ 00380 APR_DECLARE(apr_status_t) apr_pollcb_remove(apr_pollcb_t *pollcb, 00381 apr_pollfd_t *descriptor); 00382 00383 /** Function prototype for pollcb handlers 00384 * @param baton Opaque baton passed into apr_pollcb_poll() 00385 * @param descriptor Contains the notification for an active descriptor, 00386 * the rtnevents member contains what events were triggered 00387 * for this descriptor. 00388 */ 00389 typedef apr_status_t (*apr_pollcb_cb_t)(void *baton, apr_pollfd_t *descriptor); 00390 00391 /** 00392 * Block for activity on the descriptor(s) in a pollcb 00393 * @param pollcb The pollcb to use 00394 * @param timeout The amount of time in microseconds to wait. This is a 00395 * maximum, not a minimum. If a descriptor is signalled, the 00396 * function will return before this time. If timeout is 00397 * negative, the function will block until a descriptor is 00398 * signalled. 00399 * @param func Callback function to call for each active descriptor. 00400 * @param baton Opaque baton passed to the callback function. 00401 * @remark Multiple signalled conditions for the same descriptor may be reported 00402 * in one or more calls to the callback function, depending on the 00403 * implementation. 00404 */ 00405 APR_DECLARE(apr_status_t) apr_pollcb_poll(apr_pollcb_t *pollcb, 00406 apr_interval_time_t timeout, 00407 apr_pollcb_cb_t func, 00408 void *baton); 00409 00410 /** @} */ 00411 00412 #ifdef __cplusplus 00413 } 00414 #endif 00415 00416 #endif /* ! APR_POLL_H */ 00417
