gnunet-svn
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[GNUnet-SVN] r27588 - libmicrohttpd/doc


From: gnunet
Subject: [GNUnet-SVN] r27588 - libmicrohttpd/doc
Date: Tue, 25 Jun 2013 15:13:46 +0200

Author: grothoff
Date: 2013-06-25 15:13:46 +0200 (Tue, 25 Jun 2013)
New Revision: 27588

Added:
   libmicrohttpd/doc/performance_data.png
Modified:
   libmicrohttpd/doc/libmicrohttpd.texi
Log:
-documentation updates for epoll

Modified: libmicrohttpd/doc/libmicrohttpd.texi
===================================================================
--- libmicrohttpd/doc/libmicrohttpd.texi        2013-06-25 13:05:51 UTC (rev 
27587)
+++ libmicrohttpd/doc/libmicrohttpd.texi        2013-06-25 13:13:46 UTC (rev 
27588)
@@ -142,7 +142,73 @@
 @c If you have other interesting examples, please let us know
 @end itemize
 
address@hidden Thread modes and event loops
address@hidden poll
address@hidden epoll
address@hidden select
 
+MHD supports four basic thread modes and up to three event loop
+styes.  
+
+The four basic thread modes are external (MHD creates no threads,
+event loop is fully managed by the application), internal (MHD creates
+one thread for all connections), thread pool (MHD creates a thread
+pool which is used to process all connections) and
+thread-per-connection (MHD creates one listen thread and then one
+thread per accepted connection).
+
+These thread modes are then combined with the event loop styles.
+MHD support select, poll and epoll.  epoll is only available on
+Linux, poll may not be available on some platforms.  Note that
+it is possible to combine MHD using epoll with an external
+select-based event loop.
+
+The default (if no other option is passed) is ``external select''.
+The highest performance can typically be obtained with a thread pool
+using @code{epoll}.  Apache Benchmark (ab) was used to compare the
+performance of @code{select} and @code{epoll} when using a thread pool
+and a large number of connections. @ref{fig:performance} shows the
+resulting plot from the @code{benchmark.c} example, which measures the
+latency between an incoming request and the completion of the
+transmission of the response.  In this setting, the @code{epoll}
+thread pool with four threads was able to handle more than 45,000
+connections per second on loopback (with Apache Benchmark running
+three processes on the same machine).
address@hidden performance
+
+
address@hidden Figure,fig:performance
address@hidden,400pt,300pt,Data,.png}
address@hidden measurements for select vs. epoll (with thread-pool).}
address@hidden float
+
+
+Not all combinations of thread modes and event loop styles are
+supported.  This is partially to keep the API simple, and partially
+because some combinations simply make no sense as others are strictly
+superior.  Note that the choice of style depends fist of all on the
+application logic, and then on the performance requirements.
+Applications that perform a blocking operation while handling a
+request within the callbacks from MHD must use a thread per
+connection.  This is typically rather costly.  Applications that do
+not support threads or that must run on embedded devices without
+thread-support must use the external mode.  Using @code{epoll} is only
+supported on Linux, thus portable applications must at least have a
+fallback option available.  @ref{tbl:supported} lists the sane
+combinations.
+
address@hidden Table,tbl:supported
address@hidden address@hidden address@hidden address@hidden address@hidden
address@hidden                           @tab @b{select} @tab @b{poll} @tab 
@b{epoll}
address@hidden @b{external}              @tab  yes       @tab no       @tab yes
address@hidden @b{internal}              @tab  yes       @tab yes      @tab yes
address@hidden @b{thread pool}           @tab  yes       @tab yes      @tab yes
address@hidden @b{thread-per-connection} @tab  yes       @tab yes      @tab no 
address@hidden multitable
address@hidden combinations of event styles and thread modes.}
address@hidden float
+
+
 @section Compiling GNU libmicrohttpd
 @cindex compilation
 @cindex embedded systems
@@ -188,6 +254,9 @@
 @item ``--disable-dauth''
 do not include the authentication APIs (results in binary incompatibility)
 
address@hidden ``--disable-epoll
+do not include epoll support, even on Linux (minimally smaller binary size, 
good for testing portability to non-Linux systems)
+
 @item ``--enable-coverage''
 set flags for analysis of code-coverage with gcc/gcov (results in slow, large 
binaries)
 
@@ -341,6 +410,16 @@
 If you specify @code{MHD_USE_IPV6} and the local platform does not
 support it, @code{MHD_start_daemon} will return NULL.
 
+If you want MHD to support IPv4 and IPv6 using a single socket, pass
+MHD_USE_DUAL_STACK, otherwise, if you only pass this option, MHD will
+try to bind to IPv6-only (resulting in no IPv4 support).
+
address@hidden MHD_USE_DUAL_STACK
address@hidden IPv6
+Use a single socket for IPv4 and IPv6.  Note that this will mean
+that IPv4 addresses are returned by MHD in the IPv6-mapped format
+(the 'struct sockaddr_in6' format will be used for IPv4 and IPv6).
+
 @item MHD_USE_PEDANTIC_CHECKS
 Be pedantic about the protocol (as opposed to as tolerant as possible).
 Specifically, at the moment, this flag causes MHD to reject HTTP
@@ -355,11 +434,27 @@
 @cindex poll
 @cindex select
 Use poll instead of select. This allows sockets with descriptors
