Apache Portable Runtime
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
apr_poll.h
Go to the documentation of this file.
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  * 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  */
74 typedef 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 */
82 
83 /** Used in apr_pollfd_t to determine what the apr_descriptor is */
84 typedef 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 */
90 
91 /** Union of either an APR file or socket. */
92 typedef union {
93  apr_file_t *f; /**< file */
94  apr_socket_t *s; /**< socket */
96 
97 /** @see apr_pollfd_t */
98 typedef struct apr_pollfd_t apr_pollfd_t;
99 
100 /** Poll descriptor set. */
101 struct 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 */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
296 APR_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  */
304 APR_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  */
310 APR_DECLARE(const char *) apr_poll_method_defname(void);
311 
312 /** Opaque structure used for pollset API */
313 typedef 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  */
325 APR_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  */
343 APR_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  */
366 APR_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  */
376 APR_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  */
385 typedef 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  */
403 APR_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