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