libs/beast/doc/qbk/02_examples/_examples.qbk

   1 [/
   2     Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
   3
   4     Distributed under the Boost Software License, Version 1.0. (See accompanying
   5     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6
   7     Official repository: https://github.com/boostorg/beast
   8 ]
   9
  10 [section Examples]
  11 [block'''<?dbhtml stop-chunking?>''']
  12
  13 Source code and build scripts for these programs are located
  14 in the [path_link example example] directory.
  15
  16 [/-----------------------------------------------------------------------------]
  17
  18 [section Clients]
  19
  20 These HTTP clients submit a GET request to a server specified on the command
  21 line, and prints the resulting response. The crawl client asynchronously
  22 fetches the document root of the 10,000 top ranked domains, this may be
  23 used to evaluate robustness. All asynchronous clients support timeouts.
  24
  25 [table
  26 [[Description] [Source File] [Source File (using SSL)]]
  27 [
  28         [HTTP, synchronous]
  29         [[path_link example/http/client/sync/http_client_sync.cpp http_client_sync.cpp]]
  30         [[path_link example/http/client/sync-ssl/http_client_sync_ssl.cpp http_client_sync_ssl.cpp]]
  31 ][
  32         [HTTP, asynchronous]
  33         [[path_link example/http/client/async/http_client_async.cpp http_client_async.cpp]]
  34         [[path_link example/http/client/async-ssl/http_client_async_ssl.cpp http_client_async_ssl.cpp]]
  35 ][
  36         [HTTP, asynchronous using __system_executor__]
  37         []
  38         [[path_link example/http/client/async-ssl-system-executor/http_client_async_ssl_system_executor.cpp http_client_async_ssl_system_executor.cpp]]
  39 ][
  40         [HTTP, coroutine]
  41         [[path_link example/http/client/coro/http_client_coro.cpp http_client_coro.cpp]]
  42         [[path_link example/http/client/coro-ssl/http_client_coro_ssl.cpp http_client_coro_ssl.cpp]]
  43 ][
  44         [HTTP crawl (asynchronous)]
  45         [[path_link example/http/client/crawl/http_crawl.cpp http_crawl.cpp]]
  46         []
  47 ]]
  48
  49 These WebSocket clients connect to a
  50 server and send a message, then receive a message and print the response
  51 before disconnecting. All asynchronous clients support timeouts.
  52
  53 [table
  54 [[Description] [Source File] [Source File (using SSL)]]
  55 [
  56         [WebSocket, synchronous]
  57         [[path_link example/websocket/client/sync/websocket_client_sync.cpp websocket_client_sync.cpp]]
  58         [[path_link example/websocket/client/sync-ssl/websocket_client_sync_ssl.cpp websocket_client_sync_ssl.cpp]]
  59 ][
  60         [WebSocket, asynchronous]
  61         [[path_link example/websocket/client/async/websocket_client_async.cpp websocket_client_async.cpp]]
  62         [[path_link example/websocket/client/async-ssl/websocket_client_async_ssl.cpp websocket_client_async_ssl.cpp]]
  63 ][
  64         [WebSocket, asynchronous using __system_executor__]
  65         []
  66         [[path_link example/websocket/client/async-ssl-system-executor/websocket_client_async_ssl_system_executor.cpp websocket_client_async_ssl_system_executor.cpp]]
  67 ][
  68         [WebSocket, coroutine]
  69         [[path_link example/websocket/client/coro/websocket_client_coro.cpp websocket_client_coro.cpp]]
  70         [[path_link example/websocket/client/coro-ssl/websocket_client_coro_ssl.cpp websocket_client_coro_ssl.cpp]]
  71 ]]
  72
  73 [endsect]
  74
  75 [/-----------------------------------------------------------------------------]
  76
  77 [section Servers]
  78
  79 These HTTP servers deliver files from a root directory specified on the
  80 command line. All asynchronous servers support timeouts.
  81
  82 [table
  83 [[Description] [Source File] [Source File (using SSL)]]
  84 [
  85         [HTTP, synchronous]
  86         [[path_link example/http/server/sync/http_server_sync.cpp http_server_sync.cpp]]
  87         [[path_link example/http/server/sync-ssl/http_server_sync_ssl.cpp http_server_sync_ssl.cpp]]
  88 ][
  89         [HTTP, asynchronous]
  90         [[path_link example/http/server/async/http_server_async.cpp http_server_async.cpp]]
  91         [[path_link example/http/server/async-ssl/http_server_async_ssl.cpp http_server_async_ssl.cpp]]
  92 ][
  93         [HTTP, coroutine]
  94         [[path_link example/http/server/coro/http_server_coro.cpp http_server_coro.cpp]]
  95         [[path_link example/http/server/coro-ssl/http_server_coro_ssl.cpp http_server_coro_ssl.cpp]]
  96 ][
  97         [HTTP, stackless coroutine]
  98         [[path_link example/http/server/stackless/http_server_stackless.cpp http_server_stackless.cpp]]
  99         [[path_link example/http/server/stackless-ssl/http_server_stackless_ssl.cpp http_server_stackless_ssl.cpp]]
 100 ][
 101         [HTTP, fast (optimized for speed)]
 102         [[path_link example/http/server/fast/http_server_fast.cpp http_server_fast.cpp]]
 103         []
 104 ][
 105         [HTTP, small (optimized for space)]
 106         [[path_link example/http/server/small/http_server_small.cpp http_server_small.cpp]]
 107         []
 108 ][
 109         [HTTP, flex (plain + SSL)]
 110         []
 111         [[path_link example/http/server/flex/http_server_flex.cpp http_server_flex.cpp]]
 112 ]]
 113
 114 These WebSocket servers echo back any message received, keeping the
 115 session open until the client disconnects. All asynchronous servers
 116 support timeouts.
 117
 118 [table
 119 [[Description] [Source File] [Source File (using SSL)]]
 120 [
 121         [WebSocket, synchronous]
 122         [[path_link example/websocket/server/sync/websocket_server_sync.cpp websocket_server_sync.cpp]]
 123         [[path_link example/websocket/server/sync-ssl/websocket_server_sync_ssl.cpp websocket_server_sync_ssl.cpp]]
 124 ][
 125         [WebSocket, asynchronous]
 126         [[path_link example/websocket/server/async/websocket_server_async.cpp websocket_server_async.cpp]]
 127         [[path_link example/websocket/server/async-ssl/websocket_server_async_ssl.cpp websocket_server_async_ssl.cpp]]
 128 ][
 129         [WebSocket, coroutine]
 130         [[path_link example/websocket/server/coro/websocket_server_coro.cpp websocket_server_coro.cpp]]
 131         [[path_link example/websocket/server/coro-ssl/websocket_server_coro_ssl.cpp websocket_server_coro_ssl.cpp]]
 132 ][
 133         [WebSocket, stackless coroutine]
 134         [[path_link example/websocket/server/stackless/websocket_server_stackless.cpp websocket_server_stackless.cpp]]
 135         [[path_link example/websocket/server/stackless-ssl/websocket_server_stackless_ssl.cpp websocket_server_stackless_ssl.cpp]]
 136 ][
 137         [WebSocket, fast (suited for benchmarks)]
 138         [[path_link example/websocket/server/fast/websocket_server_fast.cpp websocket_server_fast.cpp]]
 139         []
 140 ]]
 141
 142 [endsect]
 143
 144 [/-----------------------------------------------------------------------------]
 145
 146 [section Servers (Advanced)]
 147
 148 These servers offer both HTTP and WebSocket services on the same port,
 149 and illustrate the implementation of advanced features.
 150
 151 [table
 152 [[Description] [Features] [Sources]]
 153 [
 154         [Advanced]
 155         [[itemized_list
 156             [Timeouts]
 157             [Multi-threaded]
 158             [HTTP pipelining]
 159             [Parser-oriented HTTP reading]
 160             [Dual protocols: HTTP and WebSocket]
 161             [Clean exit via SIGINT (CTRL+C) or SIGTERM (kill)]
 162         ]]
 163         [[path_link example/advanced/server/advanced_server.cpp advanced_server.cpp]]
 164 ][
 165         [Advanced, flex (plain + SSL)]
 166         [[itemized_list
 167             [Timeouts]
 168             [Multi-threaded]
 169             [HTTP pipelining]
 170             [Parser-oriented HTTP reading]
 171             [Dual protocols: HTTP and WebSocket]
 172             [Flexible ports: plain and SSL on the same port]
 173             [Clean exit via SIGINT (CTRL+C) or SIGTERM (kill)]
 174         ]]
 175         [[path_link example/advanced/server-flex/advanced_server_flex.cpp advanced_server_flex.cpp]]
 176 ][
 177         [Chat Server, multi-threaded]
 178         [[itemized_list
 179             [Multi-threaded]
 180             [Broadcasting Messages]
 181             [Multi-user Chat Server]
 182             [JavaScript Browser Client]
 183             [Parser-oriented HTTP reading]
 184             [Dual protocols: HTTP and WebSocket]
 185             [Clean exit via SIGINT (CTRL+C) or SIGTERM (kill)]
 186         ]]
 187         [[path_link example/websocket/server/chat-multi chat-multi]]
 188 ]]
 189
 190 [endsect]
 191
 192 [/-----------------------------------------------------------------------------]
 193
 194 [section:chat_server Chat Server __video__]
 195
 196 This example demonstrates a websocket chat server, allowing multiple
 197 users to connect and participate in live, group messaging. It comes
 198 with a tiny front end implemented in JavaScript and HTML5 which runs
 199 in any browser. The example is accompanied by a one hour presentation
 200 which provides a discussion of networking concepts, followed by in-depth
 201 explanation of how the client and server are constructed. This talk
 202 was delivered at [@https://cppcon.org CppCon 2018]. The source code
 203 in the Beast example contains improvements to the original program.
 204
 205 [table Chat WebSocket Server and JavaScript Client
 206 [[Component] [Features] [Sources]]
 207 [
 208   [Server]
 209   [[itemized_list
 210       [C++]
 211       [Timeouts]
 212       [Multi-threaded]
 213       [Broadcast to multiple peers]
 214       [Dual protocols: HTTP and WebSocket]
 215       [Clean exit via SIGINT (CTRL+C) or SIGTERM (kill)]
 216   ]]
 217   [[path_link example/websocket/server/chat-multi chat-multi]]
 218 ][
 219   [Client]
 220   [[itemized_list
 221       [JavaScript / HTML5]
 222       [Runs in the browser]
 223       [Delivered by the server]
 224       [Only 60 lines total including UI]
 225       [Completely portable graphics]
 226   ]]
 227   [[path_link example/websocket/server/chat-multi/chat_client.html chat_client.html]]
 228 ]]
 229
 230 [/ "Get rich quick! Using Boost.Beast WebSockets and Networking TS"]
 231 '''
 232 <mediaobject>
 233   <videoobject>
 234     <videodata fileref="https://www.youtube.com/embed/7FQwAjELMek"
 235         align="center" contentwidth="560" contentdepth="315"/>
 236   </videoobject>
 237 </mediaobject>
 238 '''
 239
 240 [endsect]
 241
 242 [/-----------------------------------------------------------------------------]
 243
 244 [endsect]