From 6bea32e5f9921f6e39f59338e48dd42206a5dc7d Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Mon, 29 Sep 2014 00:05:31 +0900 Subject: [PATCH] Update doc --- apiref.html | 19 +- asio_http2.h.html | 511 +++++++++++++++++++++++++++++++++++ building-android-binary.html | 15 +- genindex.html | 12 +- h2load-howto.html | 12 +- h2load.1.html | 12 +- index.html | 26 +- libnghttp2_asio.html | 489 +++++++++++++++++++++++++++++++++ nghttp.1.html | 12 +- nghttp2.h.html | 15 +- nghttp2ver.h.html | 17 +- nghttpd.1.html | 12 +- nghttpx-howto.html | 12 +- nghttpx.1.html | 12 +- objects.inv | Bin 3942 -> 3944 bytes package_README.html | 56 +++- py-modindex.html | 12 +- python-apiref.html | 16 +- search.html | 12 +- searchindex.js | 2 +- tutorial-client.html | 12 +- tutorial-hpack.html | 12 +- tutorial-server.html | 12 +- 23 files changed, 1234 insertions(+), 76 deletions(-) create mode 100644 asio_http2.h.html create mode 100644 libnghttp2_asio.html diff --git a/apiref.html b/apiref.html index 81e2cd99..81554de6 100644 --- a/apiref.html +++ b/apiref.html @@ -7,7 +7,7 @@ - API Reference — nghttp2 0.6.2-DEV documentation + API Reference — nghttp2 0.6.2 documentation @@ -28,8 +28,8 @@ - - + + @@ -69,6 +69,7 @@
  • Client, Server and Proxy programs
  • Benchmarking tool
  • HPACK tools
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library
  • Python bindings
  • Contribution
    • @@ -151,6 +152,10 @@
  • Functions
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library +
  • Python API Reference @@ -2408,8 +2414,7 @@ to the outbound queue.

    negative error codes:

    NGHTTP2_ERR_INVALID_ARGUMENT
    -
    The stream does not exist; or no deferred data exist; or data -was deferred by flow control.
    +
    The stream does not exist; or no deferred data exist.
    NGHTTP2_ERR_NOMEM
    Out of memory.
    @@ -3406,7 +3411,7 @@ always succeeds.

  • Client, Server and Proxy programs
  • Benchmarking tool
  • HPACK tools
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library
  • Python bindings
  • Contribution
    • @@ -151,6 +152,10 @@
  • Functions
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library +
  • Python API Reference @@ -207,8 +213,7 @@ for ANDROID_HOME. Fo unpacked:

    $ build/tools/make-standalone-toolchain.sh \
   --install-dir=$ANDROID_HOME/toolchain \
-  --toolchain=arm-linux-androideabi-4.8 \
-  --llvm-version=3.4
+  --toolchain=arm-linux-androideabi-4.8

    The additional flag --system=linux-x86_64 may be required if you @@ -343,7 +348,7 @@ using the following command:

    @@ -68,6 +68,7 @@
  • Client, Server and Proxy programs
  • Benchmarking tool
  • HPACK tools
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library
  • Python bindings
  • Contribution
    • @@ -150,6 +151,10 @@
  • Functions
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library +
  • Python API Reference @@ -3476,7 +3482,7 @@ + + + + + +
    + + + + +
    + + + + + + +
    +
    +
    +
      +
    • Docs »
      • + +
    • libnghttp2_asio: High level HTTP/2 C++ library
      • +
    • + +
      • +
    +
    +
    +
    + +
    +

    libnghttp2_asio: High level HTTP/2 C++ library

    +

    libnghttp2_asio is C++ library built on top of libnghttp2 and provides +high level abstraction API to build HTTP/2 applications. It depends +on Boost::ASIO library and OpenSSL. Currently libnghttp2_asio +provides server side API.

    +

    libnghttp2_asio is not built by default. Use --enable-asio-lib +configure flag to build libnghttp2_asio. The required Boost libraries +are:

    +
      +
    • Boost::Asio
      • +
    • Boost::System
      • +
    • Boost::Thread
      • +
    +

    To use libnghttp2_asio, first include following header file:

    +
    #include <nghttp2/asio_http2.h>
