00001 /* Copyright 2000-2004 The Apache Software Foundation 00002 * 00003 * Licensed under the Apache License, Version 2.0 (the "License"); 00004 * you may not use this file except in compliance with the License. 00005 * You may obtain a copy of the License at 00006 * 00007 * http://www.apache.org/licenses/LICENSE-2.0 00008 * 00009 * Unless required by applicable law or agreed to in writing, software 00010 * distributed under the License is distributed on an "AS IS" BASIS, 00011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00012 * See the License for the specific language governing permissions and 00013 * limitations under the License. 00014 */ 00015 00016 #ifndef APR_POLL_H 00017 #define APR_POLL_H 00018 /** 00019 * @file apr_poll.h 00020 * @brief APR Poll interface 00021 */ 00022 #include "apr.h" 00023 #include "apr_pools.h" 00024 #include "apr_errno.h" 00025 #include "apr_inherit.h" 00026 #include "apr_file_io.h" 00027 #include "apr_network_io.h" 00028 00029 #if APR_HAVE_NETINET_IN_H 00030 #include <netinet/in.h> 00031 #endif 00032 00033 #ifdef __cplusplus 00034 extern "C" { 00035 #endif /* __cplusplus */ 00036 00037 /** 00038 * @defgroup apr_poll Poll Routines 00039 * @ingroup APR 00040 * @{ 00041 */ 00042 00043 /** 00044 * Poll options 00045 */ 00046 #define APR_POLLIN 0x001 /**< Can read without blocking */ 00047 #define APR_POLLPRI 0x002 /**< Priority data available */ 00048 #define APR_POLLOUT 0x004 /**< Can write without blocking */ 00049 #define APR_POLLERR 0x010 /**< Pending error */ 00050 #define APR_POLLHUP 0x020 /**< Hangup occurred */ 00051 #define APR_POLLNVAL 0x040 /**< Descriptior invalid */ 00052 00053 /** 00054 * Pollset Flags 00055 */ 00056 #define APR_POLLSET_THREADSAFE 0x001 /**< Adding or Removing a Descriptor is thread safe */ 00057 00058 /** Used in apr_pollfd_t to determine what the apr_descriptor is */ 00059 typedef enum { 00060 APR_NO_DESC, /**< nothing here */ 00061 APR_POLL_SOCKET, /**< descriptor refers to a socket */ 00062 APR_POLL_FILE, /**< descriptor refers to a file */ 00063 APR_POLL_LASTDESC /**< descriptor is the last one in the list */ 00064 } apr_datatype_e ; 00065 00066 /** Union of either an APR file or socket. */ 00067 typedef union { 00068 apr_file_t *f; /**< file */ 00069 apr_socket_t *s; /**< socket */ 00070 } apr_descriptor; 00071 00072 /** @see apr_pollfd_t */ 00073 typedef struct apr_pollfd_t apr_pollfd_t; 00074 00075 /** Poll descriptor set. */ 00076 struct apr_pollfd_t { 00077 apr_pool_t *p; /**< associated pool */ 00078 apr_datatype_e desc_type; /**< descriptor type */ 00079 apr_int16_t reqevents; /**< requested events */ 00080 apr_int16_t rtnevents; /**< returned events */ 00081 apr_descriptor desc; /**< @see apr_descriptor */ 00082 void *client_data; /**< allows app to associate context */ 00083 }; 00084 00085 00086 /* General-purpose poll API for arbitrarily large numbers of 00087 * file descriptors 00088 */ 00089 00090 /** Opaque structure used for pollset API */ 00091 typedef struct apr_pollset_t apr_pollset_t; 00092 00093 /** 00094 * Setup a pollset object 00095 * @param pollset The pointer in which to return the newly created object 00096 * @param size The maximum number of descriptors that this pollset can hold 00097 * @param p The pool from which to allocate the pollset 00098 * @param flags Optional flags to modify the operation of the pollset. 00099 * 00100 * @remark If flags equals APR_POLLSET_THREADSAFE, then a pollset is 00101 * created on which it is safe to make concurrent calls to 00102 * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() from 00103 * separate threads. This feature is only supported on some 00104 * platforms; the apr_pollset_create() call will fail with 00105 * APR_ENOTIMPL on platforms where it is not supported. 00106 */ 00107 APR_DECLARE(apr_status_t) apr_pollset_create(apr_pollset_t **pollset, 00108 apr_uint32_t size, 00109 apr_pool_t *p, 00110 apr_uint32_t flags); 00111 00112 /** 00113 * Destroy a pollset object 00114 * @param pollset The pollset to destroy 00115 */ 00116 APR_DECLARE(apr_status_t) apr_pollset_destroy(apr_pollset_t *pollset); 00117 00118 /** 00119 * Add a socket or file descriptor to a pollset 00120 * @param pollset The pollset to which to add the descriptor 00121 * @param descriptor The descriptor to add 00122 * @remark If you set client_data in the descriptor, that value 00123 * will be returned in the client_data field whenever this 00124 * descriptor is signalled in apr_pollset_poll(). 00125 */ 00126 APR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset, 00127 const apr_pollfd_t *descriptor); 00128 00129 /** 00130 * Remove a descriptor from a pollset 00131 * @param pollset The pollset from which to remove the descriptor 00132 * @param descriptor The descriptor to remove 00133 */ 00134 APR_DECLARE(apr_status_t) apr_pollset_remove(apr_pollset_t *pollset, 00135 const apr_pollfd_t *descriptor); 00136 00137 /** 00138 * Block for activity on the descriptor(s) in a pollset 00139 * @param pollset The pollset to use 00140 * @param timeout Timeout in microseconds 00141 * @param num Number of signalled descriptors (output parameter) 00142 * @param descriptors Array of signalled descriptors (output parameter) 00143 */ 00144 APR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset, 00145 apr_interval_time_t timeout, 00146 apr_int32_t *num, 00147 const apr_pollfd_t **descriptors); 00148 00149 00150 /** 00151 * Poll the sockets in the poll structure 00152 * @param aprset The poll structure we will be using. 00153 * @param numsock The number of sockets we are polling 00154 * @param nsds The number of sockets signalled. 00155 * @param timeout The amount of time in microseconds to wait. This is 00156 * a maximum, not a minimum. If a socket is signalled, we 00157 * will wake up before this time. A negative number means 00158 * wait until a socket is signalled. 00159 * @remark The number of sockets signalled is returned in the third argument. 00160 * This is a blocking call, and it will not return until either a 00161 * socket has been signalled, or the timeout has expired. 00162 */ 00163 APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock, 00164 apr_int32_t *nsds, 00165 apr_interval_time_t timeout); 00166 00167 /** @} */ 00168 00169 00170 #ifdef __cplusplus 00171 } 00172 #endif 00173 00174 #endif /* ! APR_POLL_H */ 00175