commit 222acd1c5aacc5f4d3b3ab4955d3fd861b44c5a0
parent d14c6aa0f7dfc3b950a9c0c8ef218b6ba4aa4725
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 21 Mar 2017 12:55:10 +0100
clarify when it is ok to call MHD_get_fdset in documentation, document MHD_get_fdset2()
Diffstat:
3 files changed, 47 insertions(+), 20 deletions(-)
diff --git a/doc/libmicrohttpd.texi b/doc/libmicrohttpd.texi
@@ -1594,6 +1594,15 @@ is added to @var{read_fd_set}. The list of currently existent
connections is scanned and their file descriptors added to the correct
set.
+When calling this function, FD_SETSIZE is assumed to be platform's
+default. If you changed FD_SETSIZE for your application,
+you should use @code{MHD_get_fdset2()} instead.
+
+This function should only be called in when MHD is configured to use
+external select with @code{select()} or with @code{epoll()}. In
+the latter case, it will only add the single @code{epoll()} file
+descriptor used by MHD to the sets.
+
After the call completed successfully: the variable referenced by
@var{max_fd} references the file descriptor with highest integer
identifier. The variable must be set to zero before invoking this
@@ -1605,6 +1614,10 @@ the right options for this call.
@end deftypefun
+@deftypefun int MHD_get_fdset2 (struct MHD_Daemon *daemon, fd_set * read_fd_set, fd_set * write_fd_set, fd_set * except_fd_set, int *max_fd, unsigned int fd_setsize)
+Like @code{MHD_get_fdset()}, except that you can manually specify the value of FD_SETSIZE used by your application.
+
+
@deftypefun int MHD_get_timeout (struct MHD_Daemon *daemon, unsigned long long *timeout)
@cindex timeout
Obtain timeout value for select for this daemon (only needed if
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
@@ -2178,8 +2178,13 @@ MHD_add_connection (struct MHD_Daemon *daemon,
* before calling this function. FD_SETSIZE is assumed
* to be platform's default.
*
- * This function could be called only for daemon started
- * without MHD_USE_INTERNAL_POLLING_THREAD flag.
+ * This function should only be called in when MHD is configured to
+ * use external select with @code{select()} or with @code{epoll()}.
+ * In the latter case, it will only add the single @code{epoll()} file
+ * descriptor used by MHD to the sets.
+ *
+ * This function must be called only for daemon started
+ * without #MHD_USE_INTERNAL_POLLING_THREAD flag.
*
* @param daemon daemon to get sets from
* @param read_fd_set read set
@@ -2205,12 +2210,18 @@ MHD_get_fdset (struct MHD_Daemon *daemon,
* Obtain the `select()` sets for this daemon.
* Daemon's FDs will be added to fd_sets. To get only
* daemon FDs in fd_sets, call FD_ZERO for each fd_set
- * before calling this function. Passing custom FD_SETSIZE
- * as @a fd_setsize allow usage of larger/smaller than
- * platform's default fd_sets.
+ * before calling this function.
*
- * This function could be called only for daemon started
- * without MHD_USE_INTERNAL_POLLING_THREAD flag.
+ * Passing custom FD_SETSIZE as @a fd_setsize allow usage of
+ * larger/smaller than platform's default fd_sets.
+ *
+ * This function should only be called in when MHD is configured to
+ * use external select with @code{select()} or with @code{epoll()}.
+ * In the latter case, it will only add the single @code{epoll()} file
+ * descriptor used by MHD to the sets.
+ *
+ * This function must be called only for daemon started
+ * without #MHD_USE_INTERNAL_POLLING_THREAD flag.
*
* @param daemon daemon to get sets from
* @param read_fd_set read set
@@ -2227,11 +2238,11 @@ MHD_get_fdset (struct MHD_Daemon *daemon,
*/
_MHD_EXTERN int
MHD_get_fdset2 (struct MHD_Daemon *daemon,
- fd_set *read_fd_set,
- fd_set *write_fd_set,
- fd_set *except_fd_set,
- MHD_socket *max_fd,
- unsigned int fd_setsize);
+ fd_set *read_fd_set,
+ fd_set *write_fd_set,
+ fd_set *except_fd_set,
+ MHD_socket *max_fd,
+ unsigned int fd_setsize);
/**
@@ -2242,7 +2253,7 @@ MHD_get_fdset2 (struct MHD_Daemon *daemon,
* determined by current value of FD_SETSIZE.
*
* This function could be called only for daemon started
- * without MHD_USE_INTERNAL_POLLING_THREAD flag.
+ * without #MHD_USE_INTERNAL_POLLING_THREAD flag.
*
* @param daemon daemon to get sets from
* @param read_fd_set read set
@@ -2288,7 +2299,7 @@ MHD_get_timeout (struct MHD_Daemon *daemon,
* fd_sets from #MHD_get_fdset were not directly passed to `select()`;
* with this function, MHD will internally do the appropriate `select()`
* call itself again. While it is always safe to call #MHD_run (if
- * ::MHD_USE_INTERNAL_POLLING_THREAD is not set), you should call
+ * #MHD_USE_INTERNAL_POLLING_THREAD is not set), you should call
* #MHD_run_from_select if performance is important (as it saves an
* expensive call to `select()`).
*
@@ -2315,7 +2326,7 @@ MHD_run (struct MHD_Daemon *daemon);
* ready.
*
* This function cannot be used with daemon started with
- * MHD_USE_INTERNAL_POLLING_THREAD flag.
+ * #MHD_USE_INTERNAL_POLLING_THREAD flag.
*
* @param daemon daemon to run select loop for
* @param read_fd_set read set
diff --git a/src/microhttpd/daemon.c b/src/microhttpd/daemon.c
@@ -1046,8 +1046,8 @@ internal_get_fdset2 (struct MHD_Daemon *daemon,
* as @a fd_setsize allow usage of larger/smaller than
* platform's default fd_sets.
*
- * This function could be called only for daemon started
- * without MHD_USE_INTERNAL_POLLING_THREAD flag.
+ * This function must be called only for daemon started
+ * without #MHD_USE_INTERNAL_POLLING_THREAD flag.
*
* @param daemon daemon to get sets from
* @param read_fd_set read set
@@ -1106,9 +1106,12 @@ MHD_get_fdset2 (struct MHD_Daemon *daemon,
}
#endif
- return internal_get_fdset2 (daemon, read_fd_set,
- write_fd_set, except_fd_set,
- max_fd, fd_setsize);
+ return internal_get_fdset2 (daemon,
+ read_fd_set,
+ write_fd_set,
+ except_fd_set,
+ max_fd,
+ fd_setsize);
}