+
    +
    +

    Also take a look at that header file asio_http2.h.

    +
    +

    Server API

    +

    Server API is designed to build HTTP/2 server very easily to utilize +C++11 anonymous function and closure. The bare minimum example of +HTTP/2 server looks like this:

    +
    #include <nghttp2/asio_http2.h>
+
+using namespace nghttp2::asio_http2;
+using namespace nghttp2::asio_http2::server;
+
+int main(int argc, char* argv[])
+{
+  http2 server;
+
+  server.listen
+    ("*", 3000,
+     [](std::shared_ptr<request> req, std::shared_ptr<response> res)
+     {
+       res->write_head(200);
+       res->end("hello, world");
+     });
+}
+
    +
    +

    First we instantiate nghttp2::asio_http2::server::http2 object. +Then call nghttp2::asio_http2::server::http2::listen function with +address and port to listen to and callback function, namely “request +callback”, invoked when request arrives.

    +

    The req and res represent HTTP request and response +respectively. nghttp2::asio_http2_::server::response::write_head +constructs HTTP response header fields. The first argument is HTTP +status code, in the above example, which is 200. The second argument, +which is omitted in the above example, is additional header fields to +send.

    +

    nghttp2::asio_http2::server::response::end sends responde body. +In the above example, we send string “hello, world”.

    +
    +

    Serving static files and enabling SSL/TLS

    +

    In this example, we serve a couple of static files and also enable +SSL/TLS.

    +
    #include <nghttp2/asio_http2.h>
+
+using namespace nghttp2::asio_http2;
+using namespace nghttp2::asio_http2::server;
+
+int main(int argc, char* argv[])
+{
+  http2 server;
+
+  server.tls("server.key", "server.crt");
+
+  server.listen
+    ("*", 3000,
+     [](std::shared_ptr<request> req, std::shared_ptr<response> res)
+     {
+       if(req->path() == "/" || req->path() == "/index.html") {
+         res->write_head(200);
+         res->end(file_reader("index.html"));
+       } else {
+         res->write_head(404);
+         res->end("<html><head><title>404</title></head>"
+                  "<body>404 Not Found</body></html>");
+       }
+     });
+}
+
    +
    +

    Specifying path to private key file and certificate file in +nghttp2::asio_http2::server::http2::tls will enable SSL/TLS. Both +files must be in PEM format.

    +

    In the above example, if request path is either “/” or “/index.html”, +we serve index.html file in the current working directory. +nghttp2::asio_http2::server::response::end has overload to take +function of type nghttp2::asio_http2::read_cb and application pass +its implementation to generate response body. For the convenience, +libnghttp2_asio library provides nghttp2::asio_http2::file_reader +function to generate function to server static file.

    +
    +
    +

    Server push

    +

    Server push is also supported.

    +
    #include <nghttp2/asio_http2.h>
+
+using namespace nghttp2::asio_http2;
+using namespace nghttp2::asio_http2::server;
+
+int main(int argc, char* argv[])
+{
+  http2 server;
+
+  server.tls("server.key", "server.crt");
+
+  server.listen
+    ("*", 3000,
+     [](std::shared_ptr<request> req, std::shared_ptr<response> res)
+     {
+       if(req->path() == "/") {
+         req->push("GET", "/my.css");
+
+         res->write_head(200);
+         res->end(file_reader("index.html"));
+
+         return;
+       }
+
+       if(req->path() == "/my.css") {
+         res->write_head(200);
+         res->end(file_reader("my.css"));
+
+         return;
+       }
+
+       res->write_head(404);
+       res->end("<html><head><title>404</title></head>"
+                "<body>404 Not Found</body></html>");
+     });
+}
+
    +
    +

    When client requested “/”, we push “/my.css”. To push resource, call +nghttp2::asio_http2::server::request::push function with desired +method and path. Later, the callback will be called with the pushed +resource “/my.css”.

    +
    +
    +

    Enable multi-threading

    +

    Enabling multi-threading is very easy. Just call +nghttp2::asio_http2::server::http2::num_threads function with the +desired number of threads:

    +
    http2 server;