address@hidden>= FD_SETSIZE}.  This option only works in conjunction with
address@hidden (at this point).  If you
-specify @code{MHD_USE_POLL} and the local platform does not support
-it, @code{MHD_start_daemon} will return NULL.
address@hidden>= FD_SETSIZE}.  This option currently only works in conjunction
+with @code{MHD_USE_THREAD_PER_CONNECTION} or
address@hidden (at this point).  If you specify
address@hidden and the local platform does not support it,
address@hidden will return NULL.
 
address@hidden MHD_USE_EPOLL_LINUX_ONLY
address@hidden FD_SETSIZE
address@hidden epoll
address@hidden select
+Use epoll instead of poll or select. This allows sockets with
+descriptors @code{>= FD_SETSIZE}.  This option is only available on
+Linux systems and only works in conjunction with
address@hidden (at this point).  If you specify
address@hidden and the local platform does not
+support it, @code{MHD_start_daemon} will return NULL.  Using epoll
+instead of select or poll can in some situations result in significantly
+higher performance as the system call has fundamentally lower complexity
+(O(1) for epoll vs. O(n) for select/poll where n is the number of
+open connections).
+
 @item MHD_SUPPRESS_DATE_NO_CLOCK
 @cindex date
 @cindex clock
@@ -380,6 +475,18 @@
 with using a thread pool; if it is used,
 @code{MHD_OPTION_THREAD_POOL_SIZE} is ignored.
 
address@hidden MHD_USE_PIPE_FOR_SHUTDOWN
address@hidden quiesce
+Force MHD to use a signal pipe to notify the event loop (of threads)
+of our shutdown.  This is required if an appliction uses
address@hidden or @code{MHD_USE_THREAD_PER_CONNECTION}
+and then performs @code{MHD_quiesce_daemon} (which eliminates our
+ability to signal termination via the listen socket).  In these modes,
address@hidden will fail if this option was not set.  Also,
+use of this option is automatic (as in, you do not even have to
+specify it), if @code{MHD_USE_NO_LISTEN_SOCKET} is specified.  In
+"external" select mode, this option is always simply ignored.  
+
 @end table
 @end deftp
 
@@ -1087,6 +1194,7 @@
 
 
 @deftypefun int MHD_quiesce_daemon (struct MHD_Daemon *daemon)
address@hidden quiesce
 Stop accepting connections from the listening socket.  Allows clients
 to continue processing, but stops accepting new connections.  Note
 that the caller is responsible for closing the returned socket;
@@ -1102,6 +1210,7 @@
 
 Return @code{-1} on error (daemon not listening), the handle to the
 listen socket otherwise.
+
 @end deftypefun
 
 
@@ -1130,6 +1239,7 @@
 started with the right options for this call.
 @end deftypefun
 
+
 @deftypefun int MHD_run_from_select (struct MHD_Daemon *daemon, const fd_set 
*read_fd_set, const fd_set *write_fd_set, const fd_set *except_fd_set)
 Run webserver operations given sets of ready socket handles.
 @cindex select
@@ -1162,6 +1272,7 @@
 @end deftypefun
 
 
+
 @deftypefun void MHD_add_connection (struct MHD_Daemon *daemon, int 
client_socket, const struct sockaddr *addr, socklen_t addrlen)
 Add another client connection to the set of connections 
 managed by MHD.  This API is usually not needed (since
@@ -2055,12 +2166,14 @@
 @item MHD_DAEMON_INFO_KEY_SIZE
 Request information about the key size for a particular cipher
 algorithm.  The cipher algorithm should be passed as an extra argument
-(of type 'enum MHD_GNUTLS_CipherAlgorithm').
+(of type 'enum MHD_GNUTLS_CipherAlgorithm').  No longer supported,
+using this value will cause MHD_get_daemon_info to return NULL.
 
 @item MHD_DAEMON_INFO_MAC_KEY_SIZE
 Request information about the key size for a particular cipher
 algorithm.  The cipher algorithm should be passed as an extra argument
-(of type 'enum MHD_GNUTLS_HashAlgorithm').
+(of type 'enum MHD_GNUTLS_HashAlgorithm').  No longer supported,
+using this value will cause MHD_get_daemon_info to return NULL.
 
 @item MHD_DAEMON_INFO_LISTEN_FD
 @cindex listen
@@ -2070,6 +2183,17 @@
 is actually being used by MHD.
 No extra arguments should be passed.
 
address@hidden MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY
address@hidden epoll
+Request the file-descriptor number that MHD is using for epoll.  If
+the build is not supporting epoll, NULL is returned; if we are using a
+thread pool or this daemon was not started with
+MHD_USE_EPOLL_LINUX_ONLY, (a pointer to) -1 is returned.  If we are
+using MHD_USE_SELECT_INTERNALLY or are in 'external' select mode, the
+internal epoll FD is returned.  This function must be used in external
+select mode with epoll to obtain the FD to call epoll on.  No extra
+arguments should be passed.
+
 @end table
 @end deftp
 

Added: libmicrohttpd/doc/performance_data.png
===================================================================
(Binary files differ)

Index: libmicrohttpd/doc/performance_data.png
===================================================================
--- libmicrohttpd/doc/performance_data.png      2013-06-25 13:05:51 UTC (rev 
27587)
+++ libmicrohttpd/doc/performance_data.png      2013-06-25 13:13:46 UTC (rev 
27588)

Property changes on: libmicrohttpd/doc/performance_data.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/octet-stream
\ No newline at end of property



reply via email to

[Prev in Thread] Current Thread [Next in Thread]