apr_poll.h revision 269847
1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. 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#ifndef APR_POLL_H 18#define APR_POLL_H 19/** 20 * @file apr_poll.h 21 * @brief APR Poll interface 22 */ 23#include "apr.h" 24#include "apr_pools.h" 25#include "apr_errno.h" 26#include "apr_inherit.h" 27#include "apr_file_io.h" 28#include "apr_network_io.h" 29 30#if APR_HAVE_NETINET_IN_H 31#include <netinet/in.h> 32#endif 33 34#ifdef __cplusplus 35extern "C" { 36#endif /* __cplusplus */ 37 38/** 39 * @defgroup apr_poll Poll Routines 40 * @ingroup APR 41 * @{ 42 */ 43 44/** 45 * @defgroup pollopts Poll options 46 * @ingroup apr_poll 47 * @{ 48 */ 49#define APR_POLLIN 0x001 /**< Can read without blocking */ 50#define APR_POLLPRI 0x002 /**< Priority data available */ 51#define APR_POLLOUT 0x004 /**< Can write without blocking */ 52#define APR_POLLERR 0x010 /**< Pending error */ 53#define APR_POLLHUP 0x020 /**< Hangup occurred */ 54#define APR_POLLNVAL 0x040 /**< Descriptor invalid */ 55/** @} */ 56 57/** 58 * @defgroup pollflags Pollset Flags 59 * @ingroup apr_poll 60 * @{ 61 */ 62#define APR_POLLSET_THREADSAFE 0x001 /**< Adding or removing a descriptor is 63 * thread-safe 64 */ 65#define APR_POLLSET_NOCOPY 0x002 /**< Descriptors passed to apr_pollset_add() 66 * are not copied 67 */ 68#define APR_POLLSET_WAKEABLE 0x004 /**< Poll operations are interruptable by 69 * apr_pollset_wakeup() 70 */ 71#define APR_POLLSET_NODEFAULT 0x010 /**< Do not try to use the default method if 72 * the specified non-default method cannot be 73 * used 74 */ 75/** @} */ 76 77/** 78 * Pollset Methods 79 */ 80typedef enum { 81 APR_POLLSET_DEFAULT, /**< Platform default poll method */ 82 APR_POLLSET_SELECT, /**< Poll uses select method */ 83 APR_POLLSET_KQUEUE, /**< Poll uses kqueue method */ 84 APR_POLLSET_PORT, /**< Poll uses Solaris event port method */ 85 APR_POLLSET_EPOLL, /**< Poll uses epoll method */ 86 APR_POLLSET_POLL, /**< Poll uses poll method */ 87 APR_POLLSET_AIO_MSGQ /**< Poll uses z/OS asio method */ 88} apr_pollset_method_e; 89 90/** Used in apr_pollfd_t to determine what the apr_descriptor is */ 91typedef enum { 92 APR_NO_DESC, /**< nothing here */ 93 APR_POLL_SOCKET, /**< descriptor refers to a socket */ 94 APR_POLL_FILE, /**< descriptor refers to a file */ 95 APR_POLL_LASTDESC /**< @deprecated descriptor is the last one in the list */ 96} apr_datatype_e ; 97 98/** Union of either an APR file or socket. */ 99typedef union { 100 apr_file_t *f; /**< file */ 101 apr_socket_t *s; /**< socket */ 102} apr_descriptor; 103 104/** @see apr_pollfd_t */ 105typedef struct apr_pollfd_t apr_pollfd_t; 106 107/** Poll descriptor set. */ 108struct apr_pollfd_t { 109 apr_pool_t *p; /**< associated pool */ 110 apr_datatype_e desc_type; /**< descriptor type */ 111 apr_int16_t reqevents; /**< requested events */ 112 apr_int16_t rtnevents; /**< returned events */ 113 apr_descriptor desc; /**< @see apr_descriptor */ 114 void *client_data; /**< allows app to associate context */ 115}; 116 117 118/* General-purpose poll API for arbitrarily large numbers of 119 * file descriptors 120 */ 121 122/** Opaque structure used for pollset API */ 123typedef struct apr_pollset_t apr_pollset_t; 124 125/** 126 * Set up a pollset object 127 * @param pollset The pointer in which to return the newly created object 128 * @param size The maximum number of descriptors that this pollset can hold 129 * @param p The pool from which to allocate the pollset 130 * @param flags Optional flags to modify the operation of the pollset. 131 * 132 * @remark If flags contains APR_POLLSET_THREADSAFE, then a pollset is 133 * created on which it is safe to make concurrent calls to 134 * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() 135 * from separate threads. This feature is only supported on some 136 * platforms; the apr_pollset_create() call will fail with 137 * APR_ENOTIMPL on platforms where it is not supported. 138 * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollset is 139 * created with an additional internal pipe object used for the 140 * apr_pollset_wakeup() call. The actual size of pollset is 141 * in that case @a size + 1. This feature is only supported on some 142 * platforms; the apr_pollset_create() call will fail with 143 * APR_ENOTIMPL on platforms where it is not supported. 144 * @remark If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t 145 * structures passed to apr_pollset_add() are not copied and 146 * must have a lifetime at least as long as the pollset. 147 * @remark Some poll methods (including APR_POLLSET_KQUEUE, 148 * APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a 149 * fixed limit on the size of the pollset. For these methods, 150 * the size parameter controls the maximum number of 151 * descriptors that will be returned by a single call to 152 * apr_pollset_poll(). 153 */ 154APR_DECLARE(apr_status_t) apr_pollset_create(apr_pollset_t **pollset, 155 apr_uint32_t size, 156 apr_pool_t *p, 157 apr_uint32_t flags); 158 159/** 160 * Set up a pollset object 161 * @param pollset The pointer in which to return the newly created object 162 * @param size The maximum number of descriptors that this pollset can hold 163 * @param p The pool from which to allocate the pollset 164 * @param flags Optional flags to modify the operation of the pollset. 165 * @param method Poll method to use. See #apr_pollset_method_e. If this 166 * method cannot be used, the default method will be used unless the 167 * APR_POLLSET_NODEFAULT flag has been specified. 168 * 169 * @remark If flags contains APR_POLLSET_THREADSAFE, then a pollset is 170 * created on which it is safe to make concurrent calls to 171 * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() 172 * from separate threads. This feature is only supported on some 173 * platforms; the apr_pollset_create_ex() call will fail with 174 * APR_ENOTIMPL on platforms where it is not supported. 175 * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollset is 176 * created with additional internal pipe object used for the 177 * apr_pollset_wakeup() call. The actual size of pollset is 178 * in that case size + 1. This feature is only supported on some 179 * platforms; the apr_pollset_create_ex() call will fail with 180 * APR_ENOTIMPL on platforms where it is not supported. 181 * @remark If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t 182 * structures passed to apr_pollset_add() are not copied and 183 * must have a lifetime at least as long as the pollset. 184 * @remark Some poll methods (including APR_POLLSET_KQUEUE, 185 * APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a 186 * fixed limit on the size of the pollset. For these methods, 187 * the size parameter controls the maximum number of 188 * descriptors that will be returned by a single call to 189 * apr_pollset_poll(). 190 */ 191APR_DECLARE(apr_status_t) apr_pollset_create_ex(apr_pollset_t **pollset, 192 apr_uint32_t size, 193 apr_pool_t *p, 194 apr_uint32_t flags, 195 apr_pollset_method_e method); 196 197/** 198 * Destroy a pollset object 199 * @param pollset The pollset to destroy 200 */ 201APR_DECLARE(apr_status_t) apr_pollset_destroy(apr_pollset_t *pollset); 202 203/** 204 * Add a socket or file descriptor to a pollset 205 * @param pollset The pollset to which to add the descriptor 206 * @param descriptor The descriptor to add 207 * @remark If you set client_data in the descriptor, that value 208 * will be returned in the client_data field whenever this 209 * descriptor is signalled in apr_pollset_poll(). 210 * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 211 * and thread T1 is blocked in a call to apr_pollset_poll() for 212 * this same pollset that is being modified via apr_pollset_add() 213 * in thread T2, the currently executing apr_pollset_poll() call in 214 * T1 will either: (1) automatically include the newly added descriptor 215 * in the set of descriptors it is watching or (2) return immediately 216 * with APR_EINTR. Option (1) is recommended, but option (2) is 217 * allowed for implementations where option (1) is impossible 218 * or impractical. 219 * @remark If the pollset has been created with APR_POLLSET_NOCOPY, the 220 * apr_pollfd_t structure referenced by descriptor will not be copied 221 * and must have a lifetime at least as long as the pollset. 222 * @remark Do not add the same socket or file descriptor to the same pollset 223 * multiple times, even if the requested events differ for the 224 * different calls to apr_pollset_add(). If the events of interest 225 * for a descriptor change, you must first remove the descriptor 226 * from the pollset with apr_pollset_remove(), then add it again 227 * specifying all requested events. 228 */ 229APR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset, 230 const apr_pollfd_t *descriptor); 231 232/** 233 * Remove a descriptor from a pollset 234 * @param pollset The pollset from which to remove the descriptor 235 * @param descriptor The descriptor to remove 236 * @remark If the descriptor is not found, APR_NOTFOUND is returned. 237 * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 238 * and thread T1 is blocked in a call to apr_pollset_poll() for 239 * this same pollset that is being modified via apr_pollset_remove() 240 * in thread T2, the currently executing apr_pollset_poll() call in 241 * T1 will either: (1) automatically exclude the newly added descriptor 242 * in the set of descriptors it is watching or (2) return immediately 243 * with APR_EINTR. Option (1) is recommended, but option (2) is 244 * allowed for implementations where option (1) is impossible 245 * or impractical. 246 * @remark apr_pollset_remove() cannot be used to remove a subset of requested 247 * events for a descriptor. The reqevents field in the apr_pollfd_t 248 * parameter must contain the same value when removing as when adding. 249 */ 250APR_DECLARE(apr_status_t) apr_pollset_remove(apr_pollset_t *pollset, 251 const apr_pollfd_t *descriptor); 252 253/** 254 * Block for activity on the descriptor(s) in a pollset 255 * @param pollset The pollset to use 256 * @param timeout The amount of time in microseconds to wait. This is a 257 * maximum, not a minimum. If a descriptor is signalled, the 258 * function will return before this time. If timeout is 259 * negative, the function will block until a descriptor is 260 * signalled or until apr_pollset_wakeup() has been called. 261 * @param num Number of signalled descriptors (output parameter) 262 * @param descriptors Array of signalled descriptors (output parameter) 263 * @remark APR_EINTR will be returned if the pollset has been created with 264 * APR_POLLSET_WAKEABLE, apr_pollset_wakeup() has been called while 265 * waiting for activity, and there were no signalled descriptors at the 266 * time of the wakeup call. 267 * @remark Multiple signalled conditions for the same descriptor may be reported 268 * in one or more returned apr_pollfd_t structures, depending on the 269 * implementation. 270 */ 271APR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset, 272 apr_interval_time_t timeout, 273 apr_int32_t *num, 274 const apr_pollfd_t **descriptors); 275 276/** 277 * Interrupt the blocked apr_pollset_poll() call. 278 * @param pollset The pollset to use 279 * @remark If the pollset was not created with APR_POLLSET_WAKEABLE the 280 * return value is APR_EINIT. 281 */ 282APR_DECLARE(apr_status_t) apr_pollset_wakeup(apr_pollset_t *pollset); 283 284/** 285 * Poll the descriptors in the poll structure 286 * @param aprset The poll structure we will be using. 287 * @param numsock The number of descriptors we are polling 288 * @param nsds The number of descriptors signalled (output parameter) 289 * @param timeout The amount of time in microseconds to wait. This is a 290 * maximum, not a minimum. If a descriptor is signalled, the 291 * function will return before this time. If timeout is 292 * negative, the function will block until a descriptor is 293 * signalled or until apr_pollset_wakeup() has been called. 294 * @remark The number of descriptors signalled is returned in the third argument. 295 * This is a blocking call, and it will not return until either a 296 * descriptor has been signalled or the timeout has expired. 297 * @remark The rtnevents field in the apr_pollfd_t array will only be filled- 298 * in if the return value is APR_SUCCESS. 299 */ 300APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock, 301 apr_int32_t *nsds, 302 apr_interval_time_t timeout); 303 304/** 305 * Return a printable representation of the pollset method. 306 * @param pollset The pollset to use 307 */ 308APR_DECLARE(const char *) apr_pollset_method_name(apr_pollset_t *pollset); 309 310/** 311 * Return a printable representation of the default pollset method 312 * (APR_POLLSET_DEFAULT). 313 */ 314APR_DECLARE(const char *) apr_poll_method_defname(void); 315 316/** Opaque structure used for pollcb API */ 317typedef struct apr_pollcb_t apr_pollcb_t; 318 319/** 320 * Set up a pollcb object 321 * @param pollcb The pointer in which to return the newly created object 322 * @param size The maximum number of descriptors that a single _poll can return. 323 * @param p The pool from which to allocate the pollcb 324 * @param flags Optional flags to modify the operation of the pollcb. 325 * 326 * @remark Pollcb is only supported on some platforms; the apr_pollcb_create() 327 * call will fail with APR_ENOTIMPL on platforms where it is not supported. 328 */ 329APR_DECLARE(apr_status_t) apr_pollcb_create(apr_pollcb_t **pollcb, 330 apr_uint32_t size, 331 apr_pool_t *p, 332 apr_uint32_t flags); 333 334/** 335 * Set up a pollcb object 336 * @param pollcb The pointer in which to return the newly created object 337 * @param size The maximum number of descriptors that a single _poll can return. 338 * @param p The pool from which to allocate the pollcb 339 * @param flags Optional flags to modify the operation of the pollcb. 340 * @param method Poll method to use. See #apr_pollset_method_e. If this 341 * method cannot be used, the default method will be used unless the 342 * APR_POLLSET_NODEFAULT flag has been specified. 343 * 344 * @remark Pollcb is only supported on some platforms; the apr_pollcb_create_ex() 345 * call will fail with APR_ENOTIMPL on platforms where it is not supported. 346 */ 347APR_DECLARE(apr_status_t) apr_pollcb_create_ex(apr_pollcb_t **pollcb, 348 apr_uint32_t size, 349 apr_pool_t *p, 350 apr_uint32_t flags, 351 apr_pollset_method_e method); 352 353/** 354 * Add a socket or file descriptor to a pollcb 355 * @param pollcb The pollcb to which to add the descriptor 356 * @param descriptor The descriptor to add 357 * @remark If you set client_data in the descriptor, that value will be 358 * returned in the client_data field whenever this descriptor is 359 * signalled in apr_pollcb_poll(). 360 * @remark Unlike the apr_pollset API, the descriptor is not copied, and users 361 * must retain the memory used by descriptor, as the same pointer will 362 * be returned to them from apr_pollcb_poll. 363 * @remark Do not add the same socket or file descriptor to the same pollcb 364 * multiple times, even if the requested events differ for the 365 * different calls to apr_pollcb_add(). If the events of interest 366 * for a descriptor change, you must first remove the descriptor 367 * from the pollcb with apr_pollcb_remove(), then add it again 368 * specifying all requested events. 369 */ 370APR_DECLARE(apr_status_t) apr_pollcb_add(apr_pollcb_t *pollcb, 371 apr_pollfd_t *descriptor); 372/** 373 * Remove a descriptor from a pollcb 374 * @param pollcb The pollcb from which to remove the descriptor 375 * @param descriptor The descriptor to remove 376 * @remark apr_pollcb_remove() cannot be used to remove a subset of requested 377 * events for a descriptor. The reqevents field in the apr_pollfd_t 378 * parameter must contain the same value when removing as when adding. 379 */ 380APR_DECLARE(apr_status_t) apr_pollcb_remove(apr_pollcb_t *pollcb, 381 apr_pollfd_t *descriptor); 382 383/** Function prototype for pollcb handlers 384 * @param baton Opaque baton passed into apr_pollcb_poll() 385 * @param descriptor Contains the notification for an active descriptor, 386 * the rtnevents member contains what events were triggered 387 * for this descriptor. 388 */ 389typedef apr_status_t (*apr_pollcb_cb_t)(void *baton, apr_pollfd_t *descriptor); 390 391/** 392 * Block for activity on the descriptor(s) in a pollcb 393 * @param pollcb The pollcb to use 394 * @param timeout The amount of time in microseconds to wait. This is a 395 * maximum, not a minimum. If a descriptor is signalled, the 396 * function will return before this time. If timeout is 397 * negative, the function will block until a descriptor is 398 * signalled. 399 * @param func Callback function to call for each active descriptor. 400 * @param baton Opaque baton passed to the callback function. 401 * @remark Multiple signalled conditions for the same descriptor may be reported 402 * in one or more calls to the callback function, depending on the 403 * implementation. 404 */ 405APR_DECLARE(apr_status_t) apr_pollcb_poll(apr_pollcb_t *pollcb, 406 apr_interval_time_t timeout, 407 apr_pollcb_cb_t func, 408 void *baton); 409 410/** @} */ 411 412#ifdef __cplusplus 413} 414#endif 415 416#endif /* ! APR_POLL_H */ 417 418