walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity
nghttp2/libnghttp2_asio.html

489 lines
33 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>libnghttp2_asio: High level HTTP/2 C++ library &mdash; nghttp2 0.6.3-DEV documentation</title>
<link href='https://fonts.googleapis.com/css?family=Lato:400,700,400italic,700italic|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="top" title="nghttp2 0.6.3-DEV documentation" href="index.html"/>
<link rel="next" title="Python API Reference" href="python-apiref.html"/>
<link rel="prev" title="API Reference" href="apiref.html"/>
<script src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="index.html" class="fa fa-home"> nghttp2</a>
<div role="search">
<form id ="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="package_README.html">nghttp2 - HTTP/2 C Library</a><ul>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#development-status">Development Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#public-test-server">Public Test Server</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#requirements">Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#build-from-git">Build from git</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#building-documentation">Building documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#client-server-and-proxy-programs">Client, Server and Proxy programs</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#benchmarking-tool">Benchmarking tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#hpack-tools">HPACK tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#libnghttp2-asio-high-level-http-2-c-library">libnghttp2_asio: High level HTTP/2 C++ library</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#python-bindings">Python bindings</a></li>
<li class="toctree-l2"><a class="reference internal" href="package_README.html#contribution">Contribution</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="building-android-binary.html">Building Android binary</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-client.html">Tutorial: HTTP/2 client</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial-client.html#libevent-client-c">libevent-client.c</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-server.html">Tutorial: HTTP/2 server</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial-server.html#libevent-server-c">libevent-server.c</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-hpack.html">Tutorial: HPACK API</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial-hpack.html#deflating-encoding-headers">Deflating (encoding) headers</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-hpack.html#inflating-decoding-headers">Inflating (decoding) headers</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial-hpack.html#deflate-c">deflate.c</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nghttp.1.html">nghttp(1)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nghttp.1.html#name">NAME</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttp.1.html#synopsis">SYNOPSIS</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttp.1.html#description">DESCRIPTION</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttp.1.html#options">OPTIONS</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttp.1.html#see-also">SEE ALSO</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nghttpd.1.html">nghttpd(1)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nghttpd.1.html#name">NAME</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpd.1.html#synopsis">SYNOPSIS</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpd.1.html#description">DESCRIPTION</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpd.1.html#options">OPTIONS</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpd.1.html#see-also">SEE ALSO</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nghttpx.1.html">nghttpx(1)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nghttpx.1.html#name">NAME</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx.1.html#synopsis">SYNOPSIS</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx.1.html#description">DESCRIPTION</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx.1.html#options">OPTIONS</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx.1.html#see-also">SEE ALSO</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="h2load.1.html">h2load(1)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="h2load.1.html#name">NAME</a></li>
<li class="toctree-l2"><a class="reference internal" href="h2load.1.html#synopsis">SYNOPSIS</a></li>
<li class="toctree-l2"><a class="reference internal" href="h2load.1.html#description">DESCRIPTION</a></li>
<li class="toctree-l2"><a class="reference internal" href="h2load.1.html#options">OPTIONS</a></li>
<li class="toctree-l2"><a class="reference internal" href="h2load.1.html#see-also">SEE ALSO</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nghttpx-howto.html">nghttpx - HTTP/2 proxy - HOW-TO</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#default-mode">Default mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#http-2-proxy-mode">HTTP/2 proxy mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#client-mode">Client mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#client-proxy-mode">Client proxy mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#http-2-bridge-mode">HTTP/2 bridge mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#disable-ssl-tls">Disable SSL/TLS</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#specifying-additional-ca-certificate">Specifying additional CA certificate</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#read-write-rate-limit">Read/write rate limit</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#rewriting-location-header-field">Rewriting location header field</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#hot-deploy">Hot deploy</a></li>
<li class="toctree-l2"><a class="reference internal" href="nghttpx-howto.html#re-opening-log-files">Re-opening log files</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="h2load-howto.html">h2load - HTTP/2 benchmarking tool - HOW-TO</a><ul>
<li class="toctree-l2"><a class="reference internal" href="h2load-howto.html#basic-usage">Basic Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="h2load-howto.html#flow-control">Flow Control</a></li>
<li class="toctree-l2"><a class="reference internal" href="h2load-howto.html#multi-threading">Multi-Threading</a></li>
<li class="toctree-l2"><a class="reference internal" href="h2load-howto.html#selecting-protocol-for-clear-text">Selecting protocol for clear text</a></li>
<li class="toctree-l2"><a class="reference internal" href="h2load-howto.html#multiple-uris">Multiple URIs</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="apiref.html">API Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#includes">Includes</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#remarks">Remarks</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#macros">Macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#enums">Enums</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#types-structs-unions-and-typedefs">Types (structs, unions and typedefs)</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#functions">Functions</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="current reference internal" href="">libnghttp2_asio: High level HTTP/2 C++ library</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#server-api">Server API</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="python-apiref.html">Python API Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="python-apiref.html#hpack-api">HPACK API</a></li>
<li class="toctree-l2"><a class="reference internal" href="python-apiref.html#http-2-servers">HTTP/2 servers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nghttp2.h.html">nghttp2.h</a></li>
<li class="toctree-l1"><a class="reference internal" href="nghttp2ver.h.html">nghttp2ver.h</a></li>
<li class="toctree-l1"><a class="reference internal" href="asio_http2.h.html">asio_http2.h</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/tatsuhiro-t/nghttp2">Source</a></li>
<li class="toctree-l1"><a class="reference external" href="https://github.com/tatsuhiro-t/nghttp2/issues">Issues</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">nghttp2</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>libnghttp2_asio: High level HTTP/2 C++ library</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document">
<div class="section" id="libnghttp2-asio-high-level-http-2-c-library">
<h1>libnghttp2_asio: High level HTTP/2 C++ library<a class="headerlink" href="#libnghttp2-asio-high-level-http-2-c-library" title="Permalink to this headline"></a></h1>
<p>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.</p>
<p>libnghttp2_asio is not built by default. Use <tt class="docutils literal"><span class="pre">--enable-asio-lib</span></tt>
configure flag to build libnghttp2_asio. The required Boost libraries
are:</p>
<ul class="simple">
<li>Boost::Asio</li>
<li>Boost::System</li>
<li>Boost::Thread</li>
</ul>
<p>To use libnghttp2_asio, first include following header file:</p>
<div class="highlight-cpp"><div class="highlight"><pre><span class="cp">#include &lt;nghttp2/asio_http2.h&gt;</span>
</pre></div>
</div>
<p>Also take a look at that header file <a class="reference internal" href="asio_http2.h.html"><em>asio_http2.h</em></a>.</p>
<div class="section" id="server-api">
<h2>Server API<a class="headerlink" href="#server-api" title="Permalink to this headline"></a></h2>
<p>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:</p>
<div class="highlight-cpp"><div class="highlight"><pre><span class="cp">#include &lt;nghttp2/asio_http2.h&gt;</span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">nghttp2</span><span class="o">::</span><span class="n">asio_http2</span><span class="p">;</span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">nghttp2</span><span class="o">::</span><span class="n">asio_http2</span><span class="o">::</span><span class="n">server</span><span class="p">;</span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">*</span> <span class="n">argv</span><span class="p">[])</span>
<span class="p">{</span>
<span class="n">http2</span> <span class="n">server</span><span class="p">;</span>
<span class="n">server</span><span class="p">.</span><span class="n">listen</span>
<span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">,</span> <span class="mi">3000</span><span class="p">,</span>
<span class="p">[](</span><span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o">&lt;</span><span class="n">request</span><span class="o">&gt;</span> <span class="n">req</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o">&lt;</span><span class="n">response</span><span class="o">&gt;</span> <span class="n">res</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">write_head</span><span class="p">(</span><span class="mi">200</span><span class="p">);</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">end</span><span class="p">(</span><span class="s">&quot;hello, world&quot;</span><span class="p">);</span>
<span class="p">});</span>
<span class="p">}</span>
</pre></div>
</div>
<p>First we instantiate <tt class="docutils literal"><span class="pre">nghttp2::asio_http2::server::http2</span></tt> object.
Then call <tt class="docutils literal"><span class="pre">nghttp2::asio_http2::server::http2::listen</span></tt> function with
address and port to listen to and callback function, namely &#8220;request
callback&#8221;, invoked when request arrives.</p>
<p>The <tt class="docutils literal"><span class="pre">req</span></tt> and <tt class="docutils literal"><span class="pre">res</span></tt> represent HTTP request and response
respectively. <tt class="docutils literal"><span class="pre">nghttp2::asio_http2_::server::response::write_head</span></tt>
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.</p>
<p><tt class="docutils literal"><span class="pre">nghttp2::asio_http2::server::response::end</span></tt> sends responde body.
In the above example, we send string &#8220;hello, world&#8221;.</p>
<div class="section" id="serving-static-files-and-enabling-ssl-tls">
<h3>Serving static files and enabling SSL/TLS<a class="headerlink" href="#serving-static-files-and-enabling-ssl-tls" title="Permalink to this headline"></a></h3>
<p>In this example, we serve a couple of static files and also enable
SSL/TLS.</p>
<div class="highlight-cpp"><div class="highlight"><pre><span class="cp">#include &lt;nghttp2/asio_http2.h&gt;</span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">nghttp2</span><span class="o">::</span><span class="n">asio_http2</span><span class="p">;</span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">nghttp2</span><span class="o">::</span><span class="n">asio_http2</span><span class="o">::</span><span class="n">server</span><span class="p">;</span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">*</span> <span class="n">argv</span><span class="p">[])</span>
<span class="p">{</span>
<span class="n">http2</span> <span class="n">server</span><span class="p">;</span>
<span class="n">server</span><span class="p">.</span><span class="n">tls</span><span class="p">(</span><span class="s">&quot;server.key&quot;</span><span class="p">,</span> <span class="s">&quot;server.crt&quot;</span><span class="p">);</span>
<span class="n">server</span><span class="p">.</span><span class="n">listen</span>
<span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">,</span> <span class="mi">3000</span><span class="p">,</span>
<span class="p">[](</span><span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o">&lt;</span><span class="n">request</span><span class="o">&gt;</span> <span class="n">req</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o">&lt;</span><span class="n">response</span><span class="o">&gt;</span> <span class="n">res</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">if</span><span class="p">(</span><span class="n">req</span><span class="o">-&gt;</span><span class="n">path</span><span class="p">()</span> <span class="o">==</span> <span class="s">&quot;/&quot;</span> <span class="o">||</span> <span class="n">req</span><span class="o">-&gt;</span><span class="n">path</span><span class="p">()</span> <span class="o">==</span> <span class="s">&quot;/index.html&quot;</span><span class="p">)</span> <span class="p">{</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">write_head</span><span class="p">(</span><span class="mi">200</span><span class="p">);</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">end</span><span class="p">(</span><span class="n">file_reader</span><span class="p">(</span><span class="s">&quot;index.html&quot;</span><span class="p">));</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">write_head</span><span class="p">(</span><span class="mi">404</span><span class="p">);</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">end</span><span class="p">(</span><span class="s">&quot;&lt;html&gt;&lt;head&gt;&lt;title&gt;404&lt;/title&gt;&lt;/head&gt;&quot;</span>
<span class="s">&quot;&lt;body&gt;404 Not Found&lt;/body&gt;&lt;/html&gt;&quot;</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">});</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Specifying path to private key file and certificate file in
<tt class="docutils literal"><span class="pre">nghttp2::asio_http2::server::http2::tls</span></tt> will enable SSL/TLS. Both
files must be in PEM format.</p>
<p>In the above example, if request path is either &#8220;/&#8221; or &#8220;/index.html&#8221;,
we serve index.html file in the current working directory.
<tt class="docutils literal"><span class="pre">nghttp2::asio_http2::server::response::end</span></tt> has overload to take
function of type <tt class="docutils literal"><span class="pre">nghttp2::asio_http2::read_cb</span></tt> and application pass
its implementation to generate response body. For the convenience,
libnghttp2_asio library provides <tt class="docutils literal"><span class="pre">nghttp2::asio_http2::file_reader</span></tt>
function to generate function to server static file.</p>
</div>
<div class="section" id="server-push">
<h3>Server push<a class="headerlink" href="#server-push" title="Permalink to this headline"></a></h3>
<p>Server push is also supported.</p>
<div class="highlight-cpp"><div class="highlight"><pre><span class="cp">#include &lt;nghttp2/asio_http2.h&gt;</span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">nghttp2</span><span class="o">::</span><span class="n">asio_http2</span><span class="p">;</span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">nghttp2</span><span class="o">::</span><span class="n">asio_http2</span><span class="o">::</span><span class="n">server</span><span class="p">;</span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">*</span> <span class="n">argv</span><span class="p">[])</span>
<span class="p">{</span>
<span class="n">http2</span> <span class="n">server</span><span class="p">;</span>
<span class="n">server</span><span class="p">.</span><span class="n">tls</span><span class="p">(</span><span class="s">&quot;server.key&quot;</span><span class="p">,</span> <span class="s">&quot;server.crt&quot;</span><span class="p">);</span>
<span class="n">server</span><span class="p">.</span><span class="n">listen</span>
<span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">,</span> <span class="mi">3000</span><span class="p">,</span>
<span class="p">[](</span><span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o">&lt;</span><span class="n">request</span><span class="o">&gt;</span> <span class="n">req</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o">&lt;</span><span class="n">response</span><span class="o">&gt;</span> <span class="n">res</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">if</span><span class="p">(</span><span class="n">req</span><span class="o">-&gt;</span><span class="n">path</span><span class="p">()</span> <span class="o">==</span> <span class="s">&quot;/&quot;</span><span class="p">)</span> <span class="p">{</span>
<span class="n">req</span><span class="o">-&gt;</span><span class="n">push</span><span class="p">(</span><span class="s">&quot;GET&quot;</span><span class="p">,</span> <span class="s">&quot;/my.css&quot;</span><span class="p">);</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">write_head</span><span class="p">(</span><span class="mi">200</span><span class="p">);</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">end</span><span class="p">(</span><span class="n">file_reader</span><span class="p">(</span><span class="s">&quot;index.html&quot;</span><span class="p">));</span>
<span class="k">return</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">if</span><span class="p">(</span><span class="n">req</span><span class="o">-&gt;</span><span class="n">path</span><span class="p">()</span> <span class="o">==</span> <span class="s">&quot;/my.css&quot;</span><span class="p">)</span> <span class="p">{</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">write_head</span><span class="p">(</span><span class="mi">200</span><span class="p">);</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">end</span><span class="p">(</span><span class="n">file_reader</span><span class="p">(</span><span class="s">&quot;my.css&quot;</span><span class="p">));</span>
<span class="k">return</span><span class="p">;</span>
<span class="p">}</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">write_head</span><span class="p">(</span><span class="mi">404</span><span class="p">);</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">end</span><span class="p">(</span><span class="s">&quot;&lt;html&gt;&lt;head&gt;&lt;title&gt;404&lt;/title&gt;&lt;/head&gt;&quot;</span>
<span class="s">&quot;&lt;body&gt;404 Not Found&lt;/body&gt;&lt;/html&gt;&quot;</span><span class="p">);</span>
<span class="p">});</span>
<span class="p">}</span>
</pre></div>
</div>
<p>When client requested &#8220;/&#8221;, we push &#8220;/my.css&#8221;. To push resource, call
<tt class="docutils literal"><span class="pre">nghttp2::asio_http2::server::request::push</span></tt> function with desired
method and path. Later, the callback will be called with the pushed
resource &#8220;/my.css&#8221;.</p>
</div>
<div class="section" id="enable-multi-threading">
<h3>Enable multi-threading<a class="headerlink" href="#enable-multi-threading" title="Permalink to this headline"></a></h3>
<p>Enabling multi-threading is very easy. Just call
<tt class="docutils literal"><span class="pre">nghttp2::asio_http2::server::http2::num_threads</span></tt> function with the
desired number of threads:</p>
<div class="highlight-cpp"><div class="highlight"><pre><span class="n">http2</span> <span class="n">server</span><span class="p">;</span>
<span class="c1">// Use 4 native threads</span>
<span class="n">server</span><span class="p">.</span><span class="n">num_threads</span><span class="p">(</span><span class="mi">4</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="run-blocking-tasks-in-background-thread">
<h3>Run blocking tasks in background thread<a class="headerlink" href="#run-blocking-tasks-in-background-thread" title="Permalink to this headline"></a></h3>
<p>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.</p>
<p>To run blocking tasks, use
<tt class="docutils literal"><span class="pre">nghttp2::asio_http2::server::request::run_task</span></tt>. 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:</p>
<div class="highlight-cpp"><div class="highlight"><pre><span class="cp">#include &lt;unistd.h&gt;</span>
<span class="cp">#include &lt;nghttp2/asio_http2.h&gt;</span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">nghttp2</span><span class="o">::</span><span class="n">asio_http2</span><span class="p">;</span>
<span class="k">using</span> <span class="k">namespace</span> <span class="n">nghttp2</span><span class="o">::</span><span class="n">asio_http2</span><span class="o">::</span><span class="n">server</span><span class="p">;</span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">*</span> <span class="n">argv</span><span class="p">[])</span>
<span class="p">{</span>
<span class="n">http2</span> <span class="n">server</span><span class="p">;</span>
<span class="n">server</span><span class="p">.</span><span class="n">num_concurrent_tasks</span><span class="p">(</span><span class="mi">16</span><span class="p">);</span>
<span class="n">server</span><span class="p">.</span><span class="n">listen</span>
<span class="p">(</span><span class="s">&quot;*&quot;</span><span class="p">,</span> <span class="mi">3000</span><span class="p">,</span>
<span class="p">[](</span><span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o">&lt;</span><span class="n">request</span><span class="o">&gt;</span> <span class="n">req</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">shared_ptr</span><span class="o">&lt;</span><span class="n">response</span><span class="o">&gt;</span> <span class="n">res</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">req</span><span class="o">-&gt;</span><span class="n">run_task</span>
<span class="p">([</span><span class="n">res</span><span class="p">](</span><span class="n">channel</span><span class="o">&amp;</span> <span class="n">channel</span><span class="p">)</span>
<span class="p">{</span>
<span class="c1">// executed in different thread than the thread where</span>
<span class="c1">// request callback was executed.</span>
<span class="c1">// using res directly here is not safe. Capturing it by</span>
<span class="c1">// value is safe because it is std::shared_ptr.</span>
<span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
<span class="n">channel</span><span class="p">.</span><span class="n">post</span>
<span class="p">([</span><span class="n">res</span><span class="p">]()</span>
<span class="p">{</span>
<span class="c1">// executed in the same thread where request callback</span>
<span class="c1">// was executed.</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">write_head</span><span class="p">(</span><span class="mi">200</span><span class="p">);</span>
<span class="n">res</span><span class="o">-&gt;</span><span class="n">end</span><span class="p">(</span><span class="s">&quot;hello, world&quot;</span><span class="p">);</span>
<span class="p">});</span>
<span class="p">});</span>
<span class="p">});</span>
<span class="p">}</span>
</pre></div>
</div>
<p>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.</p>
<p>We call <tt class="docutils literal"><span class="pre">req-&gt;run_task()</span></tt> 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 <tt class="docutils literal"><span class="pre">req-&gt;run_task()</span></tt> is executed in the
different thread from the thread where request callback is called,
using <tt class="docutils literal"><span class="pre">req</span></tt> or <tt class="docutils literal"><span class="pre">res</span></tt> object directly there may cause undefined
behaviour. To avoid this issue, we can use
<tt class="docutils literal"><span class="pre">nghttp2::asio_http2::channel::post</span></tt> by supplying a callback which
in turn get called in the same thread where request callback was
called.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="python-apiref.html" class="btn btn-neutral float-right" title="Python API Reference">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="apiref.html" class="btn btn-neutral" title="API Reference"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2012, 2014, Tatsuhiro Tsujikawa.
</p>
</div>
<a href="https://github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'0.6.3-DEV',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: false
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink