include/apr-0/apr_poll.h

   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  * @defgroup apr_poll_opt Poll options
  46  * @{
  47  */
  48 #define APR_POLLIN    0x001     /**< Can read without blocking */
  49 #define APR_POLLPRI   0x002     /**< Priority data available */
  50 #define APR_POLLOUT   0x004     /**< Can write without blocking */
  51 #define APR_POLLERR   0x010     /**< Pending error */
  52 #define APR_POLLHUP   0x020     /**< Hangup occurred */
  53 #define APR_POLLNVAL  0x040     /**< Descriptior invalid */
  54 /** @} */
  55
  56 /** Used in apr_pollfd_t to determine what the apr_descriptor is */
  57 typedef enum {
  58     APR_NO_DESC,                /**< nothing here */
  59     APR_POLL_SOCKET,            /**< descriptor refers to a socket */
  60     APR_POLL_FILE,              /**< descriptor refers to a file */
  61     APR_POLL_LASTDESC           /**< descriptor is the last one in the list */
  62 } apr_datatype_e ;
  63
  64 /** Union of either an APR file or socket. */
  65 typedef union {
  66     apr_file_t *f;              /**< file */
  67     apr_socket_t *s;            /**< socket */
  68 } apr_descriptor;
  69
  70 /** @see apr_pollfd_t */
  71 typedef struct apr_pollfd_t apr_pollfd_t;
  72
  73 /** Poll descriptor set. */
  74 struct apr_pollfd_t {
  75     apr_pool_t *p;              /**< associated pool */
  76     apr_datatype_e desc_type;   /**< descriptor type */
  77     apr_int16_t reqevents;      /**< requested events */
  78     apr_int16_t rtnevents;      /**< returned events */
  79     apr_descriptor desc;        /**< @see apr_descriptor */
  80     void *client_data;          /**< allows app to associate context */
  81 };
  82
  83 /**
  84  * Setup the memory required for poll to operate properly
  85  * @param new_poll The poll structure to be used.
  86  * @param num The number of socket descriptors to be polled.
  87  * @param cont The pool to operate on.
  88  * @deprecated This function is deprecated, APR applications should control the pollset memory themselves.
  89  */
  90 APR_DECLARE(apr_status_t) apr_poll_setup(apr_pollfd_t **new_poll,
  91                                          apr_int32_t num,
  92                                          apr_pool_t *cont);
  93
  94 /**
  95  * Poll the sockets in the poll structure
  96  * @param aprset The poll structure we will be using.
  97  * @param numsock The number of sockets we are polling
  98  * @param nsds The number of sockets signalled.
  99  * @param timeout The amount of time in microseconds to wait.  This is
 100  *                a maximum, not a minimum.  If a socket is signalled, we
 101  *                will wake up before this time.  A negative number means
 102  *                wait until a socket is signalled.
 103  * @remark
 104  * <PRE>
 105  * The number of sockets signalled is returned in the second argument.
 106  *
 107  *        This is a blocking call, and it will not return until either a
 108  *        socket has been signalled, or the timeout has expired.
 109  * </PRE>
 110  */
 111 APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock,
 112                                    apr_int32_t *nsds,
 113                                    apr_interval_time_t timeout);
 114
 115 /**
 116  * Add a socket to the poll structure.
 117  * @param aprset The poll structure we will be using.
 118  * @param sock The socket to add to the current poll structure.
 119  * @param event The events to look for when we do the poll.  One of:
 120  * <PRE>
 121  *            APR_POLLIN       signal if read will not block
 122  *            APR_POLLPRI      signal if prioirty data is availble to be read
 123  *            APR_POLLOUT      signal if write will not block
 124  * </PRE>
 125  * @deprecated This function is deprecated, APR applications should control the pollset memory themselves.
 126  */
 127 APR_DECLARE(apr_status_t) apr_poll_socket_add(apr_pollfd_t *aprset,
 128                                               apr_socket_t *sock,
 129                                               apr_int16_t event);
 130
 131 /**
 132  * Modify a socket in the poll structure with mask.
 133  * @param aprset The poll structure we will be using.
 134  * @param sock The socket to modify in poll structure.
 135  * @param events The events to stop looking for during the poll.  One of:
 136  * <PRE>
 137  *            APR_POLLIN       signal if read will not block
 138  *            APR_POLLPRI      signal if priority data is available to be read
 139  *            APR_POLLOUT      signal if write will not block
 140  * </PRE>
 141  * @deprecated This function is deprecated, APR applications should control the pollset memory themselves.
 142  */
 143 APR_DECLARE(apr_status_t) apr_poll_socket_mask(apr_pollfd_t *aprset,
 144                                                apr_socket_t *sock,
 145                                                apr_int16_t events);
 146 /**
 147  * Remove a socket from the poll structure.
 148  * @param aprset The poll structure we will be using.
 149  * @param sock The socket to remove from the current poll structure.
 150  * @deprecated This function is deprecated, APR applications should control the pollset memory themselves.
 151  */
 152 APR_DECLARE(apr_status_t) apr_poll_socket_remove(apr_pollfd_t *aprset,
 153                                                  apr_socket_t *sock);
 154
 155 /**
 156  * Clear all events in the poll structure.
 157  * @param aprset The poll structure we will be using.
 158  * @param events The events to clear from all sockets.  One of:
 159  * <PRE>
 160  *            APR_POLLIN       signal if read will not block
 161  *            APR_POLLPRI      signal if priority data is available to be read
 162  *            APR_POLLOUT      signal if write will not block
 163  * </PRE>
 164  * @deprecated This function is deprecated, APR applications should control the pollset memory themselves.
 165  */
 166 APR_DECLARE(apr_status_t) apr_poll_socket_clear(apr_pollfd_t *aprset,
 167                                                  apr_int16_t events);
 168
 169 /**
 170  * Get the return events for the specified socket.
 171  * @param event The returned events for the socket.  One of:
 172  * <PRE>
 173  *            APR_POLLIN       Data is available to be read
 174  *            APR_POLLPRI      Priority data is availble to be read
 175  *            APR_POLLOUT      Write will succeed
 176  *            APR_POLLERR      An error occurred on the socket
 177  *            APR_POLLHUP      The connection has been terminated
 178  *            APR_POLLNVAL     This is an invalid socket to poll on.
 179  *                             Socket not open.
 180  * </PRE>
 181  * @param sock The socket we wish to get information about.
 182  * @param aprset The poll structure we will be using.
 183  * @deprecated This function is deprecated, APR applications should control the pollset memory themselves.
 184  */
 185 APR_DECLARE(apr_status_t) apr_poll_revents_get(apr_int16_t *event,
 186                                           apr_socket_t *sock,
 187                                           apr_pollfd_t *aprset);
 188
 189 /* General-purpose poll API for arbitrarily large numbers of
 190  * file descriptors
 191  */
 192
 193 /** Opaque structure used for pollset API */
 194 typedef struct apr_pollset_t apr_pollset_t;
 195
 196 /**
 197  * Setup a pollset object
 198  * @param pollset  The pointer in which to return the newly created object
 199  * @param size The maximum number of descriptors that this pollset can hold
 200  * @param p The pool from which to allocate the pollset
 201  * @param flags Optional flags to modify the operation of the pollset
 202  *              (reserved for future expansion)
 203  */
 204 APR_DECLARE(apr_status_t) apr_pollset_create(apr_pollset_t **pollset,
 205                                              apr_uint32_t size,
 206                                              apr_pool_t *p,
 207                                              apr_uint32_t flags);
 208
 209 /**
 210  * Destroy a pollset object
 211  * @param pollset The pollset to destroy
 212  */
 213 APR_DECLARE(apr_status_t) apr_pollset_destroy(apr_pollset_t *pollset);
 214
 215 /**
 216  * Add a socket or file descriptor to a pollset
 217  * @param pollset The pollset to which to add the descriptor
 218  * @param descriptor The descriptor to add
 219  * @remark If you set client_data in the descriptor, that value
 220  *         will be returned in the client_data field whenever this
 221  *         descriptor is signalled in apr_pollset_poll().
 222  */
 223 APR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset,
 224                                           const apr_pollfd_t *descriptor);
 225
 226 /**
 227  * Remove a descriptor from a pollset
 228  * @param pollset The pollset from which to remove the descriptor
 229  * @param descriptor The descriptor to remove
 230  */
 231 APR_DECLARE(apr_status_t) apr_pollset_remove(apr_pollset_t *pollset,
 232                                              const apr_pollfd_t *descriptor);
 233
 234 /**
 235  * Block for activity on the descriptor(s) in a pollset
 236  * @param pollset The pollset to use
 237  * @param timeout Timeout in microseconds
 238  * @param num Number of signalled descriptors (output parameter)
 239  * @param descriptors Array of signalled descriptors (output parameter)
 240  */
 241 APR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset,
 242                                            apr_interval_time_t timeout,
 243                                            apr_int32_t *num,
 244                                            const apr_pollfd_t **descriptors);
 245
 246 /** @} */
 247
 248 #ifdef __cplusplus
 249 }
 250 #endif
 251
 252 #endif  /* ! APR_POLL_H */
 253