1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Notes</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 1. Boost.Beast"> 8<link rel="up" href="../using_websocket.html" title="WebSocket"> 9<link rel="prev" href="teardown.html" title="Teardown"> 10<link rel="next" href="../concepts.html" title="Concepts"> 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="teardown.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.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="../concepts.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="beast.using_websocket.notes"></a><a class="link" href="notes.html" title="Notes">Notes</a> 28</h3></div></div></div> 29<p> 30 Because calls to read data may return a variable amount of bytes, the interface 31 to calls that read data require an object that meets the requirements of 32 <a class="link" href="../concepts/DynamicBuffer.html" title="DynamicBuffer"><span class="emphasis"><em>DynamicBuffer</em></span></a>. 33 This concept is modeled on <a href="../../../../../../doc/html/boost_asio/reference/streambuf.html" target="_top"><code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">streambuf</span></code></a>. 34 </p> 35<p> 36 The implementation does not perform queueing or buffering of messages. If 37 desired, these features should be provided by callers. The impact of this 38 design is that library users are in full control of the allocation strategy 39 used to store data and the back-pressure applied on the read and write side 40 of the underlying TCP/IP connection. 41 </p> 42<h5> 43<a name="beast.using_websocket.notes.h0"></a> 44 <span class="phrase"><a name="beast.using_websocket.notes.asynchronous_operations"></a></span><a class="link" href="notes.html#beast.using_websocket.notes.asynchronous_operations">Asynchronous 45 Operations</a> 46 </h5> 47<p> 48 Asynchronous versions are available for all functions: 49 </p> 50<pre class="programlisting"><span class="identifier">flat_buffer</span> <span class="identifier">buffer</span><span class="special">;</span> 51 52<span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_read</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">,</span> 53 <span class="special">[](</span><span class="identifier">error_code</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">)</span> 54 <span class="special">{</span> 55 <span class="comment">// Do something with the buffer</span> 56 <span class="special">});</span> 57</pre> 58<p> 59 Calls to asynchronous initiation functions support the extensible asynchronous 60 model developed by the Boost.Asio author, allowing for traditional completion 61 handlers, stackful or stackless coroutines, and even futures: 62 </p> 63<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">echo</span><span class="special">(</span><span class="identifier">stream</span><span class="special"><</span><span class="identifier">tcp_stream</span><span class="special">>&</span> <span class="identifier">ws</span><span class="special">,</span> 64 <span class="identifier">multi_buffer</span><span class="special">&</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">yield_context</span> <span class="identifier">yield</span><span class="special">)</span> 65<span class="special">{</span> 66 <span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_read</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">yield</span><span class="special">);</span> 67 <span class="identifier">std</span><span class="special">::</span><span class="identifier">future</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">></span> <span class="identifier">fut</span> <span class="special">=</span> 68 <span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_write</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">.</span><span class="identifier">data</span><span class="special">(),</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">use_future</span><span class="special">);</span> 69<span class="special">}</span> 70</pre> 71<p> 72 The example programs that come with the library demonstrate the usage of 73 websocket stream operations with all asynchronous varieties. 74 </p> 75<h5> 76<a name="beast.using_websocket.notes.h1"></a> 77 <span class="phrase"><a name="beast.using_websocket.notes.the_io_context"></a></span><a class="link" href="notes.html#beast.using_websocket.notes.the_io_context">The 78 io_context</a> 79 </h5> 80<p> 81 The creation and operation of the <a href="../../../../../../doc/html/boost_asio/reference/io_context.html" target="_top"><code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">io_context</span></code></a> 82 associated with the underlying stream is left to the callers, permitting 83 any implementation strategy including one that does not require threads for 84 environments where threads are unavailable. Beast WebSocket itself does not 85 use or require threads. 86 </p> 87<h5> 88<a name="beast.using_websocket.notes.h2"></a> 89 <span class="phrase"><a name="beast.using_websocket.notes.thread_safety"></a></span><a class="link" href="notes.html#beast.using_websocket.notes.thread_safety">Thread 90 Safety</a> 91 </h5> 92<p> 93 Like a regular <a href="../../../../../../libs/asio/index.html" target="_top">Boost.Asio</a> 94 socket, a <a class="link" href="../ref/boost__beast__websocket__stream.html" title="websocket::stream"><code class="computeroutput"><span class="identifier">stream</span></code></a> is not thread safe. Callers 95 are responsible for synchronizing operations on the socket using an implicit 96 or explicit strand, as per the Asio documentation. The websocket stream asynchronous 97 interface supports one of each of the following operations to be active at 98 the same time: 99 </p> 100<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 101<li class="listitem"> 102 <a class="link" href="../ref/boost__beast__websocket__stream/async_read.html" title="websocket::stream::async_read"><code class="computeroutput"><span class="identifier">async_read</span></code></a> or <a class="link" href="../ref/boost__beast__websocket__stream/async_read_some.html" title="websocket::stream::async_read_some"><code class="computeroutput"><span class="identifier">async_read_some</span></code></a> 103 </li> 104<li class="listitem"> 105 <a class="link" href="../ref/boost__beast__websocket__stream/async_write.html" title="websocket::stream::async_write"><code class="computeroutput"><span class="identifier">async_write</span></code></a> or <a class="link" href="../ref/boost__beast__websocket__stream/async_write_some.html" title="websocket::stream::async_write_some"><code class="computeroutput"><span class="identifier">async_write_some</span></code></a> 106 </li> 107<li class="listitem"> 108 <a class="link" href="../ref/boost__beast__websocket__stream/async_ping.html" title="websocket::stream::async_ping"><code class="computeroutput"><span class="identifier">async_ping</span></code></a> or <a class="link" href="../ref/boost__beast__websocket__stream/async_pong.html" title="websocket::stream::async_pong"><code class="computeroutput"><span class="identifier">async_pong</span></code></a> 109 </li> 110<li class="listitem"> 111 <a class="link" href="../ref/boost__beast__websocket__stream/async_close.html" title="websocket::stream::async_close"><code class="computeroutput"><span class="identifier">async_close</span></code></a> 112 </li> 113</ul></div> 114<p> 115 For example, the following code is produces undefined behavior, because the 116 program is attempting to perform two simultaneous reads: 117 </p> 118<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_read</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span> <span class="special">[](</span><span class="identifier">error_code</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">){});</span> 119<span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_read</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span> <span class="special">[](</span><span class="identifier">error_code</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">){});</span> 120</pre> 121<p> 122 However, this code is correct: 123 </p> 124<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_read</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span> <span class="special">[](</span><span class="identifier">error_code</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">){});</span> 125<span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_write</span><span class="special">(</span><span class="identifier">b</span><span class="special">.</span><span class="identifier">data</span><span class="special">(),</span> <span class="special">[](</span><span class="identifier">error_code</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">){});</span> 126<span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_ping</span><span class="special">({},</span> <span class="special">[](</span><span class="identifier">error_code</span><span class="special">){});</span> 127<span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_close</span><span class="special">({},</span> <span class="special">[](</span><span class="identifier">error_code</span><span class="special">){});</span> 128</pre> 129<p> 130 The implementation uses composed asynchronous operations; although some individual 131 operations can perform both reads and writes, this behavior is coordinated 132 internally to make sure the underlying stream is operated in a safe fashion. 133 This allows an asynchronous read operation to respond to a received ping 134 frame even while a user-initiated call to asynchronous write is active. 135 </p> 136</div> 137<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 138<td align="left"></td> 139<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 140 Falco<p> 141 Distributed under the Boost Software License, Version 1.0. (See accompanying 142 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>) 143 </p> 144</div></td> 145</tr></table> 146<hr> 147<div class="spirit-nav"> 148<a accesskey="p" href="teardown.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.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="../concepts.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 149</div> 150</body> 151</html> 152
