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