+
+// Use 4 native threads
+server.num_threads(4);
+
    +
    +
    +
    +

    Run blocking tasks in background thread

    +

    The request callback is called in the same thread where HTTP request +is handled. And many connections shares the same thread, we cannot +directly run blocking tasks in request callback.

    +

    To run blocking tasks, use +nghttp2::asio_http2::server::request::run_task. The passed +callback will be executed in the different thread from the thread +where request callback was executed. So application can perform +blocking task there. The example follows:

    +
    #include <unistd.h>
+#include <nghttp2/asio_http2.h>
+
+using namespace nghttp2::asio_http2;
+using namespace nghttp2::asio_http2::server;
+
+int main(int argc, char* argv[])
+{
+  http2 server;
+
+  server.num_concurrent_tasks(16);
+
+  server.listen
+    ("*", 3000,
+     [](std::shared_ptr<request> req, std::shared_ptr<response> res)
+     {
+       req->run_task
+         ([res](channel& channel)
+          {
+            // executed in different thread than the thread where
+            // request callback was executed.
+
+            // using res directly here is not safe.  Capturing it by
+            // value is safe because it is std::shared_ptr.
+
+            sleep(1);
+
+            channel.post
+              ([res]()
+               {
+                 // executed in the same thread where request callback
+                 // was executed.
+                 res->write_head(200);
+                 res->end("hello, world");
+               });
+          });
+     });
+}
+
    +
    +

    First we set the number of background threads which run tasks. By +default it is set to 1. In this example, we set it to 16, so at most +16 tasks can be executed concurrently without blocking handling new +requests.

    +

    We call req->run_task() to execute task in background thread. In +the passed callback, we just simply sleeps 1 second. After sleep is +over, we schedule another callback to send response to the client. +Since the callback passed to req->run_task() is executed in the +different thread from the thread where request callback is called, +using req or res object directly there may cause undefined +behaviour. To avoid this issue, we can use +nghttp2::asio_http2::channel::post by supplying a callback which +in turn get called in the same thread where request callback was +called.

    +
    +
    +
    + + +
    + +
    +
    + +
    + +
    + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/nghttp.1.html b/nghttp.1.html index 7e77f95f..f48cbc4a 100644 --- a/nghttp.1.html +++ b/nghttp.1.html @@ -7,7 +7,7 @@ - nghttp(1) — nghttp2 0.6.2-DEV documentation + nghttp(1) — nghttp2 0.6.2 documentation @@ -28,7 +28,7 @@ - + @@ -69,6 +69,7 @@
  • Client, Server and Proxy programs
  • Benchmarking tool
  • HPACK tools
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library
  • Python bindings
  • Contribution
    • @@ -151,6 +152,10 @@
  • Functions
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library +
  • Python API Reference @@ -421,7 +427,7 @@ padding. Specify 0 to disable padding.

    @@ -69,6 +69,7 @@
  • Client, Server and Proxy programs
  • Benchmarking tool
  • HPACK tools
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library
  • Python bindings
  • Contribution
    • @@ -151,6 +152,10 @@
  • Functions
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library +
  • Python API Reference @@ -542,7 +548,7 @@ encoded using UTF-8.

    Next - Previous + Previous @@ -571,7 +577,7 @@ encoded using UTF-8.

    @@ -67,6 +67,7 @@
  • Client, Server and Proxy programs
  • Benchmarking tool
  • HPACK tools
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library
  • Python bindings
  • Contribution
    • @@ -149,6 +150,10 @@
  • Functions
    • +
  • libnghttp2_asio: High level HTTP/2 C++ library +
  • Python API Reference @@ -232,7 +238,7 @@