libs/beast/doc/html/beast/using_io.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Networking</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.Beast">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Beast">
   9 <link rel="prev" href="examples.html" title="Examples">
  10 <link rel="next" href="using_io/asio_refresher.html" title="Refresher">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="examples.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="using_io/asio_refresher.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="beast.using_io"></a><a class="link" href="using_io.html" title="Networking">Networking</a>
  28 </h2></div></div></div>
  29 <p>
  30       This library uses the <a href="http://cplusplus.github.io/networking-ts/draft.pdf" target="_top">Networking
  31       Technical Specification</a>, scheduled to become an official part of C++
  32       no sooner than the year 2023. Three implementations exist, with cosmetic differences
  33       but otherwise using the same function signatures and type declarations: Boost.Asio,
  34       stand-alone Asio, and networking-ts-impl. This table shows how a variable of
  35       type <code class="computeroutput"><span class="identifier">io_context</span></code> is declared
  36       in each implementation by including the appropriate header and using a suitable
  37       namespace alias:
  38     </p>
  39 <div class="table">
  40 <a name="beast.using_io.networking_implementations"></a><p class="title"><b>Table&#160;1.2.&#160;Networking Implementations</b></p>
  41 <div class="table-contents"><table class="table" summary="Networking Implementations">
  42 <colgroup>
  43 <col>
  44 <col>
  45 </colgroup>
  46 <thead><tr>
  47 <th>
  48               <p>
  49                 Name
  50               </p>
  51             </th>
  52 <th>
  53               <p>
  54                 Namespace and Header Example
  55               </p>
  56             </th>
  57 </tr></thead>
  58 <tbody>
  59 <tr>
  60 <td>
  61               <p>
  62                 <a href="../../../../../libs/asio/index.html" target="_top">Boost.Asio</a>
  63               </p>
  64             </td>
  65 <td>
  66 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">asio</span><span class="special">/</span><span class="identifier">io_context</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  67 <span class="keyword">namespace</span> <span class="identifier">net</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">;</span>
  68 <span class="identifier">net</span><span class="special">::</span><span class="identifier">io_context</span> <span class="identifier">ioc</span><span class="special">;</span>
  69 </pre>
  70             </td>
  71 </tr>
  72 <tr>
  73 <td>
  74               <p>
  75                 <a href="https://think-async.com/Asio/" target="_top">Asio (Standalone)</a>
  76               </p>
  77             </td>
  78 <td>
  79 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">asio</span><span class="special">/</span><span class="identifier">io_context</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  80 <span class="keyword">namespace</span> <span class="identifier">net</span> <span class="special">=</span> <span class="identifier">asio</span><span class="special">;</span>
  81 <span class="identifier">net</span><span class="special">::</span><span class="identifier">io_context</span> <span class="identifier">ioc</span><span class="special">;</span>
  82 </pre>
  83             </td>
  84 </tr>
  85 <tr>
  86 <td>
  87               <p>
  88                 <a href="https://github.com/chriskohlhoff/networking-ts-impl" target="_top">networking-ts-impl</a>
  89               </p>
  90             </td>
  91 <td>
  92 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">experimental</span><span class="special">/</span><span class="identifier">io_context</span><span class="special">&gt;</span>
  93 <span class="keyword">namespace</span> <span class="identifier">net</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">experimental</span><span class="special">::</span><span class="identifier">net</span><span class="special">;</span>
  94 <span class="identifier">net</span><span class="special">::</span><span class="identifier">io_context</span> <span class="identifier">ioc</span><span class="special">;</span>
  95 </pre>
  96             </td>
  97 </tr>
  98 </tbody>
  99 </table></div>
 100 </div>
 101 <br class="table-break"><p>
 102       This document refers to the three implementations above interchangeably and
 103       collectively as <span class="bold"><strong>Networking</strong></span> (or just <span class="emphasis"><em>networking</em></span>).
 104       The Boost.Asio and Asio flavors of Networking provide additional features not
 105       currently proposed for C++, but likely to appear in a future specification,
 106       such as:
 107     </p>
 108 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 109 <li class="listitem">
 110           <a href="../../../../../doc/html/boost_asio/reference/serial_port.html" target="_top">Serial
 111           ports</a>
 112         </li>
 113 <li class="listitem">
 114           <a href="../../../../../doc/html/boost_asio/reference/local__stream_protocol.html" target="_top">UNIX
 115           domain sockets</a>
 116         </li>
 117 <li class="listitem">
 118           <a href="../../../../../doc/html/boost_asio/reference/signal_set.html" target="_top">POSIX
 119           signals</a> (e.g. SIGINT, SIGABORT)
 120         </li>
 121 <li class="listitem">
 122           <a href="../../../../../doc/html/boost_asio/reference/ssl__stream.html" target="_top">TLS
 123           streams</a> (such as OpenSSL)
 124         </li>
 125 </ul></div>
 126 <p>
 127       Boost.Beast depends specifically on the Boost.Asio flavor of Networking, although
 128       this may change in the future. While this library offers performant implementations
 129       of the HTTP and WebSocket network protocols, it depends on the networking interfaces
 130       to perform general tasks such as performing domain name resolution (DNS lookup),
 131       establishing outgoing connections, and accepting incoming connections. Callers
 132       are responsible for interacting with networking to initialize objects to the
 133       correct state where they are usable by this library.
 134     </p>
 135 <p>
 136       In this documentation, the example code, and the implementation, the <code class="computeroutput"><span class="identifier">net</span></code> namespace is used to qualify Networking
 137       identifiers. For Boost.Beast, <code class="computeroutput"><span class="identifier">net</span></code>
 138       will be an alias for the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span></code> namespace.
 139     </p>
 140 <p>
 141       To further ease of use, this library provides an extensive collection of types
 142       and algorithms. This section of the documentation explains these types and
 143       algorithms, provides examples of usage, and also provides refreshers and tutorials
 144       for working with networking.
 145     </p>
 146 <h4>
 147 <a name="beast.using_io.h0"></a>
 148       <span class="phrase"><a name="beast.using_io.abbreviations"></a></span><a class="link" href="using_io.html#beast.using_io.abbreviations">Abbreviations</a>
 149     </h4>
 150 <p>
 151       This documentation assumes familiarity with <a href="../../../../../libs/asio/index.html" target="_top">Boost.Asio</a>,
 152       which is required to work with Beast. Sample code and identifiers used throughout
 153       are written as if the following declarations are in effect:
 154     </p>
 155 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">beast</span><span class="special">/</span><span class="identifier">core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 156 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">asio</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 157 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">asio</span><span class="special">/</span><span class="identifier">ssl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 158 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 159 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">thread</span><span class="special">&gt;</span>
 160 </pre>
 161 <pre class="programlisting"><span class="comment">//</span>
 162 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">beast</span><span class="special">;</span>
 163 <span class="keyword">namespace</span> <span class="identifier">net</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">;</span>
 164 <span class="keyword">namespace</span> <span class="identifier">ssl</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">;</span>
 165 <span class="keyword">using</span> <span class="identifier">tcp</span> <span class="special">=</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">;</span>
 166
 167 <span class="identifier">net</span><span class="special">::</span><span class="identifier">io_context</span> <span class="identifier">ioc</span><span class="special">;</span>
 168 <span class="keyword">auto</span> <span class="identifier">work</span> <span class="special">=</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">make_work_guard</span><span class="special">(</span><span class="identifier">ioc</span><span class="special">);</span>
 169 <span class="identifier">std</span><span class="special">::</span><span class="identifier">thread</span> <span class="identifier">t</span><span class="special">{[&amp;](){</span> <span class="identifier">ioc</span><span class="special">.</span><span class="identifier">run</span><span class="special">();</span> <span class="special">}};</span>
 170
 171 <span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">;</span>
 172 <span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">sock</span><span class="special">{</span><span class="identifier">ioc</span><span class="special">};</span>
 173 </pre>
 174 <p>
 175       [8_conf_macros.qbk]
 176     </p>
 177 </div>
 178 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 179 <td align="left"></td>
 180 <td align="right"><div class="copyright-footer">Copyright &#169; 2016-2019 Vinnie
 181       Falco<p>
 182         Distributed under the Boost Software License, Version 1.0. (See accompanying
 183         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 184       </p>
 185 </div></td>
 186 </tr></table>
 187 <hr>
 188 <div class="spirit-nav">
 189 <a accesskey="p" href="examples.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="using_io/asio_refresher.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 190 </div>
 191 </body>
 192 </html>