Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

apr_poll.h

Go to the documentation of this file.
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 

Generated on Sat Apr 2 21:46:29 2005 for Apache Portable Runtime by  doxygen 1.3.9.1