[PATCH] apr_poll.h (choosing between the APIs)

[Rob Saccoccio <ro...@fastcgi.com>]

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
  * @{
  */