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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
21 * @brief APR Poll interface
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"
30 #if APR_HAVE_NETINET_IN_H
31 #include <netinet/in.h>
36 #endif /* __cplusplus */
39 * @defgroup apr_poll Poll Routines
45 * @defgroup pollopts Poll options
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 */
58 * @defgroup pollflags Pollset Flags
62 #define APR_POLLSET_THREADSAFE 0x001 /**< Adding or removing a descriptor is
65 #define APR_POLLSET_NOCOPY 0x002 /**< Descriptors passed to apr_pollset_add()
68 #define APR_POLLSET_WAKEABLE 0x004 /**< Poll operations are interruptable by
69 * apr_pollset_wakeup()
71 #define APR_POLLSET_NODEFAULT 0x010 /**< Do not try to use the default method if
72 * the specified non-default method cannot be
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 */
88 } apr_pollset_method_e;
90 /** Used in apr_pollfd_t to determine what the apr_descriptor is */
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 */
98 /** Union of either an APR file or socket. */
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;
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 */
118 /* General-purpose poll API for arbitrarily large numbers of
122 /** Opaque structure used for pollset API */
123 typedef struct apr_pollset_t apr_pollset_t;
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.
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().
154 APR_DECLARE(apr_status_t) apr_pollset_create(apr_pollset_t **pollset,
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.
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().
191 APR_DECLARE(apr_status_t) apr_pollset_create_ex(apr_pollset_t **pollset,
195 apr_pollset_method_e method);
198 * Destroy a pollset object
199 * @param pollset The pollset to destroy
201 APR_DECLARE(apr_status_t) apr_pollset_destroy(apr_pollset_t *pollset);
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
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.
229 APR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset,
230 const apr_pollfd_t *descriptor);
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
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.
250 APR_DECLARE(apr_status_t) apr_pollset_remove(apr_pollset_t *pollset,
251 const apr_pollfd_t *descriptor);
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
271 APR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset,
272 apr_interval_time_t timeout,
274 const apr_pollfd_t **descriptors);
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.
282 APR_DECLARE(apr_status_t) apr_pollset_wakeup(apr_pollset_t *pollset);
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.
300 APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock,
302 apr_interval_time_t timeout);
305 * Return a printable representation of the pollset method.
306 * @param pollset The pollset to use
308 APR_DECLARE(const char *) apr_pollset_method_name(apr_pollset_t *pollset);
311 * Return a printable representation of the default pollset method
312 * (APR_POLLSET_DEFAULT).
314 APR_DECLARE(const char *) apr_poll_method_defname(void);
316 /** Opaque structure used for pollcb API */
317 typedef struct apr_pollcb_t apr_pollcb_t;
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.
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.
329 APR_DECLARE(apr_status_t) apr_pollcb_create(apr_pollcb_t **pollcb,
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.
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.
347 APR_DECLARE(apr_status_t) apr_pollcb_create_ex(apr_pollcb_t **pollcb,
351 apr_pollset_method_e method);
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.
370 APR_DECLARE(apr_status_t) apr_pollcb_add(apr_pollcb_t *pollcb,
371 apr_pollfd_t *descriptor);
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.
380 APR_DECLARE(apr_status_t) apr_pollcb_remove(apr_pollcb_t *pollcb,
381 apr_pollfd_t *descriptor);
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.
389 typedef apr_status_t (*apr_pollcb_cb_t)(void *baton, apr_pollfd_t *descriptor);
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
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
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,
416 #endif /* ! APR_POLL_H */