Apache Portable Runtime
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  * @defgroup pollopts Poll options
46  * @ingroup apr_poll
47  * @{
48  */
49 #define APR_POLLIN 0x001 /**< Can read without blocking */
50 #define APR_POLLPRI 0x002 /**< Priority data available */
51 #define APR_POLLOUT 0x004 /**< Can write without blocking */
52 #define APR_POLLERR 0x010 /**< Pending error */
53 #define APR_POLLHUP 0x020 /**< Hangup occurred */
54 #define APR_POLLNVAL 0x040 /**< Descriptor invalid */
55 #define APR_POLLEXCL 0x080 /**< Exclusive wake up */
56 /** @} */
57 
58 /**
59  * @defgroup pollflags Pollset Flags
60  * @ingroup apr_poll
61  * @{
62  */
63 #define APR_POLLSET_THREADSAFE 0x001 /**< Adding or removing a descriptor is
64  * thread-safe
65  */
66 #define APR_POLLSET_NOCOPY 0x002 /**< Descriptors passed to apr_pollset_add()
67  * are not copied
68  */
69 #define APR_POLLSET_WAKEABLE 0x004 /**< Poll operations are interruptable by
70  * apr_pollset_wakeup() or apr_pollcb_wakeup()
71  */
72 #define APR_POLLSET_NODEFAULT 0x010 /**< Do not try to use the default method if
73  * the specified non-default method cannot be
74  * used
75  */
76 /** @} */
77 
78 /**
79  * Pollset Methods
80  */
81 typedef enum {
82  APR_POLLSET_DEFAULT, /**< Platform default poll method */
83  APR_POLLSET_SELECT, /**< Poll uses select method */
84  APR_POLLSET_KQUEUE, /**< Poll uses kqueue method */
85  APR_POLLSET_PORT, /**< Poll uses Solaris event port method */
86  APR_POLLSET_EPOLL, /**< Poll uses epoll method */
87  APR_POLLSET_POLL, /**< Poll uses poll method */
88  APR_POLLSET_AIO_MSGQ /**< Poll uses z/OS asio method */
90 
91 /** Used in apr_pollfd_t to determine what the apr_descriptor is */
92 typedef enum {
93  APR_NO_DESC, /**< nothing here */
94  APR_POLL_SOCKET, /**< descriptor refers to a socket */
95  APR_POLL_FILE, /**< descriptor refers to a file */
96  APR_POLL_LASTDESC /**< @deprecated descriptor is the last one in the list */
98 
99 /** Union of either an APR file or socket. */
100 typedef union {
101  apr_file_t *f; /**< file */
102  apr_socket_t *s; /**< socket */
104 
105 /** @see apr_pollfd_t */
106 typedef struct apr_pollfd_t apr_pollfd_t;
107 
108 /** Poll descriptor set. */
109 struct apr_pollfd_t {
110  apr_pool_t *p; /**< associated pool */
111  apr_datatype_e desc_type; /**< descriptor type */
112  apr_int16_t reqevents; /**< requested events */
113  apr_int16_t rtnevents; /**< returned events */
114  apr_descriptor desc; /**< @see apr_descriptor */
115  void *client_data; /**< allows app to associate context */
116 };
117 
118 
119 /* General-purpose poll API for arbitrarily large numbers of
120  * file descriptors
121  */
122 
123 /** Opaque structure used for pollset API */
124 typedef struct apr_pollset_t apr_pollset_t;
125 
126 /**
127  * Set up a pollset object
128  * @param pollset The pointer in which to return the newly created object
129  * @param size The maximum number of descriptors that this pollset can hold
130  * @param p The pool from which to allocate the pollset
131  * @param flags Optional flags to modify the operation of the pollset.
132  *
133  * @remark If flags contains APR_POLLSET_THREADSAFE, then a pollset is
134  * created on which it is safe to make concurrent calls to
135  * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll()
136  * from separate threads. This feature is only supported on some
137  * platforms; the apr_pollset_create() call will fail with
138  * APR_ENOTIMPL on platforms where it is not supported.
139  * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollset is
140  * created with an additional internal pipe object used for the
141  * apr_pollset_wakeup() call. The actual size of pollset is
142  * in that case @a size + 1. This feature is only supported on some
143  * platforms; the apr_pollset_create() call will fail with
144  * APR_ENOTIMPL on platforms where it is not supported.
145  * @remark If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t
146  * structures passed to apr_pollset_add() are not copied and
147  * must have a lifetime at least as long as the pollset.
148  * @remark Some poll methods (including APR_POLLSET_KQUEUE,
149  * APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a
150  * fixed limit on the size of the pollset. For these methods,
151  * the size parameter controls the maximum number of
152  * descriptors that will be returned by a single call to
153  * apr_pollset_poll().
154  */
156  apr_uint32_t size,
157  apr_pool_t *p,
158  apr_uint32_t flags);
159 
160 /**
161  * Set up a pollset object
162  * @param pollset The pointer in which to return the newly created object
163  * @param size The maximum number of descriptors that this pollset can hold
164  * @param p The pool from which to allocate the pollset
165  * @param flags Optional flags to modify the operation of the pollset.
166  * @param method Poll method to use. See #apr_pollset_method_e. If this
167  * method cannot be used, the default method will be used unless the
168  * APR_POLLSET_NODEFAULT flag has been specified.
169  *
170  * @remark If flags contains APR_POLLSET_THREADSAFE, then a pollset is
171  * created on which it is safe to make concurrent calls to
172  * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll()
173  * from separate threads. This feature is only supported on some
174  * platforms; the apr_pollset_create_ex() call will fail with
175  * APR_ENOTIMPL on platforms where it is not supported.
176  * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollset is
177  * created with additional internal pipe object used for the
178  * apr_pollset_wakeup() call. The actual size of pollset is
179  * in that case size + 1. This feature is only supported on some
180  * platforms; the apr_pollset_create_ex() call will fail with
181  * APR_ENOTIMPL on platforms where it is not supported.
182  * @remark If flags contains APR_POLLSET_NOCOPY, then the apr_pollfd_t
183  * structures passed to apr_pollset_add() are not copied and
184  * must have a lifetime at least as long as the pollset.
185  * @remark Some poll methods (including APR_POLLSET_KQUEUE,
186  * APR_POLLSET_PORT, and APR_POLLSET_EPOLL) do not have a
187  * fixed limit on the size of the pollset. For these methods,
188  * the size parameter controls the maximum number of
189  * descriptors that will be returned by a single call to
190  * apr_pollset_poll().
191  */
193  apr_uint32_t size,
194  apr_pool_t *p,
195  apr_uint32_t flags,
196  apr_pollset_method_e method);
197 
198 /**
199  * Destroy a pollset object
200  * @param pollset The pollset to destroy
201  */
203 
204 /**
205  * Add a socket or file descriptor to a pollset
206  * @param pollset The pollset to which to add the descriptor
207  * @param descriptor The descriptor to add
208  * @remark If you set client_data in the descriptor, that value
209  * will be returned in the client_data field whenever this
210  * descriptor is signalled in apr_pollset_poll().
211  * @remark If the pollset has been created with APR_POLLSET_THREADSAFE
212  * and thread T1 is blocked in a call to apr_pollset_poll() for
213  * this same pollset that is being modified via apr_pollset_add()
214  * in thread T2, the currently executing apr_pollset_poll() call in
215  * T1 will either: (1) automatically include the newly added descriptor
216  * in the set of descriptors it is watching or (2) return immediately
217  * with APR_EINTR. Option (1) is recommended, but option (2) is
218  * allowed for implementations where option (1) is impossible
219  * or impractical.
220  * @remark If the pollset has been created with APR_POLLSET_NOCOPY, the
221  * apr_pollfd_t structure referenced by descriptor will not be copied
222  * and must have a lifetime at least as long as the pollset.
223  * @remark Do not add the same socket or file descriptor to the same pollset
224  * multiple times, even if the requested events differ for the
225  * different calls to apr_pollset_add(). If the events of interest
226  * for a descriptor change, you must first remove the descriptor
227  * from the pollset with apr_pollset_remove(), then add it again
228  * specifying all requested events.
229  */
231  const apr_pollfd_t *descriptor);
232 
233 /**
234  * Remove a descriptor from a pollset
235  * @param pollset The pollset from which to remove the descriptor
236  * @param descriptor The descriptor to remove
237  * @remark If the descriptor is not found, APR_NOTFOUND is returned.
238  * @remark If the pollset has been created with APR_POLLSET_THREADSAFE
239  * and thread T1 is blocked in a call to apr_pollset_poll() for
240  * this same pollset that is being modified via apr_pollset_remove()
241  * in thread T2, the currently executing apr_pollset_poll() call in
242  * T1 will either: (1) automatically exclude the newly added descriptor
243  * in the set of descriptors it is watching or (2) return immediately
244  * with APR_EINTR. Option (1) is recommended, but option (2) is
245  * allowed for implementations where option (1) is impossible
246  * or impractical.
247  * @remark apr_pollset_remove() cannot be used to remove a subset of requested
248  * events for a descriptor. The reqevents field in the apr_pollfd_t
249  * parameter must contain the same value when removing as when adding.
250  */
252  const apr_pollfd_t *descriptor);
253 
254 /**
255  * Block for activity on the descriptor(s) in a pollset
256  * @param pollset The pollset to use
257  * @param timeout The amount of time in microseconds to wait. This is a
258  * maximum, not a minimum. If a descriptor is signalled, the
259  * function will return before this time. If timeout is
260  * negative, the function will block until a descriptor is
261  * signalled or until apr_pollset_wakeup() has been called.
262  * @param num Number of signalled descriptors (output parameter)
263  * @param descriptors Array of signalled descriptors (output parameter)
264  * @remark APR_EINTR will be returned if the pollset has been created with
265  * APR_POLLSET_WAKEABLE, apr_pollset_wakeup() has been called while
266  * waiting for activity, and there were no signalled descriptors at the
267  * time of the wakeup call.
268  * @remark Multiple signalled conditions for the same descriptor may be reported
269  * in one or more returned apr_pollfd_t structures, depending on the
270  * implementation.
271  */
273  apr_interval_time_t timeout,
274  apr_int32_t *num,
275  const apr_pollfd_t **descriptors);
276 
277 /**
278  * Interrupt the blocked apr_pollset_poll() call.
279  * @param pollset The pollset to use
280  * @remark If the pollset was not created with APR_POLLSET_WAKEABLE the
281  * return value is APR_EINIT.
282  */
284 
285 /**
286  * Poll the descriptors in the poll structure
287  * @param aprset The poll structure we will be using.
288  * @param numsock The number of descriptors we are polling
289  * @param nsds The number of descriptors signalled (output parameter)
290  * @param timeout The amount of time in microseconds to wait. This is a
291  * maximum, not a minimum. If a descriptor is signalled, the
292  * function will return before this time. If timeout is
293  * negative, the function will block until a descriptor is
294  * signalled or until apr_pollset_wakeup() has been called.
295  * @remark The number of descriptors signalled is returned in the third argument.
296  * This is a blocking call, and it will not return until either a
297  * descriptor has been signalled or the timeout has expired.
298  * @remark The rtnevents field in the apr_pollfd_t array will only be filled-
299  * in if the return value is APR_SUCCESS.
300  */
301 APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock,
302  apr_int32_t *nsds,
303  apr_interval_time_t timeout);
304 
305 /**
306  * Return a printable representation of the pollset method.
307  * @param pollset The pollset to use
308  */
310 
311 /**
312  * Return a printable representation of the default pollset method
313  * (APR_POLLSET_DEFAULT).
314  */
316 
317 /** Opaque structure used for pollcb API */
318 typedef struct apr_pollcb_t apr_pollcb_t;
319 
320 /**
321  * Set up a pollcb object
322  * @param pollcb The pointer in which to return the newly created object
323  * @param size The maximum number of descriptors that a single _poll can return.
324  * @param p The pool from which to allocate the pollcb
325  * @param flags Optional flags to modify the operation of the pollcb.
326  *
327  * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollcb is
328  * created with an additional internal pipe object used for the
329  * apr_pollcb_wakeup() call. The actual size of pollcb is
330  * in that case @a size + 1.
331  * @remark Pollcb is only supported on some platforms; the apr_pollcb_create()
332  * call will fail with APR_ENOTIMPL on platforms where it is not supported.
333  */
335  apr_uint32_t size,
336  apr_pool_t *p,
337  apr_uint32_t flags);
338 
339 /**
340  * Set up a pollcb object
341  * @param pollcb The pointer in which to return the newly created object
342  * @param size The maximum number of descriptors that a single _poll can return.
343  * @param p The pool from which to allocate the pollcb
344  * @param flags Optional flags to modify the operation of the pollcb.
345  * @param method Poll method to use. See #apr_pollset_method_e. If this
346  * method cannot be used, the default method will be used unless the
347  * APR_POLLSET_NODEFAULT flag has been specified.
348  *
349  * @remark If flags contains APR_POLLSET_WAKEABLE, then a pollcb is
350  * created with an additional internal pipe object used for the
351  * apr_pollcb_wakeup() call. The actual size of pollcb is
352  * in that case @a size + 1.
353  * @remark Pollcb is only supported on some platforms; the apr_pollcb_create_ex()
354  * call will fail with APR_ENOTIMPL on platforms where it is not supported.
355  */
357  apr_uint32_t size,
358  apr_pool_t *p,
359  apr_uint32_t flags,
360  apr_pollset_method_e method);
361 
362 /**
363  * Add a socket or file descriptor to a pollcb
364  * @param pollcb The pollcb to which to add the descriptor
365  * @param descriptor The descriptor to add
366  * @remark If you set client_data in the descriptor, that value will be
367  * returned in the client_data field whenever this descriptor is
368  * signalled in apr_pollcb_poll().
369  * @remark Unlike the apr_pollset API, the descriptor is not copied, and users
370  * must retain the memory used by descriptor, as the same pointer will
371  * be returned to them from apr_pollcb_poll.
372  * @remark Do not add the same socket or file descriptor to the same pollcb
373  * multiple times, even if the requested events differ for the
374  * different calls to apr_pollcb_add(). If the events of interest
375  * for a descriptor change, you must first remove the descriptor
376  * from the pollcb with apr_pollcb_remove(), then add it again
377  * specifying all requested events.
378  */
380  apr_pollfd_t *descriptor);
381 /**
382  * Remove a descriptor from a pollcb
383  * @param pollcb The pollcb from which to remove the descriptor
384  * @param descriptor The descriptor to remove
385  * @remark If the descriptor is not found, APR_NOTFOUND is returned.
386  * @remark apr_pollcb_remove() cannot be used to remove a subset of requested
387  * events for a descriptor. The reqevents field in the apr_pollfd_t
388  * parameter must contain the same value when removing as when adding.
389  */
391  apr_pollfd_t *descriptor);
392 
393 /**
394  * Function prototype for pollcb handlers
395  * @param baton Opaque baton passed into apr_pollcb_poll()
396  * @param descriptor Contains the notification for an active descriptor.
397  * The @a rtnevents member describes which events were triggered
398  * for this descriptor.
399  * @remark If the pollcb handler does not return APR_SUCCESS, the apr_pollcb_poll()
400  * call returns with the handler's return value.
401  */
402 typedef apr_status_t (*apr_pollcb_cb_t)(void *baton, apr_pollfd_t *descriptor);
403 
404 /**
405  * Block for activity on the descriptor(s) in a pollcb
406  * @param pollcb The pollcb to use
407  * @param timeout The amount of time in microseconds to wait. This is a
408  * maximum, not a minimum. If a descriptor is signalled, the
409  * function will return before this time. If timeout is
410  * negative, the function will block until a descriptor is
411  * signalled or until apr_pollcb_wakeup() has been called.
412  * @param func Callback function to call for each active descriptor.
413  * @param baton Opaque baton passed to the callback function.
414  * @remark Multiple signalled conditions for the same descriptor may be reported
415  * in one or more calls to the callback function, depending on the
416  * implementation.
417  * @remark APR_EINTR will be returned if the pollset has been created with
418  * APR_POLLSET_WAKEABLE and apr_pollcb_wakeup() has been called while
419  * waiting for activity.
420  */
422  apr_interval_time_t timeout,
423  apr_pollcb_cb_t func,
424  void *baton);
425 
426 /**
427  * Interrupt the blocked apr_pollcb_poll() call.
428  * @param pollcb The pollcb to use
429  * @remark If the pollcb was not created with APR_POLLSET_WAKEABLE the
430  * return value is APR_EINIT.
431  */
433 
434 /**
435  * Return a printable representation of the pollcb method.
436  * @param pollcb The pollcb to use
437  */
439 
440 /** @} */
441 
442 #ifdef __cplusplus
443 }
444 #endif
445 
446 #endif /* ! APR_POLL_H */
447 
APR Platform Definitions.
APR Error Codes.
APR File I/O Handling.
APR File Handle Inheritance Helpers.
APR Network library.
APR memory allocation.
int apr_status_t
Definition: apr_errno.h:44
struct apr_file_t apr_file_t
Definition: apr_file_io.h:195
struct apr_socket_t apr_socket_t
Definition: apr_network_io.h:219
#define APR_DECLARE(type)
Definition: apr.h:516
apr_datatype_e
Definition: apr_poll.h:92
apr_status_t apr_pollcb_poll(apr_pollcb_t *pollcb, apr_interval_time_t timeout, apr_pollcb_cb_t func, void *baton)
apr_status_t(* apr_pollcb_cb_t)(void *baton, apr_pollfd_t *descriptor)
Definition: apr_poll.h:402
apr_status_t apr_pollcb_create_ex(apr_pollcb_t **pollcb, apr_uint32_t size, apr_pool_t *p, apr_uint32_t flags, apr_pollset_method_e method)
apr_status_t apr_pollset_remove(apr_pollset_t *pollset, const apr_pollfd_t *descriptor)
const char * apr_pollcb_method_name(apr_pollcb_t *pollcb)
apr_status_t apr_pollset_create(apr_pollset_t **pollset, apr_uint32_t size, apr_pool_t *p, apr_uint32_t flags)
apr_status_t apr_pollset_add(apr_pollset_t *pollset, const apr_pollfd_t *descriptor)
const char * apr_poll_method_defname(void)
struct apr_pollset_t apr_pollset_t
Definition: apr_poll.h:124
apr_status_t apr_pollset_poll(apr_pollset_t *pollset, apr_interval_time_t timeout, apr_int32_t *num, const apr_pollfd_t **descriptors)
apr_status_t apr_pollcb_create(apr_pollcb_t **pollcb, apr_uint32_t size, apr_pool_t *p, apr_uint32_t flags)
apr_status_t apr_pollcb_add(apr_pollcb_t *pollcb, apr_pollfd_t *descriptor)
const char * apr_pollset_method_name(apr_pollset_t *pollset)
apr_status_t apr_pollset_create_ex(apr_pollset_t **pollset, apr_uint32_t size, apr_pool_t *p, apr_uint32_t flags, apr_pollset_method_e method)
apr_status_t apr_pollset_destroy(apr_pollset_t *pollset)
apr_pollset_method_e
Definition: apr_poll.h:81
apr_status_t apr_pollset_wakeup(apr_pollset_t *pollset)
apr_status_t apr_pollcb_wakeup(apr_pollcb_t *pollcb)
apr_status_t apr_pollcb_remove(apr_pollcb_t *pollcb, apr_pollfd_t *descriptor)
apr_status_t apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock, apr_int32_t *nsds, apr_interval_time_t timeout)
struct apr_pollcb_t apr_pollcb_t
Definition: apr_poll.h:318
@ APR_POLL_SOCKET
Definition: apr_poll.h:94
@ APR_POLL_LASTDESC
Definition: apr_poll.h:96
@ APR_POLL_FILE
Definition: apr_poll.h:95
@ APR_NO_DESC
Definition: apr_poll.h:93
@ APR_POLLSET_EPOLL
Definition: apr_poll.h:86
@ APR_POLLSET_KQUEUE
Definition: apr_poll.h:84
@ APR_POLLSET_SELECT
Definition: apr_poll.h:83
@ APR_POLLSET_POLL
Definition: apr_poll.h:87
@ APR_POLLSET_AIO_MSGQ
Definition: apr_poll.h:88
@ APR_POLLSET_DEFAULT
Definition: apr_poll.h:82
@ APR_POLLSET_PORT
Definition: apr_poll.h:85
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
apr_int64_t apr_interval_time_t
Definition: apr_time.h:55
Definition: apr_poll.h:109
void * client_data
Definition: apr_poll.h:115
apr_int16_t reqevents
Definition: apr_poll.h:112
apr_datatype_e desc_type
Definition: apr_poll.h:111
apr_descriptor desc
Definition: apr_poll.h:114
apr_pool_t * p
Definition: apr_poll.h:110
apr_int16_t rtnevents
Definition: apr_poll.h:113
Definition: apr_poll.h:100
apr_socket_t * s
Definition: apr_poll.h:102
apr_file_t * f
Definition: apr_poll.h:101