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 * Poll options 00046 */ 00047 #define APR_POLLIN 0x001 /**< Can read without blocking */ 00048 #define APR_POLLPRI 0x002 /**< Priority data available */ 00049 #define APR_POLLOUT 0x004 /**< Can write without blocking */ 00050 #define APR_POLLERR 0x010 /**< Pending error */ 00051 #define APR_POLLHUP 0x020 /**< Hangup occurred */ 00052 #define APR_POLLNVAL 0x040 /**< Descriptior invalid */ 00053 00054 /** 00055 * Pollset Flags 00056 */ 00057 #define APR_POLLSET_THREADSAFE 0x001 /**< Adding or Removing a Descriptor is thread safe */ 00058 #define APR_POLLSET_NOCOPY 0x002 /**< Descriptors passed to apr_pollset_create() are not copied */ 00059 #define APR_POLLSET_WAKEABLE 0x004 /**< Pollset poll operation is interruptable */ 00060 00061 /** Used in apr_pollfd_t to determine what the apr_descriptor is */ 00062 typedef enum { 00063 APR_NO_DESC, /**< nothing here */ 00064 APR_POLL_SOCKET, /**< descriptor refers to a socket */ 00065 APR_POLL_FILE, /**< descriptor refers to a file */ 00066 APR_POLL_LASTDESC /**< @deprecated descriptor is the last one in the list */ 00067 } apr_datatype_e ; 00068 00069 /** Union of either an APR file or socket. */ 00070 typedef union { 00071 apr_file_t *f; /**< file */ 00072 apr_socket_t *s; /**< socket */ 00073 } apr_descriptor; 00074 00075 /** @see apr_pollfd_t */ 00076 typedef struct apr_pollfd_t apr_pollfd_t; 00077 00078 /** Poll descriptor set. */ 00079 struct apr_pollfd_t { 00080 apr_pool_t *p; /**< associated pool */ 00081 apr_datatype_e desc_type; /**< descriptor type */ 00082 apr_int16_t reqevents; /**< requested events */ 00083 apr_int16_t rtnevents; /**< returned events */ 00084 apr_descriptor desc; /**< @see apr_descriptor */ 00085 void *client_data; /**< allows app to associate context */ 00086 }; 00087 00088 00089 /* General-purpose poll API for arbitrarily large numbers of 00090 * file descriptors 00091 */ 00092 00093 /** Opaque structure used for pollset API */ 00094 typedef struct apr_pollset_t apr_pollset_t; 00095 00096 /** 00097 * Setup a pollset object 00098 * @param pollset The pointer in which to return the newly created object 00099 * @param size The maximum number of descriptors that this pollset can hold 00100 * @param p The pool from which to allocate the pollset 00101 * @param flags Optional flags to modify the operation of the pollset. 00102 * 00103 * @remark If flags equals APR_POLLSET_THREADSAFE, then a pollset is 00104 * created on which it is safe to make concurrent calls to 00105 * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() 00106 * from separate threads. This feature is only supported on some 00107 * platforms; the apr_pollset_create() call will fail with 00108 * APR_ENOTIMPL on platforms where it is not supported. 00109 * @remark If flags contain APR_POLLSET_WAKEABLE, then a pollset is 00110 * created with additional internal pipe object used for 00111 * apr_pollset_wakeup() call. The actual size of pollset is 00112 * in that case size + 1. This feature is only supported on some 00113 * platforms; the apr_pollset_create() call will fail with 00114 * APR_ENOTIMPL on platforms where it is not supported. 00115 */ 00116 APR_DECLARE(apr_status_t) apr_pollset_create(apr_pollset_t **pollset, 00117 apr_uint32_t size, 00118 apr_pool_t *p, 00119 apr_uint32_t flags); 00120 00121 /** 00122 * Destroy a pollset object 00123 * @param pollset The pollset to destroy 00124 */ 00125 APR_DECLARE(apr_status_t) apr_pollset_destroy(apr_pollset_t *pollset); 00126 00127 /** 00128 * Add a socket or file descriptor to a pollset 00129 * @param pollset The pollset to which to add the descriptor 00130 * @param descriptor The descriptor to add 00131 * @remark If you set client_data in the descriptor, that value 00132 * will be returned in the client_data field whenever this 00133 * descriptor is signalled in apr_pollset_poll(). 00134 * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 00135 * and thread T1 is blocked in a call to apr_pollset_poll() for 00136 * this same pollset that is being modified via apr_pollset_add() 00137 * in thread T2, the currently executing apr_pollset_poll() call in 00138 * T1 will either: (1) automatically include the newly added descriptor 00139 * in the set of descriptors it is watching or (2) return immediately 00140 * with APR_EINTR. Option (1) is recommended, but option (2) is 00141 * allowed for implementations where option (1) is impossible 00142 * or impractical. 00143 */ 00144 APR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset, 00145 const apr_pollfd_t *descriptor); 00146 00147 /** 00148 * Remove a descriptor from a pollset 00149 * @param pollset The pollset from which to remove the descriptor 00150 * @param descriptor The descriptor to remove 00151 * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 00152 * and thread T1 is blocked in a call to apr_pollset_poll() for 00153 * this same pollset that is being modified via apr_pollset_remove() 00154 * in thread T2, the currently executing apr_pollset_poll() call in 00155 * T1 will either: (1) automatically exclude the newly added descriptor 00156 * in the set of descriptors it is watching or (2) return immediately 00157 * with APR_EINTR. Option (1) is recommended, but option (2) is 00158 * allowed for implementations where option (1) is impossible 00159 * or impractical. 00160 */ 00161 APR_DECLARE(apr_status_t) apr_pollset_remove(apr_pollset_t *pollset, 00162 const apr_pollfd_t *descriptor); 00163 00164 /** 00165 * Block for activity on the descriptor(s) in a pollset 00166 * @param pollset The pollset to use 00167 * @param timeout Timeout in microseconds 00168 * @param num Number of signalled descriptors (output parameter) 00169 * @param descriptors Array of signalled descriptors (output parameter) 00170 * @remark If the pollset has been created with APR_POLLSET_WAKEABLE 00171 * and the wakeup has been called while waiting for activity 00172 * return value is APR_EINTR in case there was no signaled 00173 * descriptors at the time of wakeup call. 00174 */ 00175 APR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset, 00176 apr_interval_time_t timeout, 00177 apr_int32_t *num, 00178 const apr_pollfd_t **descriptors); 00179 00180 /** 00181 * Interrupt the blocked apr_pollset_poll call. 00182 * @param pollset The pollset to use 00183 * @remark If the pollset was not created with APR_POLLSET_WAKEABLE the 00184 * return value is APR_EINIT. 00185 */ 00186 APR_DECLARE(apr_status_t) apr_pollset_wakeup(apr_pollset_t *pollset); 00187 00188 /** 00189 * Poll the descriptors in the poll structure 00190 * @param aprset The poll structure we will be using. 00191 * @param numsock The number of descriptors we are polling 00192 * @param nsds The number of descriptors signalled (output parameter) 00193 * @param timeout The amount of time in microseconds to wait. This is 00194 * a maximum, not a minimum. If a descriptor is signalled, we 00195 * will wake up before this time. A negative number means 00196 * wait until a descriptor is signalled. 00197 * @remark The number of descriptors signalled is returned in the third argument. 00198 * This is a blocking call, and it will not return until either a 00199 * descriptor has been signalled, or the timeout has expired. 00200 * @remark The rtnevents field in the apr_pollfd_t array will only be filled- 00201 * in if the return value is APR_SUCCESS. 00202 */ 00203 APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock, 00204 apr_int32_t *nsds, 00205 apr_interval_time_t timeout); 00206 00207 /** Opaque structure used for pollset API */ 00208 typedef struct apr_pollcb_t apr_pollcb_t; 00209 00210 /** 00211 * Setup a pollcb object 00212 * @param pollcb The pointer in which to return the newly created object 00213 * @param size The maximum number of descriptors that a single _poll can return. 00214 * @param p The pool from which to allocate the pollcb 00215 * @param flags Optional flags to modify the operation of the pollcb. 00216 * 00217 * @remark Pollcb is only supported on some platforms; the apr_pollcb_create() 00218 * call will fail with APR_ENOTIMPL on platforms where it is not supported. 00219 */ 00220 APR_DECLARE(apr_status_t) apr_pollcb_create(apr_pollcb_t **pollcb, 00221 apr_uint32_t size, 00222 apr_pool_t *pool, 00223 apr_uint32_t flags); 00224 00225 /** 00226 * Add a socket or file descriptor to a pollcb 00227 * @param pollcb The pollcb to which to add the descriptor 00228 * @param descriptor The descriptor to add 00229 * @remark If you set client_data in the descriptor, that value 00230 * will be returned in the client_data field whenever this 00231 * descriptor is signalled in apr_pollcb_poll(). 00232 * @remark Unlike the apr_pollset API, the descriptor is not copied, and users 00233 * must retain the memory used by descriptor, as the same pointer will be 00234 * returned to them from apr_pollcb_poll. 00235 */ 00236 APR_DECLARE(apr_status_t) apr_pollcb_add(apr_pollcb_t *pollcb, 00237 apr_pollfd_t *descriptor); 00238 /** 00239 * Remove a descriptor from a pollcb 00240 * @param pollcb The pollcb from which to remove the descriptor 00241 * @param descriptor The descriptor to remove 00242 */ 00243 APR_DECLARE(apr_status_t) apr_pollcb_remove(apr_pollcb_t *pollcb, 00244 apr_pollfd_t *descriptor); 00245 00246 /** Function prototype for pollcb handlers 00247 * @param baton Opaque baton passed into apr_pollcb_poll 00248 * @param descriptor Contains the notification for an active descriptor, 00249 * the rtnevents member contains what events were triggered 00250 * for this descriptor. 00251 */ 00252 typedef apr_status_t (*apr_pollcb_cb_t)(void *baton, apr_pollfd_t *descriptor); 00253 00254 /** 00255 * Block for activity on the descriptor(s) in a pollcb 00256 * @param pollcb The pollcb to use 00257 * @param timeout Timeout in microseconds 00258 * @param func Callback function to call for each active socket 00259 * @param baton Opaque baton passed to the callback function. 00260 */ 00261 APR_DECLARE(apr_status_t) apr_pollcb_poll(apr_pollcb_t *pollcb, 00262 apr_interval_time_t timeout, 00263 apr_pollcb_cb_t func, 00264 void *baton); 00265 00266 /** @} */ 00267 00268 #ifdef __cplusplus 00269 } 00270 #endif 00271 00272 #endif /* ! APR_POLL_H */ 00273
1.5.6