[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r5470 - libmicrohttpd-docs/WWW
From: |
gnunet |
Subject: |
[GNUnet-SVN] r5470 - libmicrohttpd-docs/WWW |
Date: |
Sat, 11 Aug 2007 21:35:55 -0600 (MDT) |
Author: grothoff
Date: 2007-08-11 21:35:55 -0600 (Sat, 11 Aug 2007)
New Revision: 5470
Modified:
libmicrohttpd-docs/WWW/index.php
Log:
docu
Modified: libmicrohttpd-docs/WWW/index.php
===================================================================
--- libmicrohttpd-docs/WWW/index.php 2007-08-11 23:15:23 UTC (rev 5469)
+++ libmicrohttpd-docs/WWW/index.php 2007-08-12 03:35:55 UTC (rev 5470)
@@ -66,6 +66,9 @@
ANCHOR("using");
H2("Using libmicrohttpd");
BP();
+W("The <tt>microhttpd.h</tt> include file documents most of the API in
detail.");
+W("This webpage only gives a general overview.");
+P();
W("Here is a minimal example (included in the distribution):");
?>
<pre>
@@ -77,12 +80,6 @@
#define PAGE "<html><head><title>libmicrohttpd demo</title>"\
"</head><body>libmicrohttpd demo</body></html>"
-static int apc_all(void * cls,
- const struct sockaddr * addr,
- socklen_t addrlen) {
- return MHD_YES; /* accept connections from anyone */
-}
-
static int ahc_echo(void * cls,
struct MHD_Connection * connection,
const char * url,
@@ -90,14 +87,14 @@
const char * upload_data,
const char * version,
unsigned int * upload_data_size) {
- const char * me = cls;
+ const char * page = cls;
struct MHD_Response * response;
int ret;
if (0 != strcmp(method, "GET"))
return MHD_NO; /* unexpected method */
- response = MHD_create_response_from_data(strlen(me),
- (void*) me,
+ response = MHD_create_response_from_data(strlen(page),
+ (void*) page,
MHD_NO,
MHD_NO);
ret = MHD_queue_response(connection,
@@ -117,8 +114,8 @@
}
d = MHD_start_daemon(MHD_USE_THREAD_PER_CONNECTION,
atoi(argv[1]),
- &apc_all,
NULL,
+ NULL,
&ahc_echo,
PAGE,
MHD_OPTION_END);
@@ -130,9 +127,48 @@
}
</pre>
<?php
+EP();
+H3("Threading models");
+BP();
+W("The example above uses the simplest threading model,
<tt>MHD_USE_THREAD_PER_CONNECTION</tt>.");
+W("In this model, MHD starts one thread to listen on the port for new
connections and then spawns a new thread to handle each connection.");
+W("This model is great if the HTTP server has hardly any state that is shared
between connections (no synchronization issues!) and may need to perform
blocking operations (such as extensive IO or running of code) to handle an
individual connection.");
P();
-W("For more information about the API, study the <tt>microhttpd.h</tt> include
file.");
+W("The second threading model, <tt>MHD_USE_SELECT_INTERNALLY</tt>, uses only a
single thread to handle listening on the port and processing of requests.");
+W("This model is preferable if spawning a thread for each connection would be
costly.");
+W("If the HTTP server is able to quickly produce responses without much
computational overhead for each connection, this model can be a great choice.");
+W("Note that MHD will still start a single thread -- the main program can
continue with its operations.");
+W("Naturally, if the HTTP server needs to interact with shared state in the
main application, synchronization will be required.");
+W("If such synchronization in code providing a response results in blocking,
all HTTP server operations on all connections will stall.");
+P();
+W("The third threading model (used when no specific flag is given), uses no
threads.");
+W("Instead, the main application must (periodically) request file descriptor
sets from MHD, perform a select call and then call <tt>MHD_run</tt>.");
+W("<tt>MHD_run</tt> will then process HTTP requests as usual and return.");
+W("<tt>MHD_run</tt> is guaranteed to not block; however, access handlers and
response processing callbacks that it invokes may block.");
+W("This mode is useful if a single-threaded implementation is desired and in
particular if the main application already uses a select loop for its
processing.");
+P();
+W("The testcases provided include examples for using each of the three
threading modes.");
EP();
+H3("Responses");
+BP();
+W("MHD provides various functions to create <tt>struct MHD_Response</tt>
objects.");
+W("A response consists of a set of HTTP headers and a (possibly empty) body.");
+W("The two main ways to create a response are either by specifying a given
(fixed-size) body (<tt>MHD_create_response_from_data</tt>) or by providing a
function of type <tt>MHD_ContentReaderCallback</tt> which provides portions of
the response as needed.");
+W("The first response construction is great for small and in particular static
webpages that fit into memory.");
+W("The second response type should be used for response objects where the size
is initially not known or where the response maybe too large to fit into
memory.");
+P();
+W("A response is used by calling <tt>MHD_queue_response</tt> which sends the
response back to the client on the specified connection.");
+W("Once created, a response object can be used any number of times.");
+W("Internally, each response uses a reference counter.");
+W("The response is freed once the reference counter reaches zero.");
+W("The HTTP server should call <tt>MHD_destroy_response</tt> when a response
object is no longer needed, that is, the server will not call
<tt>MHD_queue_response</tt> again using this response object.");
+W("Note that this does not mean that the response will be immediately
destroyed -- destruction maybe delayed until sending of the response is
complete on all connections that have the response in the queue.");
+P();
+W("Clients should never queue a "100 CONTINUE" response.");
+W("MHD handles "100 CONTINUE" internally and only allows clients to
queue a single response per connection.");
+W("Furthermore, clients must not queue a response before the request has been
fully received.");
+W("If a client attempts to queue multiple responses or attempts to queue a
response early, <tt>MHD_queue_response<tt> will fail (and return
<tt>MHD_NO</tt>).");
+EP();
ANCHOR("mantis");
H2("Bugtrack");
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r5470 - libmicrohttpd-docs/WWW,
gnunet <=