apr_poll.h revision 251875
1251875Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251875Speter * contributor license agreements. See the NOTICE file distributed with 3251875Speter * this work for additional information regarding copyright ownership. 4251875Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251875Speter * (the "License"); you may not use this file except in compliance with 6251875Speter * the License. You may obtain a copy of the License at 7251875Speter * 8251875Speter * http://www.apache.org/licenses/LICENSE-2.0 9251875Speter * 10251875Speter * Unless required by applicable law or agreed to in writing, software 11251875Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251875Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251875Speter * See the License for the specific language governing permissions and 14251875Speter * limitations under the License. 15251875Speter */ 16251875Speter 17251875Speter#ifndef APR_POLL_H 18251875Speter#define APR_POLL_H 19251875Speter/** 20251875Speter * @file apr_poll.h 21251875Speter * @brief APR Poll interface 22251875Speter */ 23251875Speter#include "apr.h" 24251875Speter#include "apr_pools.h" 25251875Speter#include "apr_errno.h" 26251875Speter#include "apr_inherit.h" 27251875Speter#include "apr_file_io.h" 28251875Speter#include "apr_network_io.h" 29251875Speter 30251875Speter#if APR_HAVE_NETINET_IN_H 31251875Speter#include <netinet/in.h> 32251875Speter#endif 33251875Speter 34251875Speter#ifdef __cplusplus 35251875Speterextern "C" { 36251875Speter#endif /* __cplusplus */ 37251875Speter 38251875Speter/** 39251875Speter * @defgroup apr_poll Poll Routines 40251875Speter * @ingroup APR 41251875Speter * @{ 42251875Speter */ 43251875Speter 44251875Speter/** 45251875Speter * Poll options 46251875Speter */ 47251875Speter#define APR_POLLIN 0x001 /**< Can read without blocking */ 48251875Speter#define APR_POLLPRI 0x002 /**< Priority data available */ 49251875Speter#define APR_POLLOUT 0x004 /**< Can write without blocking */ 50251875Speter#define APR_POLLERR 0x010 /**< Pending error */ 51251875Speter#define APR_POLLHUP 0x020 /**< Hangup occurred */ 52251875Speter#define APR_POLLNVAL 0x040 /**< Descriptor invalid */ 53251875Speter 54251875Speter/** 55251875Speter * Pollset Flags 56251875Speter */ 57251875Speter#define APR_POLLSET_THREADSAFE 0x001 /**< Adding or removing a descriptor is 58251875Speter * thread-safe 59251875Speter */ 60251875Speter#define APR_POLLSET_NOCOPY 0x002 /**< Descriptors passed to apr_pollset_add() 61251875Speter * are not copied 62251875Speter */ 63251875Speter#define APR_POLLSET_WAKEABLE 0x004 /**< Poll operations are interruptable by 64251875Speter * apr_pollset_wakeup() 65251875Speter */ 66251875Speter#define APR_POLLSET_NODEFAULT 0x010 /**< Do not try to use the default method if 67251875Speter * the specified non-default method cannot be 68251875Speter * used 69251875Speter */ 70251875Speter 71251875Speter/** 72251875Speter * Pollset Methods 73251875Speter */ 74251875Spetertypedef enum { 75251875Speter APR_POLLSET_DEFAULT, /**< Platform default poll method */ 76251875Speter APR_POLLSET_SELECT, /**< Poll uses select method */ 77251875Speter APR_POLLSET_KQUEUE, /**< Poll uses kqueue method */ 78251875Speter APR_POLLSET_PORT, /**< Poll uses Solaris event port method */ 79251875Speter APR_POLLSET_EPOLL, /**< Poll uses epoll method */ 80251875Speter APR_POLLSET_POLL /**< Poll uses poll method */ 81251875Speter} apr_pollset_method_e; 82251875Speter 83251875Speter/** Used in apr_pollfd_t to determine what the apr_descriptor is */ 84251875Spetertypedef enum { 85251875Speter APR_NO_DESC, /**< nothing here */ 86251875Speter APR_POLL_SOCKET, /**< descriptor refers to a socket */ 87251875Speter APR_POLL_FILE, /**< descriptor refers to a file */ 88251875Speter APR_POLL_LASTDESC /**< @deprecated descriptor is the last one in the list */ 89251875Speter} apr_datatype_e ; 90251875Speter 91251875Speter/** Union of either an APR file or socket. */ 92251875Spetertypedef union { 93251875Speter apr_file_t *f; /**< file */ 94251875Speter apr_socket_t *s; /**< socket */ 95251875Speter} apr_descriptor; 96251875Speter 97251875Speter/** @see apr_pollfd_t */ 98251875Spetertypedef struct apr_pollfd_t apr_pollfd_t; 99251875Speter 100251875Speter/** Poll descriptor set. */ 101251875Speterstruct apr_pollfd_t { 102251875Speter apr_pool_t *p; /**< associated pool */ 103251875Speter apr_datatype_e desc_type; /**< descriptor type */ 104251875Speter apr_int16_t reqevents; /**< requested events */ 105251875Speter apr_int16_t rtnevents; /**< returned events */ 106251875Speter apr_descriptor desc; /**< @see apr_descriptor */ 107251875Speter void *client_data; /**< allows app to associate context */ 108251875Speter}; 109251875Speter 110251875Speter 111251875Speter/* General-purpose poll API for arbitrarily large numbers of 112251875Speter * file descriptors 113251875Speter */ 114251875Speter 115251875Speter/** Opaque structure used for pollset API */ 116251875Spetertypedef struct apr_pollset_t apr_pollset_t; 117251875Speter 118251875Speter/** 119251875Speter * Set up a pollset object 120251875Speter * @param pollset The pointer in which to return the newly created object 121251875Speter * @param size The maximum number of descriptors that this pollset can hold 122251875Speter * @param p The pool from which to allocate the pollset 123251875Speter * @param flags Optional flags to modify the operation of the pollset. 124251875Speter * 125251875Speter * @remark If flags contains APR_POLLSET_THREADSAFE, then a pollset is 126251875Speter * created on which it is safe to make concurrent calls to 127251875Speter * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() 128251875Speter * from separate threads. This feature is only supported on some 129251875Speter * platforms; the apr_pollset_create() call will fail with 130251875Speter * APR_ENOTIMPL on platforms where it is not supported. 131251875Speter * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollset is 132251875Speter * created with an additional internal pipe object used for the 133251875Speter * apr_pollset_wakeup() call. The actual size of pollset is 134251875Speter * in that case size + 1. This feature is only supported on some 135251875Speter * platforms; the apr_pollset_create() call will fail with 136251875Speter * APR_ENOTIMPL on platforms where it is not supported. 137251875Speter * @remark If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t 138251875Speter * structures passed to apr_pollset_add() are not copied and 139251875Speter * must have a lifetime at least as long as the pollset. 140251875Speter * @remark Some poll methods (including APR_POLLSET_KQUEUE, 141251875Speter * APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a 142251875Speter * fixed limit on the size of the pollset. For these methods, 143251875Speter * the size parameter controls the maximum number of 144251875Speter * descriptors that will be returned by a single call to 145251875Speter * apr_pollset_poll(). 146251875Speter */ 147251875SpeterAPR_DECLARE(apr_status_t) apr_pollset_create(apr_pollset_t **pollset, 148251875Speter apr_uint32_t size, 149251875Speter apr_pool_t *p, 150251875Speter apr_uint32_t flags); 151251875Speter 152251875Speter/** 153251875Speter * Set up a pollset object 154251875Speter * @param pollset The pointer in which to return the newly created object 155251875Speter * @param size The maximum number of descriptors that this pollset can hold 156251875Speter * @param p The pool from which to allocate the pollset 157251875Speter * @param flags Optional flags to modify the operation of the pollset. 158251875Speter * @param method Poll method to use. See #apr_pollset_method_e. If this 159251875Speter * method cannot be used, the default method will be used unless the 160251875Speter * APR_POLLSET_NODEFAULT flag has been specified. 161251875Speter * 162251875Speter * @remark If flags contains APR_POLLSET_THREADSAFE, then a pollset is 163251875Speter * created on which it is safe to make concurrent calls to 164251875Speter * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() 165251875Speter * from separate threads. This feature is only supported on some 166251875Speter * platforms; the apr_pollset_create_ex() call will fail with 167251875Speter * APR_ENOTIMPL on platforms where it is not supported. 168251875Speter * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollset is 169251875Speter * created with additional internal pipe object used for the 170251875Speter * apr_pollset_wakeup() call. The actual size of pollset is 171251875Speter * in that case size + 1. This feature is only supported on some 172251875Speter * platforms; the apr_pollset_create_ex() call will fail with 173251875Speter * APR_ENOTIMPL on platforms where it is not supported. 174251875Speter * @remark If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t 175251875Speter * structures passed to apr_pollset_add() are not copied and 176251875Speter * must have a lifetime at least as long as the pollset. 177251875Speter * @remark Some poll methods (including APR_POLLSET_KQUEUE, 178251875Speter * APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a 179251875Speter * fixed limit on the size of the pollset. For these methods, 180251875Speter * the size parameter controls the maximum number of 181251875Speter * descriptors that will be returned by a single call to 182251875Speter * apr_pollset_poll(). 183251875Speter */ 184251875SpeterAPR_DECLARE(apr_status_t) apr_pollset_create_ex(apr_pollset_t **pollset, 185251875Speter apr_uint32_t size, 186251875Speter apr_pool_t *p, 187251875Speter apr_uint32_t flags, 188251875Speter apr_pollset_method_e method); 189251875Speter 190251875Speter/** 191251875Speter * Destroy a pollset object 192251875Speter * @param pollset The pollset to destroy 193251875Speter */ 194251875SpeterAPR_DECLARE(apr_status_t) apr_pollset_destroy(apr_pollset_t *pollset); 195251875Speter 196251875Speter/** 197251875Speter * Add a socket or file descriptor to a pollset 198251875Speter * @param pollset The pollset to which to add the descriptor 199251875Speter * @param descriptor The descriptor to add 200251875Speter * @remark If you set client_data in the descriptor, that value 201251875Speter * will be returned in the client_data field whenever this 202251875Speter * descriptor is signalled in apr_pollset_poll(). 203251875Speter * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 204251875Speter * and thread T1 is blocked in a call to apr_pollset_poll() for 205251875Speter * this same pollset that is being modified via apr_pollset_add() 206251875Speter * in thread T2, the currently executing apr_pollset_poll() call in 207251875Speter * T1 will either: (1) automatically include the newly added descriptor 208251875Speter * in the set of descriptors it is watching or (2) return immediately 209251875Speter * with APR_EINTR. Option (1) is recommended, but option (2) is 210251875Speter * allowed for implementations where option (1) is impossible 211251875Speter * or impractical. 212251875Speter * @remark If the pollset has been created with APR_POLLSET_NOCOPY, the 213251875Speter * apr_pollfd_t structure referenced by descriptor will not be copied 214251875Speter * and must have a lifetime at least as long as the pollset. 215251875Speter * @remark Do not add the same socket or file descriptor to the same pollset 216251875Speter * multiple times, even if the requested events differ for the 217251875Speter * different calls to apr_pollset_add(). If the events of interest 218251875Speter * for a descriptor change, you must first remove the descriptor 219251875Speter * from the pollset with apr_pollset_remove(), then add it again 220251875Speter * specifying all requested events. 221251875Speter */ 222251875SpeterAPR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset, 223251875Speter const apr_pollfd_t *descriptor); 224251875Speter 225251875Speter/** 226251875Speter * Remove a descriptor from a pollset 227251875Speter * @param pollset The pollset from which to remove the descriptor 228251875Speter * @param descriptor The descriptor to remove 229251875Speter * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 230251875Speter * and thread T1 is blocked in a call to apr_pollset_poll() for 231251875Speter * this same pollset that is being modified via apr_pollset_remove() 232251875Speter * in thread T2, the currently executing apr_pollset_poll() call in 233251875Speter * T1 will either: (1) automatically exclude the newly added descriptor 234251875Speter * in the set of descriptors it is watching or (2) return immediately 235251875Speter * with APR_EINTR. Option (1) is recommended, but option (2) is 236251875Speter * allowed for implementations where option (1) is impossible 237251875Speter * or impractical. 238251875Speter * @remark apr_pollset_remove() cannot be used to remove a subset of requested 239251875Speter * events for a descriptor. The reqevents field in the apr_pollfd_t 240251875Speter * parameter must contain the same value when removing as when adding. 241251875Speter */ 242251875SpeterAPR_DECLARE(apr_status_t) apr_pollset_remove(apr_pollset_t *pollset, 243251875Speter const apr_pollfd_t *descriptor); 244251875Speter 245251875Speter/** 246251875Speter * Block for activity on the descriptor(s) in a pollset 247251875Speter * @param pollset The pollset to use 248251875Speter * @param timeout The amount of time in microseconds to wait. This is a 249251875Speter * maximum, not a minimum. If a descriptor is signalled, the 250251875Speter * function will return before this time. If timeout is 251251875Speter * negative, the function will block until a descriptor is 252251875Speter * signalled or until apr_pollset_wakeup() has been called. 253251875Speter * @param num Number of signalled descriptors (output parameter) 254251875Speter * @param descriptors Array of signalled descriptors (output parameter) 255251875Speter * @remark APR_EINTR will be returned if the pollset has been created with 256251875Speter * APR_POLLSET_WAKEABLE, apr_pollset_wakeup() has been called while 257251875Speter * waiting for activity, and there were no signalled descriptors at the 258251875Speter * time of the wakeup call. 259251875Speter * @remark Multiple signalled conditions for the same descriptor may be reported 260251875Speter * in one or more returned apr_pollfd_t structures, depending on the 261251875Speter * implementation. 262251875Speter * @bug With versions 1.4.2 and prior on Windows, a call with no descriptors 263251875Speter * and timeout will return immediately with the wrong error code. 264251875Speter */ 265251875SpeterAPR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset, 266251875Speter apr_interval_time_t timeout, 267251875Speter apr_int32_t *num, 268251875Speter const apr_pollfd_t **descriptors); 269251875Speter 270251875Speter/** 271251875Speter * Interrupt the blocked apr_pollset_poll() call. 272251875Speter * @param pollset The pollset to use 273251875Speter * @remark If the pollset was not created with APR_POLLSET_WAKEABLE the 274251875Speter * return value is APR_EINIT. 275251875Speter */ 276251875SpeterAPR_DECLARE(apr_status_t) apr_pollset_wakeup(apr_pollset_t *pollset); 277251875Speter 278251875Speter/** 279251875Speter * Poll the descriptors in the poll structure 280251875Speter * @param aprset The poll structure we will be using. 281251875Speter * @param numsock The number of descriptors we are polling 282251875Speter * @param nsds The number of descriptors signalled (output parameter) 283251875Speter * @param timeout The amount of time in microseconds to wait. This is a 284251875Speter * maximum, not a minimum. If a descriptor is signalled, the 285251875Speter * function will return before this time. If timeout is 286251875Speter * negative, the function will block until a descriptor is 287251875Speter * signalled or until apr_pollset_wakeup() has been called. 288251875Speter * @remark The number of descriptors signalled is returned in the third argument. 289251875Speter * This is a blocking call, and it will not return until either a 290251875Speter * descriptor has been signalled or the timeout has expired. 291251875Speter * @remark The rtnevents field in the apr_pollfd_t array will only be filled- 292251875Speter * in if the return value is APR_SUCCESS. 293251875Speter * @bug With versions 1.4.2 and prior on Windows, a call with no descriptors 294251875Speter * and timeout will return immediately with the wrong error code. 295251875Speter */ 296251875SpeterAPR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock, 297251875Speter apr_int32_t *nsds, 298251875Speter apr_interval_time_t timeout); 299251875Speter 300251875Speter/** 301251875Speter * Return a printable representation of the pollset method. 302251875Speter * @param pollset The pollset to use 303251875Speter */ 304251875SpeterAPR_DECLARE(const char *) apr_pollset_method_name(apr_pollset_t *pollset); 305251875Speter 306251875Speter/** 307251875Speter * Return a printable representation of the default pollset method 308251875Speter * (APR_POLLSET_DEFAULT). 309251875Speter */ 310251875SpeterAPR_DECLARE(const char *) apr_poll_method_defname(void); 311251875Speter 312251875Speter/** Opaque structure used for pollset API */ 313251875Spetertypedef struct apr_pollcb_t apr_pollcb_t; 314251875Speter 315251875Speter/** 316251875Speter * Set up a pollcb object 317251875Speter * @param pollcb The pointer in which to return the newly created object 318251875Speter * @param size The maximum number of descriptors that a single _poll can return. 319251875Speter * @param p The pool from which to allocate the pollcb 320251875Speter * @param flags Optional flags to modify the operation of the pollcb. 321251875Speter * 322251875Speter * @remark Pollcb is only supported on some platforms; the apr_pollcb_create() 323251875Speter * call will fail with APR_ENOTIMPL on platforms where it is not supported. 324251875Speter */ 325251875SpeterAPR_DECLARE(apr_status_t) apr_pollcb_create(apr_pollcb_t **pollcb, 326251875Speter apr_uint32_t size, 327251875Speter apr_pool_t *p, 328251875Speter apr_uint32_t flags); 329251875Speter 330251875Speter/** 331251875Speter * Set up a pollcb object 332251875Speter * @param pollcb The pointer in which to return the newly created object 333251875Speter * @param size The maximum number of descriptors that a single _poll can return. 334251875Speter * @param p The pool from which to allocate the pollcb 335251875Speter * @param flags Optional flags to modify the operation of the pollcb. 336251875Speter * @param method Poll method to use. See #apr_pollset_method_e. If this 337251875Speter * method cannot be used, the default method will be used unless the 338251875Speter * APR_POLLSET_NODEFAULT flag has been specified. 339251875Speter * 340251875Speter * @remark Pollcb is only supported on some platforms; the apr_pollcb_create_ex() 341251875Speter * call will fail with APR_ENOTIMPL on platforms where it is not supported. 342251875Speter */ 343251875SpeterAPR_DECLARE(apr_status_t) apr_pollcb_create_ex(apr_pollcb_t **pollcb, 344251875Speter apr_uint32_t size, 345251875Speter apr_pool_t *p, 346251875Speter apr_uint32_t flags, 347251875Speter apr_pollset_method_e method); 348251875Speter 349251875Speter/** 350251875Speter * Add a socket or file descriptor to a pollcb 351251875Speter * @param pollcb The pollcb to which to add the descriptor 352251875Speter * @param descriptor The descriptor to add 353251875Speter * @remark If you set client_data in the descriptor, that value will be 354251875Speter * returned in the client_data field whenever this descriptor is 355251875Speter * signalled in apr_pollcb_poll(). 356251875Speter * @remark Unlike the apr_pollset API, the descriptor is not copied, and users 357251875Speter * must retain the memory used by descriptor, as the same pointer will 358251875Speter * be returned to them from apr_pollcb_poll. 359251875Speter * @remark Do not add the same socket or file descriptor to the same pollcb 360251875Speter * multiple times, even if the requested events differ for the 361251875Speter * different calls to apr_pollcb_add(). If the events of interest 362251875Speter * for a descriptor change, you must first remove the descriptor 363251875Speter * from the pollcb with apr_pollcb_remove(), then add it again 364251875Speter * specifying all requested events. 365251875Speter */ 366251875SpeterAPR_DECLARE(apr_status_t) apr_pollcb_add(apr_pollcb_t *pollcb, 367251875Speter apr_pollfd_t *descriptor); 368251875Speter/** 369251875Speter * Remove a descriptor from a pollcb 370251875Speter * @param pollcb The pollcb from which to remove the descriptor 371251875Speter * @param descriptor The descriptor to remove 372251875Speter * @remark apr_pollcb_remove() cannot be used to remove a subset of requested 373251875Speter * events for a descriptor. The reqevents field in the apr_pollfd_t 374251875Speter * parameter must contain the same value when removing as when adding. 375251875Speter */ 376251875SpeterAPR_DECLARE(apr_status_t) apr_pollcb_remove(apr_pollcb_t *pollcb, 377251875Speter apr_pollfd_t *descriptor); 378251875Speter 379251875Speter/** Function prototype for pollcb handlers 380251875Speter * @param baton Opaque baton passed into apr_pollcb_poll() 381251875Speter * @param descriptor Contains the notification for an active descriptor, 382251875Speter * the rtnevents member contains what events were triggered 383251875Speter * for this descriptor. 384251875Speter */ 385251875Spetertypedef apr_status_t (*apr_pollcb_cb_t)(void *baton, apr_pollfd_t *descriptor); 386251875Speter 387251875Speter/** 388251875Speter * Block for activity on the descriptor(s) in a pollcb 389251875Speter * @param pollcb The pollcb to use 390251875Speter * @param timeout The amount of time in microseconds to wait. This is a 391251875Speter * maximum, not a minimum. If a descriptor is signalled, the 392251875Speter * function will return before this time. If timeout is 393251875Speter * negative, the function will block until a descriptor is 394251875Speter * signalled. 395251875Speter * @param func Callback function to call for each active descriptor. 396251875Speter * @param baton Opaque baton passed to the callback function. 397251875Speter * @remark Multiple signalled conditions for the same descriptor may be reported 398251875Speter * in one or more calls to the callback function, depending on the 399251875Speter * implementation. 400251875Speter * @bug With versions 1.4.2 and prior on Windows, a call with no descriptors 401251875Speter * and timeout will return immediately with the wrong error code. 402251875Speter */ 403251875SpeterAPR_DECLARE(apr_status_t) apr_pollcb_poll(apr_pollcb_t *pollcb, 404251875Speter apr_interval_time_t timeout, 405251875Speter apr_pollcb_cb_t func, 406251875Speter void *baton); 407251875Speter 408251875Speter/** @} */ 409251875Speter 410251875Speter#ifdef __cplusplus 411251875Speter} 412251875Speter#endif 413251875Speter 414251875Speter#endif /* ! APR_POLL_H */ 415251875Speter 416