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  * @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()
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 Pollcb is only supported on some platforms; the apr_pollcb_create()
327  * call will fail with APR_ENOTIMPL on platforms where it is not supported.
328  */
329 APR_DECLARE(apr_status_t) apr_pollcb_create(apr_pollcb_t **pollcb,
330  apr_uint32_t size,
331  apr_pool_t *p,
332  apr_uint32_t flags);
333 
334 /**
335  * Set up a pollcb object
336  * @param pollcb The pointer in which to return the newly created object
337  * @param size The maximum number of descriptors that a single _poll can return.
338  * @param p The pool from which to allocate the pollcb
339  * @param flags Optional flags to modify the operation of the pollcb.
340  * @param method Poll method to use. See #apr_pollset_method_e. If this
341  * method cannot be used, the default method will be used unless the
342  * APR_POLLSET_NODEFAULT flag has been specified.
343  *
344  * @remark Pollcb is only supported on some platforms; the apr_pollcb_create_ex()
345  * call will fail with APR_ENOTIMPL on platforms where it is not supported.
346  */
347 APR_DECLARE(apr_status_t) apr_pollcb_create_ex(apr_pollcb_t **pollcb,
348  apr_uint32_t size,
349  apr_pool_t *p,
350  apr_uint32_t flags,
351  apr_pollset_method_e method);
352 
353 /**
354  * Add a socket or file descriptor to a pollcb
355  * @param pollcb The pollcb to which to add the descriptor
356  * @param descriptor The descriptor to add
357  * @remark If you set client_data in the descriptor, that value will be
358  * returned in the client_data field whenever this descriptor is
359  * signalled in apr_pollcb_poll().
360  * @remark Unlike the apr_pollset API, the descriptor is not copied, and users
361  * must retain the memory used by descriptor, as the same pointer will
362  * be returned to them from apr_pollcb_poll.
363  * @remark Do not add the same socket or file descriptor to the same pollcb
364  * multiple times, even if the requested events differ for the
365  * different calls to apr_pollcb_add(). If the events of interest
366  * for a descriptor change, you must first remove the descriptor
367  * from the pollcb with apr_pollcb_remove(), then add it again
368  * specifying all requested events.
369  */
370 APR_DECLARE(apr_status_t) apr_pollcb_add(apr_pollcb_t *pollcb,
371  apr_pollfd_t *descriptor);
372 /**
373  * Remove a descriptor from a pollcb
374  * @param pollcb The pollcb from which to remove the descriptor
375  * @param descriptor The descriptor to remove
376  * @remark apr_pollcb_remove() cannot be used to remove a subset of requested
377  * events for a descriptor. The reqevents field in the apr_pollfd_t
378  * parameter must contain the same value when removing as when adding.
379  */
380 APR_DECLARE(apr_status_t) apr_pollcb_remove(apr_pollcb_t *pollcb,
381  apr_pollfd_t *descriptor);
382 
383 /** Function prototype for pollcb handlers
384  * @param baton Opaque baton passed into apr_pollcb_poll()
385  * @param descriptor Contains the notification for an active descriptor,
386  * the rtnevents member contains what events were triggered
387  * for this descriptor.
388  */
389 typedef apr_status_t (*apr_pollcb_cb_t)(void *baton, apr_pollfd_t *descriptor);
390 
391 /**
392  * Block for activity on the descriptor(s) in a pollcb
393  * @param pollcb The pollcb to use
394  * @param timeout The amount of time in microseconds to wait. This is a
395  * maximum, not a minimum. If a descriptor is signalled, the
396  * function will return before this time. If timeout is
397  * negative, the function will block until a descriptor is
398  * signalled.
399  * @param func Callback function to call for each active descriptor.
400  * @param baton Opaque baton passed to the callback function.
401  * @remark Multiple signalled conditions for the same descriptor may be reported
402  * in one or more calls to the callback function, depending on the
403  * implementation.
404  */
405 APR_DECLARE(apr_status_t) apr_pollcb_poll(apr_pollcb_t *pollcb,
406  apr_interval_time_t timeout,
407  apr_pollcb_cb_t func,
408  void *baton);
409 
410 /** @} */
411 
412 #ifdef __cplusplus
413 }
414 #endif
415 
416 #endif /* ! APR_POLL_H */
417