ceph/src/Beast/doc/overview.qbk

   1 [/
   2     Copyright (c) 2013-2017 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
   8 [section:overview Introduction]
   9
  10 Beast is a header-only, cross-platform C++ library built on Boost.Asio and
  11 parts of Boost, containing two modules implementing widely used network
  12 protocols. Beast offers a universal HTTP message model, plus algorithms for
  13 parsing and serializing HTTP/1 messages. Beast.WebSocket provides a complete
  14 implementation of the WebSocket protocol. Their design achieves these goals:
  15
  16 * [*Symmetry.] Interfaces are role-agnostic; the same interfaces can be
  17 used to build clients, servers, or both.
  18
  19 * [*Ease of Use.] HTTP messages are modeled using simple, readily
  20 accessible objects. Functions and classes used to send and receive HTTP
  21 or WebSocket messages are designed to resemble Boost.Asio as closely as
  22 possible. Users familiar with Boost.Asio will be immediately comfortable
  23 using this library.
  24
  25 * [*Flexibility.] Interfaces do not mandate specific implementation
  26 strategies; important decisions such as buffer or thread management are
  27 left to users of the library.
  28
  29 * [*Performance.] The implementation performs competitively, making it a
  30 realistic choice for building high performance network servers.
  31
  32 * [*Scalability.] Development of network applications that scale to thousands
  33 of concurrent connections is possible with the implementation.
  34
  35 * [*Basis for further abstraction.] The interfaces facilitate the
  36 development of other libraries that provide higher levels of abstraction.
  37
  38 The HTTP portion of Beast is designed to be a low-level building block for
  39 creating higher level libraries. It implements only the HTTP protocol, and
  40 does not handle domain specific features (for example: cookies, redirects, or
  41 deflate content encodings).
  42
  43 [heading Requirements]
  44
  45 Beast requires:
  46
  47 * [*C++11.] A minimum of C++11 is needed.
  48 * [*Boost.] Beast is built on Boost, especially Boost.Asio.
  49 * [*OpenSSL.] If using TLS/Secure sockets (optional).
  50
  51 [note Tested compilers: msvc-14+, gcc 5+, clang 3.6+]
  52
  53 The library is [*header-only]. It is not necessary to add any .cpp files,
  54 or to add commands to your build script for building Beast. To link your
  55 program successfully, you'll need to add the Boost.System library to link
  56 with. If you use coroutines you'll also need the Boost.Coroutine library.
  57 Please visit the Boost documentation for instructions on how to do this for
  58 your particular build system.
  59
  60 [heading Motivation]
  61
  62 Beast is built on Boost.Asio. A proposal to add networking functionality to the
  63 C++ standard library, based on Boost.Asio, is under consideration by the
  64 committee and on track for standardization. Since the final approved networking
  65 interface for the C++ standard library will likely closely resemble the current
  66 interface of Boost.Asio, the choice of Boost.Asio as the network transport
  67 layer is prudent.
  68
  69 The HTTP protocol is pervasive in network applications. As C++ is a logical
  70 choice for high performance network servers, there is great utility in solid
  71 building blocks for manipulating, sending, and receiving HTTP messages
  72 compliant with the Hypertext Transfer Protocol and the supplements that
  73 follow. Unfortunately reliable implementations or industry standards do not
  74 exist in C++. The development of higher level libraries is stymied by the
  75 lack of a common set of low-level algorithms and types for interacting with
  76 the HTTP protocol.
  77
  78 Today's web applications increasingly rely on alternatives to standard HTTP
  79 to achieve performance and/or responsiveness. While WebSocket implementations
  80 are widely available in common web development languages such as Javascript,
  81 good implementations in C++ are scarce. A survey of existing C++ WebSocket
  82 solutions reveals interfaces which lack symmetry, impose performance penalties,
  83 and needlessly restrict implementation strategies.
  84
  85 Beast.WebSocket takes advantage of Boost.Asio's extensible asynchronous
  86 model, handler allocation, and handler invocation hooks. Calls to
  87 Beast.WebSocket asynchronous initiation functions allow callers the choice
  88 of using a completion handler, stackful or stackless coroutines, futures,
  89 or user defined customizations (for example, Boost.Fiber). The
  90 implementation uses handler invocation hooks (__asio_handler_invoke__),
  91 providing execution guarantees on composed operations in a manner identical
  92 to Boost.Asio. The implementation also uses handler allocation hooks
  93 (__asio_handler_allocate__) when allocating memory internally for composed
  94 operations.
  95
  96 There is no need for inheritance or virtual members in a
  97 [link beast.ref.websocket__stream `websocket::stream`].
  98 All operations are templated and transparent to the compiler, allowing for
  99 maximum inlining and optimization.
 100
 101 [heading Credits]
 102
 103 Boost.Asio is the inspiration behind which all of the interfaces and
 104 implementation strategies are built. Some parts of the documentation are
 105 written to closely resemble the wording and presentation of Boost.Asio
 106 documentation. Credit goes to Christopher Kohlhoff for the wonderful
 107 Asio library and the ideas upon which Beast is built.
 108
 109 Beast would not be possible without the considerable time and patience
 110 contributed by David Schwartz, Edward Hennis, Howard Hinnant, Miguel Portilla,
 111 Nikolaos Bougalis, Scott Determan, Scott Schurr, and Ripple Labs for
 112 supporting its development.
 113
 114 [endsect]