The following patch incorporates Brian's and Ryan's comments regarding
choosing between the two poll APIs.
--rob
Index: apr_poll.h
===================================================================
RCS file: /home/cvspublic/apr/include/apr_poll.h,v
retrieving revision 1.5
diff -u -r1.5 apr_poll.h
--- apr_poll.h 4 Aug 2002 04:43:23 -0000 1.5
+++ apr_poll.h 5 Aug 2002 01:19:24 -0000
@@ -55,11 +55,34 @@
#ifndef APR_POLL_H
#define APR_POLL_H
/**
- * @file apr_network_io.h
- * @brief APR Network library
+ * @file apr_poll.h
+ * @brief APR file/socket polling
+ *
+ * Two APIs are provided. The apr_pollset routines are intended to support
+ * repeated use of the pollset and are better for large numbers of
+ * descriptors (apr_poll is O(2n), apr_pollset is O(n)). To take advantage
+ * of it, you need to keep a handle on the pollset between calls to poll.
+ * In situations where it's prohibitively complex to maintain a pollset
+ * object, the apr_poll API is simpler to use. If you expect to call poll
+ * on a single descriptor repeatedly (and can maintain the pollset object),
+ * the apr_pollset API is more efficient than the apr_poll API.
+ *
+ * A reasonable rule of thumb for choosing between the poll APIs is:
+ *
+ * if ((very small number of file descriptors)
+ * && ((poll will NOT be repeated multiple times)
+ * || (application CANNOT keep track of a pollset object))
+ * {
+ * use apr_poll API;
+ * }
+ * }
+ * else {
+ * use apr_pollset API;
+ * }
*/
+
/**
- * @defgroup APR_Net Network Routines
+ * @defgroup APR_Poll Functions
* @ingroup APR
* @{
*/
