commit 88faa63f22d9297d7d2f249ee9a642a64a5b48c7
parent 12f65d40ac9a9351b26dc11d7dcd468a531dfe15
Author: Evgeny Grin (Karlson2k) <k2k@narod.ru>
Date: Fri, 8 Sep 2017 16:11:09 +0300
Updated doxy about MHD_get_timeout()
Diffstat:
2 files changed, 54 insertions(+), 20 deletions(-)
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
@@ -2227,6 +2227,8 @@ MHD_add_connection (struct MHD_Daemon *daemon,
* 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.
+ * It's necessary to use #MHD_get_timeout() in combination with
+ * this function.
*
* This function must be called only for daemon started
* without #MHD_USE_INTERNAL_POLLING_THREAD flag.
@@ -2264,6 +2266,8 @@ MHD_get_fdset (struct MHD_Daemon *daemon,
* 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.
+ * It's necessary to use #MHD_get_timeout() in combination with
+ * this function.
*
* This function must be called only for daemon started
* without #MHD_USE_INTERNAL_POLLING_THREAD flag.
@@ -2296,6 +2300,8 @@ MHD_get_fdset2 (struct MHD_Daemon *daemon,
* daemon FDs in fd_sets, call FD_ZERO for each fd_set
* before calling this function. Size of fd_set is
* determined by current value of FD_SETSIZE.
+ * It's necessary to use #MHD_get_timeout() in combination with
+ * this function.
*
* This function could be called only for daemon started
* without #MHD_USE_INTERNAL_POLLING_THREAD flag.
@@ -2317,17 +2323,21 @@ MHD_get_fdset2 (struct MHD_Daemon *daemon,
/**
- * Obtain timeout value for `select()` for this daemon (only needed if
- * connection timeout is used). The returned value is how many milliseconds
- * `select()` or `poll()` should at most block, not the timeout value set for
- * connections. This function MUST NOT be called if MHD is running with
- * #MHD_USE_THREAD_PER_CONNECTION.
+ * Obtain timeout value for polling function for this daemon.
+ * This function set value to amount of milliseconds for which polling
+ * function (`select()` or `poll()`) should at most block, not the
+ * timeout value set for connections.
+ * It is important to always use this function, even if connection
+ * timeout is not set, as in some cases MHD may already have more
+ * data to process on next turn (data pending in TLS buffers,
+ * connections are already ready with epoll etc.) and returned timeout
+ * will be zero.
*
* @param daemon daemon to query for timeout
* @param timeout set to the timeout (in milliseconds)
* @return #MHD_YES on success, #MHD_NO if timeouts are
* not used (or no connections exist that would
- * necessiate the use of a timeout right now).
+ * necessitate the use of a timeout right now).
* @ingroup event
*/
_MHD_EXTERN int
@@ -2338,7 +2348,8 @@ MHD_get_timeout (struct MHD_Daemon *daemon,
/**
* Run webserver operations (without blocking unless in client
* callbacks). This method should be called by clients in combination
- * with #MHD_get_fdset if the client-controlled select method is used.
+ * with #MHD_get_fdset if the client-controlled select method is used and
+ * #MHD_get_timeout().
*
* This function is a convenience method, which is useful if the
* fd_sets from #MHD_get_fdset were not directly passed to `select()`;
@@ -2360,8 +2371,8 @@ MHD_run (struct MHD_Daemon *daemon);
/**
* Run webserver operations. This method should be called by clients
- * in combination with #MHD_get_fdset if the client-controlled select
- * method is used.
+ * in combination with #MHD_get_fdset and #MHD_get_timeout() if the
+ * client-controlled select method is used.
*
* You can use this function instead of #MHD_run if you called
* `select()` on the result from #MHD_get_fdset. File descriptors in
diff --git a/src/microhttpd/daemon.c b/src/microhttpd/daemon.c
@@ -557,6 +557,16 @@ MHD_TLS_init (struct MHD_Daemon *daemon)
* before calling this function. FD_SETSIZE is assumed
* to be platform's default.
*
+ * 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.
+ * It's necessary to use #MHD_get_timeout() in combination with
+ * this function.
+ *
+ * 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
* @param write_fd_set write set
@@ -939,9 +949,17 @@ internal_get_fdset2 (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.
+ *
+ * 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.
+ * It's necessary to use #MHD_get_timeout() in combination with
+ * this function.
*
* This function must be called only for daemon started
* without #MHD_USE_INTERNAL_POLLING_THREAD flag.
@@ -3032,11 +3050,15 @@ MHD_cleanup_connections (struct MHD_Daemon *daemon)
/**
- * Obtain timeout value for `select()` for this daemon (only needed if
- * connection timeout is used). The returned value is how long
- * `select()` or `poll()` should at most block, not the timeout value set
- * for connections. This function MUST NOT be called if MHD is
- * running with #MHD_USE_THREAD_PER_CONNECTION.
+ * Obtain timeout value for polling function for this daemon.
+ * This function set value to amount of milliseconds for which polling
+ * function (`select()` or `poll()`) should at most block, not the
+ * timeout value set for connections.
+ * It is important to always use this function, even if connection
+ * timeout is not set as in some cases MHD may already have more
+ * data to process on next turn (data pending in TLS buffers,
+ * connections are already ready with epoll etc.) and returned timeout
+ * will be zero.
* @remark To be called only from thread that process
* daemon's select()/poll()/etc.
*
@@ -3220,8 +3242,8 @@ internal_run_from_select (struct MHD_Daemon *daemon,
/**
* Run webserver operations. This method should be called by clients
- * in combination with #MHD_get_fdset if the client-controlled select
- * method is used.
+ * in combination with #MHD_get_fdset and #MHD_get_timeout() if the
+ * client-controlled select method is used.
*
* You can use this function instead of #MHD_run if you called
* `select()` on the result from #MHD_get_fdset. File descriptors in
@@ -4242,7 +4264,8 @@ MHD_epoll (struct MHD_Daemon *daemon,
/**
* Run webserver operations (without blocking unless in client
* callbacks). This method should be called by clients in combination
- * with #MHD_get_fdset if the client-controlled select method is used.
+ * with #MHD_get_fdset if the client-controlled select method is used and
+ * #MHD_get_timeout().
*
* This function is a convenience method, which is useful if the
* fd_sets from #MHD_get_fdset were not directly passed to `select()`;
