diff options
author | Karlson2k <k2k@narod.ru> | 2016-11-23 17:38:53 +0300 |
---|---|---|
committer | Evgeny Grin (Karlson2k) <k2k@narod.ru> | 2016-11-23 17:44:38 +0300 |
commit | f9f8d0c54d103995e2c8ccd42de8e5ca1cc931b2 (patch) | |
tree | eff6a17cde5f7dd6d82cec6f306ba10a2267065f /doc | |
parent | 198181f17828a0c25079ace9d71f23682d99b8ad (diff) | |
download | libmicrohttpd-f9f8d0c54d103995e2c8ccd42de8e5ca1cc931b2.tar.gz libmicrohttpd-f9f8d0c54d103995e2c8ccd42de8e5ca1cc931b2.zip |
Updated documentation.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/libmicrohttpd.texi | 115 |
1 files changed, 65 insertions, 50 deletions
diff --git a/doc/libmicrohttpd.texi b/doc/libmicrohttpd.texi index 70bef1cd..dba1d08f 100644 --- a/doc/libmicrohttpd.texi +++ b/doc/libmicrohttpd.texi | |||
@@ -163,18 +163,18 @@ Examples based on reports we've received from developers include: | |||
163 | MHD supports four basic thread modes and up to three event loop | 163 | MHD supports four basic thread modes and up to three event loop |
164 | styles. | 164 | styles. |
165 | 165 | ||
166 | The four basic thread modes are external (MHD creates no threads, | 166 | The four basic thread modes are external sockets polling (MHD creates |
167 | event loop is fully managed by the application), internal (MHD creates | 167 | no threads, event loop is fully managed by the application), internal |
168 | one thread for all connections), thread pool (MHD creates a thread | 168 | polling (MHD creates one thread for all connections), polling in |
169 | pool which is used to process all connections) and | 169 | thread pool (MHD creates a thread pool which is used to process all |
170 | thread-per-connection (MHD creates one listen thread and then one | 170 | connections) and thread-per-connection (MHD creates one thread for |
171 | thread per accepted connection). | 171 | listen sockets and then one thread per accepted connection). |
172 | 172 | ||
173 | These thread modes are then combined with the event loop styles. | 173 | These thread modes are then combined with the evet loop styles |
174 | MHD support select, poll and epoll. select is available on all | 174 | (polling function type). MHD support select, poll and epoll. select |
175 | platforms, epoll and poll may not be available on some platforms. | 175 | is available on all platforms, epoll and poll may not be available on |
176 | Note that it is possible to combine MHD using epoll with an external | 176 | some platforms. Note that it is possible to combine MHD using epoll |
177 | select-based event loop. | 177 | with an external select-based event loop. |
178 | 178 | ||
179 | The default (if no other option is passed) is ``external select''. | 179 | The default (if no other option is passed) is ``external select''. |
180 | The highest performance can typically be obtained with a thread pool | 180 | The highest performance can typically be obtained with a thread pool |
@@ -267,7 +267,10 @@ do not include the post processor API (results in binary incompatibility) | |||
267 | @item ``--disable-dauth'' | 267 | @item ``--disable-dauth'' |
268 | do not include the authentication APIs (results in binary incompatibility) | 268 | do not include the authentication APIs (results in binary incompatibility) |
269 | 269 | ||
270 | @item ``--disable-epoll | 270 | @item ``--disable-httpupgrade'' |
271 | do not build code for HTTP ``Upgrade'' (smaller binary size, binary incompatible library) | ||
272 | |||
273 | @item ``--disable-epoll'' | ||
271 | do not include epoll support, even if it supported (minimally smaller binary size, good for portability testing) | 274 | do not include epoll support, even if it supported (minimally smaller binary size, good for portability testing) |
272 | 275 | ||
273 | @item ``--enable-coverage'' | 276 | @item ``--enable-coverage'' |
@@ -334,17 +337,18 @@ causing problems when porting to other platforms). | |||
334 | 337 | ||
335 | @section SIGPIPE | 338 | @section SIGPIPE |
336 | @cindex signals | 339 | @cindex signals |
337 | MHD does not install a signal handler for SIGPIPE. On platforms | 340 | MHD does not install a signal handler for SIGPIPE. On platforms where |
338 | where this is possible (such as GNU/Linux), it disables SIGPIPE for | 341 | this is possible (such as GNU/Linux), it disables SIGPIPE for its I/O |
339 | its I/O operations (by passing MSG_NOSIGNAL). On other platforms, | 342 | operations (by passing MSG_NOSIGNAL or similar). On other platforms, |
340 | SIGPIPE signals may be generated from network operations by | 343 | SIGPIPE signals may be generated from network operations by MHD and |
341 | MHD and will cause the process to die unless the developer | 344 | will cause the process to die unless the developer explicitly installs |
342 | explicitly installs a signal handler for SIGPIPE. | 345 | a signal handler for SIGPIPE. |
343 | 346 | ||
344 | Hence portable code using MHD must install a SIGPIPE handler or | 347 | Hence portable code using MHD must install a SIGPIPE handler or |
345 | explicitly block the SIGPIPE signal. MHD does not do so in order | 348 | explicitly block the SIGPIPE signal. MHD does not do so in order to |
346 | to avoid messing with other parts of the application that may | 349 | avoid messing with other parts of the application that may need to |
347 | need to handle SIGPIPE in a particular way. You can make your application handle SIGPIPE by calling the following function in @code{main}: | 350 | handle SIGPIPE in a particular way. You can make your application |
351 | handle SIGPIPE by calling the following function in @code{main}: | ||
348 | 352 | ||
349 | @verbatim | 353 | @verbatim |
350 | static void | 354 | static void |
@@ -435,34 +439,36 @@ compiler). | |||
435 | @deftp {Enumeration} MHD_FLAG | 439 | @deftp {Enumeration} MHD_FLAG |
436 | Options for the MHD daemon. | 440 | Options for the MHD daemon. |
437 | 441 | ||
438 | Note that MHD will run automatically in background thread(s) only | 442 | Note that MHD will run automatically in background thread(s) only if |
439 | if @code{MHD_USE_INTERNAL_POLLING_THREAD} is used. Otherwise caller | 443 | @code{MHD_USE_INTERNAL_POLLING_THREAD} is used. Otherwise caller |
440 | (application) must use @code{MHD_run} or @code{MHD_run_from_select} | 444 | (application) must use @code{MHD_run} or @code{MHD_run_from_select} to |
441 | to have MHD processed network connections and data. | 445 | have MHD processed network connections and data. |
442 | 446 | ||
443 | Starting the daemon may also fail if a particular option is not | 447 | Starting the daemon may also fail if a particular option is not |
444 | implemented or not supported on the target platform (i.e. no support for | 448 | implemented or not supported on the target platform (i.e. no support |
445 | @acronym{SSL}, threads or IPv6). SSL support generally depends on | 449 | for @acronym{TLS}, threads or IPv6). TLS support generally depends on |
446 | options given during MHD compilation. Threaded operations | 450 | options given during MHD compilation. Threaded operations (including |
447 | (including @code{MHD_USE_INTERNAL_POLLING_THREAD}) are not supported on | 451 | @code{MHD_USE_INTERNAL_POLLING_THREAD}) are not supported on Symbian. |
448 | Symbian. | ||
449 | 452 | ||
450 | @table @code | 453 | @table @code |
451 | @item MHD_NO_FLAG | 454 | @item MHD_NO_FLAG |
452 | No options selected. | 455 | No options selected. |
453 | 456 | ||
457 | @item MHD_USE_ERROR_LOG | ||
458 | If this flag is used, the library should print error messages and | ||
459 | warnings to stderr (or to custom error printer if it's specified by | ||
460 | options). Note that for this run-time option to have any effect, MHD | ||
461 | needs to be compiled with messages enabled. This is done by default | ||
462 | except you ran configure with the @code{--disable-messages} flag set. | ||
463 | |||
454 | @item MHD_USE_DEBUG | 464 | @item MHD_USE_DEBUG |
455 | @cindex debugging | 465 | @cindex debugging |
456 | Run in debug mode. If this flag is used, the library should print error | 466 | Currently the same as @code{MHD_USE_ERROR_LOG}. |
457 | messages and warnings to stderr. Note that for this | ||
458 | run-time option to have any effect, MHD needs to be | ||
459 | compiled with messages enabled. This is done by default except you ran | ||
460 | configure with the @code{--disable-messages} flag set. | ||
461 | 467 | ||
462 | @item MHD_USE_SSL | 468 | @item MHD_USE_TLS |
463 | @cindex TLS | 469 | @cindex TLS |
464 | @cindex SSL | 470 | @cindex SSL |
465 | Run in HTTPS-mode. If you specify @code{MHD_USE_SSL} and MHD was | 471 | Run in HTTPS-mode. If you specify @code{MHD_USE_TLS} and MHD was |
466 | compiled without SSL support, @code{MHD_start_daemon} will return | 472 | compiled without SSL support, @code{MHD_start_daemon} will return |
467 | NULL. | 473 | NULL. |
468 | 474 | ||
@@ -515,13 +521,13 @@ Use @code{epoll()} instead of @code{poll()} or @code{select()}. This | |||
515 | allows sockets with descriptors @code{>= FD_SETSIZE}. This option is | 521 | allows sockets with descriptors @code{>= FD_SETSIZE}. This option is |
516 | only available on some systems and does not work in conjunction with | 522 | only available on some systems and does not work in conjunction with |
517 | @code{MHD_USE_THREAD_PER_CONNECTION} (at this point). If you specify | 523 | @code{MHD_USE_THREAD_PER_CONNECTION} (at this point). If you specify |
518 | @code{MHD_USE_EPOLL} and the local platform does not | 524 | @code{MHD_USE_EPOLL} and the local platform does not support it, |
519 | support it, @code{MHD_start_daemon} will return NULL. Using | 525 | @code{MHD_start_daemon} will return NULL. Using @code{epoll()} |
520 | @code{epoll()} instead of @code{select()} or @code{poll()} can in some | 526 | instead of @code{select()} or @code{poll()} can in some situations |
521 | situations result in significantly higher performance as the system | 527 | result in significantly higher performance as the system call has |
522 | call has fundamentally lower complexity (O(1) for @code{epoll()} | 528 | fundamentally lower complexity (O(1) for @code{epoll()} vs. O(n) for |
523 | vs. O(n) for @code{select()}/@code{poll()} where n is the number of | 529 | @code{select()}/@code{poll()} where n is the number of open |
524 | open connections). | 530 | connections). |
525 | 531 | ||
526 | @item MHD_USE_TURBO | 532 | @item MHD_USE_TURBO |
527 | @cindex performance | 533 | @cindex performance |
@@ -559,14 +565,14 @@ connect HTTP clients to the HTTP server. This option is incompatible | |||
559 | with using a thread pool; if it is used, | 565 | with using a thread pool; if it is used, |
560 | @code{MHD_OPTION_THREAD_POOL_SIZE} is ignored. | 566 | @code{MHD_OPTION_THREAD_POOL_SIZE} is ignored. |
561 | 567 | ||
568 | |||
562 | @item MHD_USE_ITC | 569 | @item MHD_USE_ITC |
563 | @cindex quiesce | 570 | @cindex quiesce |
564 | Force MHD to use a signal inter-thread communication channel to notify | 571 | Force MHD to use a signal inter-thread communication channel to notify |
565 | the event loop (of threads) of our shutdown and other events. | 572 | the event loop (of threads) of our shutdown and other events. This is |
566 | This is required if an application uses | 573 | required if an application uses @code{MHD_USE_INTERNAL_POLLING_THREAD} |
567 | @code{MHD_USE_INTERNAL_POLLING_THREAD} and then performs | 574 | and then performs @code{MHD_quiesce_daemon} (which eliminates our |
568 | @code{MHD_quiesce_daemon} (which eliminates our ability to signal | 575 | ability to signal termination via the listen socket). In these modes, |
569 | termination via the listen socket). In these modes, | ||
570 | @code{MHD_quiesce_daemon} will fail if this option was not set. Also, | 576 | @code{MHD_quiesce_daemon} will fail if this option was not set. Also, |
571 | use of this option is automatic (as in, you do not even have to | 577 | use of this option is automatic (as in, you do not even have to |
572 | specify it), if @code{MHD_USE_NO_LISTEN_SOCKET} is specified. In | 578 | specify it), if @code{MHD_USE_NO_LISTEN_SOCKET} is specified. In |
@@ -588,6 +594,7 @@ Enable TCP_FASTOPEN on the listen socket. TCP_FASTOPEN is currently | |||
588 | supported on Linux >= 3.6. On other systems using this option with | 594 | supported on Linux >= 3.6. On other systems using this option with |
589 | cause @code{MHD_start_daemon} to fail. | 595 | cause @code{MHD_start_daemon} to fail. |
590 | 596 | ||
597 | |||
591 | @item MHD_ALLOW_UPGRADE | 598 | @item MHD_ALLOW_UPGRADE |
592 | @cindex upgrade | 599 | @cindex upgrade |
593 | This option must be set if you want to upgrade connections | 600 | This option must be set if you want to upgrade connections |
@@ -595,6 +602,14 @@ This option must be set if you want to upgrade connections | |||
595 | allocate additional resources, and hence we require this | 602 | allocate additional resources, and hence we require this |
596 | special flag so we only use the resources that are really needed. | 603 | special flag so we only use the resources that are really needed. |
597 | 604 | ||
605 | |||
606 | @item MHD_USE_AUTO | ||
607 | Automatically select best event loop style (polling function) | ||
608 | depending on requested mode by other MHD flags and functions available | ||
609 | on platform. If application doesn't have requirements for any | ||
610 | specific polling function, it's recommended to use this flag. This | ||
611 | flag is very convenient for multiplatform applications. | ||
612 | |||
598 | @end table | 613 | @end table |
599 | @end deftp | 614 | @end deftp |
600 | 615 | ||