apr_poll.h revision 251875 
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
35extern "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 */
74typedef 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 */
84typedef 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. */
92typedef union {
93    apr_file_t *f;              /**< file */
94    apr_socket_t *s;            /**< socket */
95} apr_descriptor;
96
97/** @see apr_pollfd_t */
98typedef struct apr_pollfd_t apr_pollfd_t;
99
100/** Poll descriptor set. */
101struct 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 */
116typedef 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 */
147APR_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 */
184APR_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 */
194APR_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 */
222APR_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 */
242APR_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 */
265APR_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 */
276APR_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 */
296APR_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 */
304APR_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 */
310APR_DECLARE(const char *) apr_poll_method_defname(void);
311
312/** Opaque structure used for pollset API */
313typedef 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 */
325APR_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 */
343APR_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 */
366APR_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 */
376APR_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 */
385typedef 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 */
403APR_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
416