diff --git a/CHANGELOG.md b/CHANGELOG.md index b1c1c366..d7af4362 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ Version 129: * Add autobahn test report to doc +* Documentation tidying -------------------------------------------------------------------------------- diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk index cd1bbb1c..0a75f935 100644 --- a/doc/qbk/00_main.qbk +++ b/doc/qbk/00_main.qbk @@ -26,7 +26,7 @@ [template indexterm1[term1] ''''''[term1]''''''] [template indexterm2[term1 term2] ''''''[term1]''''''[term2]''''''] -[template repo_file[path] ''''''[path]''''''] +[template source_file[path] ''''''[path]''''''] [template include_file[path][^<''''''[path]''''''>]] [def __N3747__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [*N3747]]] @@ -34,14 +34,19 @@ [def __rfc6455__ [@https://tools.ietf.org/html/rfc6455 rfc6455]] [def __rfc7230__ [@https://tools.ietf.org/html/rfc7230 rfc7230]] -[def __Asio__ [@boost:/doc/html/boost_asio.html Boost.Asio]] +[def __Asio__ [@boost:/libs/asio/index.html Boost.Asio]] [def __async_initfn__ [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html initiating function]] +[def __get_associated_allocator__ [@boost:/doc/html/boost_asio/reference/get_associated_allocator.html `get_associated_allocator`]] +[def __get_associated_executor__ [@boost:/doc/html/boost_asio/reference/get_associated_executor.html `get_associated_executor`]] + [def __asio_handler_invoke__ [@boost:/doc/html/boost_asio/reference/asio_handler_invoke.html `asio_handler_invoke`]] [def __asio_handler_allocate__ [@boost:/doc/html/boost_asio/reference/asio_handler_allocate.html `asio_handler_allocate`]] [def __io_context__ [@boost:/doc/html/boost_asio/reference/io_context.html `boost::asio::io_context`]] [def __executor_work_guard__ [@boost:/doc/html/boost_asio/reference/executor_work_guard.html `boost::asio::executor_work_guard`]] +[def __post__ [@boost:/doc/html/boost_asio/reference/post.html `boost::asio::post`]] [def __socket__ [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `boost::asio::ip::tcp::socket`]] +[def __ssl_context__ [@boost:/doc/html/boost_asio/reference/ssl__context.html `boost::asio::ssl::context`]] [def __ssl_stream__ [@boost:/doc/html/boost_asio/reference/ssl__stream.html `boost::asio::ssl::stream`]] [def __streambuf__ [@boost:/doc/html/boost_asio/reference/streambuf.html `boost::asio::streambuf`]] [def __use_future__ [@boost:/doc/html/boost_asio/reference/use_future_t.html `boost::asio::use_future`]] @@ -73,6 +78,7 @@ [def __basic_fields__ [link beast.ref.boost__beast__http__basic_fields `basic_fields`]] [def __basic_multi_buffer__ [link beast.ref.boost__beast__basic_multi_buffer `basic_multi_buffer`]] [def __basic_parser__ [link beast.ref.boost__beast__http__basic_parser `basic_parser`]] +[def __bind_handler__ [link beast.ref.boost__beast__bind_handler `bind_handler`]] [def __buffer_body__ [link beast.ref.boost__beast__http__buffer_body `buffer_body`]] [def __fields__ [link beast.ref.boost__beast__http__fields `fields`]] [def __flat_buffer__ [link beast.ref.boost__beast__flat_buffer `flat_buffer`]] diff --git a/doc/qbk/01_intro.qbk b/doc/qbk/01_intro.qbk index e9c01c80..7f292159 100644 --- a/doc/qbk/01_intro.qbk +++ b/doc/qbk/01_intro.qbk @@ -27,8 +27,9 @@ This library is designed for: * [*Basis for Further Abstraction.] Components are well-suited for building upon. -Beast is not an HTTP client or HTTP server, but it can be used to build -those things. +This library is not a client or server, but it can be used to build those +things. Many examples are provided, including clients and servers, which may +be used as a starting point for writing your own program. [heading Motivation] @@ -60,11 +61,11 @@ Supported compilers: msvc-14+, gcc 4.8+, clang 3.6+ Sources are [*header-only]. To link a program using Beast successfully, add the -[@http://www.boost.org/libs/system/doc/reference.html Boost.System] +[@boost:/libs/system/index.html Boost.System] library to your build scripts. If you use coroutines you'll also need the -[@http://www.boost.org/libs/coroutine/doc/html/index.html Boost.Coroutine] +[@boost:/libs/coroutine/index.html Boost.Coroutine] library. Please visit the -[@http://www.boost.org/doc/ Boost documentation] +[@boost:/more/getting_started.html Boost documentation] for instructions on how to do this for your particular build system. [heading Credits] @@ -102,7 +103,9 @@ for tirelessly answering questions on [section WebSocket] -The Autobahn|Testsuite provides a fully automated test suite to +The +[@https://github.com/crossbario/autobahn-testsuite Autobahn WebSockets Testsuite] +provides a fully automated test suite to verify client and server implementations of The WebSocket Protocol for specification conformance and implementation robustness. The test suite will check an implementation by doing basic @@ -114,16 +117,14 @@ contains over 500 test cases. [@https://vinniefalco.github.io/boost/beast/reports/autobahn/index.html Autobahn|Testsuite WebSocket Results] [warning - Version 0.7.6 of - [@https://github.com/crossbario/autobahn-testsuite Autobahn WebSockets Testsuite] - contains a + Version 0.7.6 of Autobahn|Testsuite contains a [@https://github.com/crossbario/autobahn-testsuite/issues/77 known defect] - which causes false positives for the following test cases: + which causes false positive failures in Beast for the following test cases: { 12.4.5, 12.4.6, 12.4.8, 12.4.9, 12.4.10, 12.4.11, 12.4.13, 12.4.14, 12.4.15, 12.4.16, 12.4.17, 12.4.18 } + When this issue is resolved in the test suite, the reports will be updated. ] - [endsect] [endsect] diff --git a/doc/qbk/02_examples.qbk b/doc/qbk/02_examples.qbk index dc7cf518..b1a0b53c 100644 --- a/doc/qbk/02_examples.qbk +++ b/doc/qbk/02_examples.qbk @@ -12,13 +12,13 @@ These complete programs are intended to quickly impress upon readers the flavor of the library. Source code and build scripts for them are -located in the example/ directory. +located in the [source_file example] directory. [section HTTP Client] Use HTTP to make a GET request to a website and print the response: -File: [repo_file example/http/client/sync/http_client_sync.cpp] +File: [source_file example/http/client/sync/http_client_sync.cpp] [example_http_client] @@ -28,7 +28,7 @@ File: [repo_file example/http/client/sync/http_client_sync.cpp] Establish a WebSocket connection, send a message and receive the reply: -File: [repo_file example/websocket/client/sync/websocket_client_sync.cpp] +File: [source_file example/websocket/client/sync/websocket_client_sync.cpp] [example_websocket_client] @@ -42,7 +42,7 @@ File: [repo_file example/websocket/client/sync/websocket_client_sync.cpp] [block''''''] Source code and build scripts for these programs are located -in the [repo_file example] directory. +in the [source_file example] directory. @@ -203,7 +203,7 @@ listed here along with a description of their use: [table [[Source File] [Description]] [ - [[repo_file example/common/detect_ssl.hpp]] + [[source_file example/common/detect_ssl.hpp]] [ This contains the detect SSL algorithm including the synchronous and asynchronous initiating functions, described @@ -211,7 +211,7 @@ listed here along with a description of their use: support both plain and SSL sessions on the same port. ] ][ - [[repo_file example/common/root_certificates.hpp]] + [[source_file example/common/root_certificates.hpp]] [ This contains the root SSL certificates used in the SSL client examples. These certificates are used to verify the signatures @@ -221,7 +221,7 @@ listed here along with a description of their use: possible server. ] ][ - [[repo_file example/common/server_certificate.hpp]] + [[source_file example/common/server_certificate.hpp]] [ This file contains a self-signed SSL certificate used by the SSL server examples. It has not been validated by a Certificate @@ -229,10 +229,10 @@ listed here along with a description of their use: a browser may generate security warnings. ] ][ - [[repo_file example/common/ssl_stream.hpp]] + [[source_file example/common/ssl_stream.hpp]] [ - The `ssl_stream` is a replacement for `boost::asio::ssl::stream` - which supports construction from a moved-froms ocket and is also + The `ssl_stream` is a replacement for __ssl_stream__ which + supports construction from a moved-froms ocket and is also itself move constructible. ] ]] @@ -247,7 +247,7 @@ Here are all of the example functions and classes presented throughout the documentation, they can be included and used in your program without modification -* [repo_file example/doc/http_examples.hpp] +* [source_file example/doc/http_examples.hpp] [endsect] @@ -261,7 +261,7 @@ operation implementation. This is a complete, runnable version of the example described in [link beast.using_io.writing_composed_operations.echo Writing Composed Operations: Echo]. -* [repo_file example/echo-op/echo_op.cpp] +* [source_file example/echo-op/echo_op.cpp] [endsect] diff --git a/doc/qbk/03_core/5_composed.qbk b/doc/qbk/03_core/5_composed.qbk index 8780a67e..ca645dbe 100644 --- a/doc/qbk/03_core/5_composed.qbk +++ b/doc/qbk/03_core/5_composed.qbk @@ -45,9 +45,8 @@ composed operations: invoked with no arguments invokes the original completion handler with a list of bound arguments. The invocation is made from the same implicit or explicit strand as that which would be used to invoke the original - handler. This is accomplished by using the correct overload of - `asio_handler_invoke` associated with the original completion handler. - + handler. This works because the returned call wrapper uses the same + associated executor and associated allocator as the bound handler. ]] [[ [link beast.ref.boost__beast__handler_ptr `handler_ptr`] @@ -115,54 +114,15 @@ this echo operation: This is the most important element of writing a composed operation, and the part which is often neglected or implemented incorrectly. It is the -declaration and definition of the "handler hooks". There are four hooks: - -[table Handler Hooks -[[Name][Description]] -[[ - [@boost:/doc/html/boost_asio/reference/asio_handler_invoke.html `asio_handler_invoke`] -][ - Default invoke function for handlers. This hooking function ensures - that the invoked method used for the final handler is accessible at - each intermediate step. -]] -[[ - [@boost:/doc/html/boost_asio/reference/asio_handler_allocate.html `asio_handler_allocate`] -][ - Default allocation function for handlers. Implement `asio_handler_allocate` - and `asio_handler_deallocate` for your own handlers to provide custom - allocation for temporary objects. -]] -[[ - [@boost:/doc/html/boost_asio/reference/asio_handler_deallocate.html `asio_handler_deallocate`] -][ - Default deallocation function for handlers. Implement `asio_handler_allocate` - and `asio_handler_deallocate` for your own handlers to provide custom - allocation for temporary objects. -]] -[[ - [@boost:/doc/html/boost_asio/reference/asio_handler_is_continuation.html `asio_handler_is_continuation`] -][ - Default continuation function for handlers. Implement - `asio_handler_is_continuation` for your own handlers to indicate when - a handler represents a continuation. -]] -] +forwarding of the final handler's associated allocator and associated +executor to the composed operation. Our composed operation stores the final handler and performs its own intermediate asynchronous operations. To ensure that I/O objects, in this -case the stream, are accessed safely it is important to use the same method -to invoke intermediate handlers as that used to invoke the final handler. -Similarly, for the memory allocation hooks our composed operation should use -the same hooks as those used by the final handler. And finally for the -`asio_is_continuation` hook, we want to return `true` for any intermediate -asynchronous operations we perform after the first one, since those represent -continuations. For the first asynchronous operation we perform, the hook should -return `true` only if the final handler also represents a continuation. Our -implementation of the hooks will forward the call to the corresponding -overloads of the final handler: - -[example_core_echo_op_6] +case the stream, are accessed safely it is important to use the same +executor to invoke intermediate handlers as that used to invoke the final +handler. Similarly, for memory allocations our composed operation should +use the allocator associated with the final handler. There are some common mistakes that should be avoided when writing composed operations: @@ -180,20 +140,17 @@ composed operations: composed operation. This will cause undefined behavior. For example, if someone calls the initiating function with a strand-wrapped function object, and there is more than thread running on the - `io_context`, the underlying stream may be accessed in a fashion + __io_context__, the underlying stream may be accessed in a fashion that violates safety guarantees. * For operations which complete immediately (i.e. without calling an - intermediate initiating function), forgetting to use - [@boost:/doc/html/boost_asio/reference/post.html `boost::asio::post`] - to invoke the final handler. This breaks the following initiating + intermediate initiating function), forgetting to use __post__ to + invoke the final handler. This breaks the following initiating function guarantee: ['Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed - in a manner equivalent to using `boost::asio::post`]. - The function - [link beast.ref.boost__beast__bind_handler `bind_handler`] - is provided for this purpose. + in a manner equivalent to using __post__]. The function + __bind_handler__ is provided for this purpose. A complete, runnable version of this example may be found in the examples directory. diff --git a/doc/qbk/04_http/02_message.qbk b/doc/qbk/04_http/02_message.qbk index c9644389..ecefd366 100644 --- a/doc/qbk/04_http/02_message.qbk +++ b/doc/qbk/04_http/02_message.qbk @@ -57,8 +57,8 @@ inspection of fields. As per __rfc7230__, a non-case-sensitive comparison is used for field names. User defined types for fields are possible. The `Body` type determines the type of the container used to represent the body as well as the algorithms for transferring buffers to and from the -the container. The library comes with a collection of common body types. -As with fields, user defined body types are possible. +container. The library comes with a collection of common body types. As +with fields, user defined body types are possible. Sometimes it is desired to only work with a header. Beast provides a single class template __header__ and some aliases to model HTTP/1 and HTTP/2 headers: diff --git a/doc/qbk/04_http/04_serializer_streams.qbk b/doc/qbk/04_http/04_serializer_streams.qbk index 38fbdb7d..020b1bbb 100644 --- a/doc/qbk/04_http/04_serializer_streams.qbk +++ b/doc/qbk/04_http/04_serializer_streams.qbk @@ -14,15 +14,13 @@ at once, such as: * Send the header first, and the body later. -* Set chunk extensions or trailers using a chunk decorator. - * Send a message incrementally: bounded work in each I/O cycle. * Use a series of caller-provided buffers to represent the body. These tasks may be performed by using the serializer stream interfaces. -To use these interfaces, first construct a suitable object with -the message to be sent: +To use these interfaces, first construct an appropriate serializer +from the message to be sent: [table Serializer [[Name][Description]] diff --git a/doc/qbk/04_http/06_serializer_buffers.qbk b/doc/qbk/04_http/06_serializer_buffers.qbk index 4ffe2a45..3074b9d6 100644 --- a/doc/qbk/04_http/06_serializer_buffers.qbk +++ b/doc/qbk/04_http/06_serializer_buffers.qbk @@ -16,8 +16,8 @@ algorithms on objects whose interface does not conform to __Stream__. For example, a [@https://github.com/libuv/libuv *libuv* socket]. The serializer interface is interactive; the caller invokes it repeatedly -to produce buffers until all of the buffers have been generated. Then the -serializer is destroyed. +to produce buffers until all of the serialized octets have been generated. +Then the serializer is destroyed. To obtain the serialized next buffer sequence, call [link beast.ref.boost__beast__http__serializer.next `serializer::next`]. diff --git a/doc/qbk/04_http/09_custom_body.qbk b/doc/qbk/04_http/09_custom_body.qbk index 8995fe40..3fa9f5f1 100644 --- a/doc/qbk/04_http/09_custom_body.qbk +++ b/doc/qbk/04_http/09_custom_body.qbk @@ -70,10 +70,10 @@ the body type as it appears in the message. This can be any type. For example, a body's value type may specify `std::vector` or even `std::list`. A custom body may even set the value type to something that is not a container for body octets, such as a -[@http://www.boost.org/libs/filesystem/doc/reference.html#class-path `boost::filesystem::path`]. +[@boost:/libs/filesystem/doc/reference.html#class-path `boost::filesystem::path`]. Or, a more structured container may be chosen. This declares a body's value type as a JSON tree structure produced from a -[@boost:/doc/html/property_tree/parsers.html#property_tree.parsers.json_parser `json_parser`]: +[@boost:/doc/html/property_tree/parsers.html#property_tree.parsers.json_parser `boost::property_tree::json_parser`]: ``` #include #include diff --git a/doc/qbk/04_http/10_custom_parsers.qbk b/doc/qbk/04_http/10_custom_parsers.qbk index 085392a8..0dba4da5 100644 --- a/doc/qbk/04_http/10_custom_parsers.qbk +++ b/doc/qbk/04_http/10_custom_parsers.qbk @@ -11,13 +11,14 @@ While the parsers included in the library will handle a broad number of use-cases, the __basic_parser__ interface can be subclassed to implement -custom parsing strategies: the basic parser processes the incoming octets -into elements according to the HTTP/1 protocol specification, while the -derived class decides what to do with those elements. In particular, users -who create exotic containers for [*Fields] may need to also create their -own parser. Custom parsers will work with all of the stream read operations -that work on parsers, as those algorithms use only the basic parser -interface. Some use cases for implementing custom parsers are: +custom strategies for storing parsed results: the basic parser processes +the incoming octets into elements according to the HTTP/1 protocol +specification, while the derived class decides what to do with those +elements. In particular, users who create exotic containers for [*Fields] +may need to also create their own parser. Custom parsers will work with +all of the stream read operations that work on parsers, as those algorithms +use only the basic parser interface. Some use cases for implementing custom +parsers are: * Inspect incoming header fields and keep or discard them. @@ -25,8 +26,8 @@ interface. Some use cases for implementing custom parsers are: * Store header data in a user-defined __Fields__ type. -The basic parser uses the Curiously Recurring Template Pattern -([@https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern CRTP]). +The basic parser uses the +[@https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern Curiously Recurring Template Pattern]. To declare your user defined parser, derive it from __basic_parser__. The interface to the parser is event-driven. Member functions of the derived class (termed "callbacks" in this context) are invoked with parsed elements diff --git a/doc/qbk/06_websocket/1_streams.qbk b/doc/qbk/06_websocket/1_streams.qbk index be43e1a3..3bb62e1c 100644 --- a/doc/qbk/06_websocket/1_streams.qbk +++ b/doc/qbk/06_websocket/1_streams.qbk @@ -26,9 +26,10 @@ socket's constructor: [heading Using SSL] -To use WebSockets over SSL, use an instance of the `boost::asio::ssl::stream` -class template as the template type for the stream. The required `io_context` -and `ssl::context` arguments are forwarded to the wrapped stream's constructor: +To use WebSockets over SSL, use an instance of the __ssl_stream__ +class template as the template type for the stream. The required +__io_context__ and __ssl_context__ arguments are forwarded to the +wrapped stream's constructor: [wss_snippet_1] [wss_snippet_2] diff --git a/doc/qbk/06_websocket/2_connect.qbk b/doc/qbk/06_websocket/2_connect.qbk index 26050d81..cc7e8301 100644 --- a/doc/qbk/06_websocket/2_connect.qbk +++ b/doc/qbk/06_websocket/2_connect.qbk @@ -28,7 +28,8 @@ the TCP/IP socket: [wss_snippet_3] [note - Examples use synchronous interfaces for clarity of exposition. + Examples use synchronous interfaces for clarity of exposition; + signatures for asynchronous operations are also provided. ] [endsect] diff --git a/doc/qbk/06_websocket/5_messages.qbk b/doc/qbk/06_websocket/5_messages.qbk index 7cb64718..37d42c43 100644 --- a/doc/qbk/06_websocket/5_messages.qbk +++ b/doc/qbk/06_websocket/5_messages.qbk @@ -9,8 +9,8 @@ [section Send and Receive Messages] -Interfaces for transacting messages are structured into a couple of -layers. The highest layer provides ease of use, while lower layers provide +Interfaces for transacting messages are structured into layers. The +highest layer provides ease of use, while lower layers provide additional control and flexibility. The layers are arranged thusly: [table @@ -75,7 +75,7 @@ message ahead of time: * Sending a message that does not fit in memory at once. * Providing incremental results as they become available. -For these cases, the frame oriented interface may be used. This +For these cases, the partial data oriented interface may be used. This example reads and echoes a complete message using this interface: [ws_snippet_16] diff --git a/doc/qbk/06_websocket/8_notes.qbk b/doc/qbk/06_websocket/8_notes.qbk index 8cd210a9..413b5ca8 100644 --- a/doc/qbk/06_websocket/8_notes.qbk +++ b/doc/qbk/06_websocket/8_notes.qbk @@ -65,9 +65,9 @@ However, this code is well-formed: [ws_snippet_25] -The implementation uses composed asynchronous operations internally; -although some individiual operations can perform both reads and writes, -this behavior is coordinated internally to make sure the underlying stream +The implementation uses composed asynchronous operations; although +some individiual operations can perform both reads and writes, this +behavior is coordinated internally to make sure the underlying stream is operated in a safe fashion. This allows an asynchronous read operation to respond to a received ping frame even while a user-initiated call to asynchronous write is active. diff --git a/doc/qbk/07_concepts/Body.qbk b/doc/qbk/07_concepts/Body.qbk index dcfcf475..927425fd 100644 --- a/doc/qbk/07_concepts/Body.qbk +++ b/doc/qbk/07_concepts/Body.qbk @@ -24,8 +24,8 @@ the algorithms used during parsing and serialization. In this table: * `B` is a type meeting the requirements of [*Body]. -* `m` is a value of type `message` where `b` is a `bool` value - and `F` is a type meeting the requirements of [*Fields]. +* `m` is a value of type `message` where `b` is a `bool` value + and `F` is a type meeting the requirements of __Fields__. [table Valid expressions [[Expression] [Type] [Semantics, Pre/Post-conditions]] @@ -66,8 +66,8 @@ In this table: [`std::uint64_t`] [ This static member function is optional. It returns the payload - size of `body` not including any chunked transfer encoding. The - function shall not exit via an exception. + size of `body` in bytes not including any chunked transfer encoding. + The function shall not exit via an exception. When this function is present: diff --git a/doc/qbk/07_concepts/BodyReader.qbk b/doc/qbk/07_concepts/BodyReader.qbk index 0acbfa30..d63fc2c5 100644 --- a/doc/qbk/07_concepts/BodyReader.qbk +++ b/doc/qbk/07_concepts/BodyReader.qbk @@ -9,7 +9,9 @@ [section:BodyReader BodyReader] -A [*BodyReader] provides an online algorithm to obtain a sequence of zero +A [*BodyReader] provides an +[@https://en.wikipedia.org/wiki/Online_algorithm online algorithm] +to obtain a sequence of zero or more buffers from a body during serialization. The implementation creates an instance of this type when needed, and calls into it one or more times to retrieve buffers holding body octets. The interface of [*BodyReader] is diff --git a/doc/qbk/08_design.qbk b/doc/qbk/08_design.qbk index 3ccf057f..04704181 100644 --- a/doc/qbk/08_design.qbk +++ b/doc/qbk/08_design.qbk @@ -52,6 +52,20 @@ start. Other design goals: * Allow for customizations, if the user needs it. +The following video presentation was delivered at +[@https://cppcon.org/ CppCon] +in 2016. It provides a light introduction to some of the earliest +interfaces of Beast (which have since changed). + +[block''' + + + + + +'''] + [include 08_design/1_http_message.qbk] [include 08_design/2_http_comparison.qbk] [include 08_design/3_websocket_zaphoyd.qbk] diff --git a/doc/qbk/08_design/1_http_message.qbk b/doc/qbk/08_design/1_http_message.qbk index 2485d0de..06bab360 100644 --- a/doc/qbk/08_design/1_http_message.qbk +++ b/doc/qbk/08_design/1_http_message.qbk @@ -5,10 +5,28 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Official repository: https://github.com/boostorg/beast + + ] [section HTTP Message Container] +The following video presentation was delivered at +[@https://cppcon.org/ CppCon] +in 2017. The presentation provides a simplified explanation of the design +process for the HTTP message container used in Beast. The slides and code +used are available in the +[@https://github.com/vinniefalco/CppCon2017 GitHub repository]. + +[block''' + + + + + +'''] + In this section we describe the problem of modeling HTTP messages and explain how the library arrived at its solution, with a discussion of the benefits and drawbacks of the design choices. The goal for creating a message model diff --git a/example/echo-op/echo_op.cpp b/example/echo-op/echo_op.cpp index b7c7a16c..10c21b05 100644 --- a/example/echo-op/echo_op.cpp +++ b/example/echo-op/echo_op.cpp @@ -145,7 +145,7 @@ public: // Associated allocator support. This is Asio's system for // allowing the final completion handler to customize the // memory allocation strategy used for composed operation - // states. A composed operation needs to use the same allocator + // states. A composed operation should use the same allocator // as the final handler. These declarations achieve that. using allocator_type = @@ -172,11 +172,6 @@ public: p_.handler(), p_->stream.get_executor()); } - // (DEPRECATED) - template - friend bool asio_handler_is_continuation( - echo_op* op); - // The entry point for this handler. This will get called // as our intermediate operations complete. Definition below. // @@ -237,33 +232,6 @@ operator()(boost::beast::error_code ec, std::size_t bytes_transferred) //] -//[example_core_echo_op_6 - -// Determines if the next asynchronous operation represents a -// continuation of the asynchronous flow of control associated -// with the final handler. If we are past step one, it means -// we have performed an asynchronous operation therefore any -// subsequent operation would represent a continuation. -// Otherwise, we propagate the handler's associated value of -// is_continuation. Getting this right means the implementation -// may schedule the invokation of the invoked functions more -// efficiently. -// -template -bool asio_handler_is_continuation(echo_op* op) -{ - // This next call is structured to permit argument - // dependent lookup to take effect. - using boost::asio::asio_handler_is_continuation; - - // Always use std::addressof to pass the pointer to the handler, - // otherwise an unwanted overload of operator& may be called instead. - return op->p_->step > 1 || - asio_handler_is_continuation(std::addressof(op->p_.handler())); -} - -//] - //[example_core_echo_op_3 template diff --git a/include/boost/beast/http/impl/message.ipp b/include/boost/beast/http/impl/message.ipp index e3972fee..d325b621 100644 --- a/include/boost/beast/http/impl/message.ipp +++ b/include/boost/beast/http/impl/message.ipp @@ -403,7 +403,7 @@ prepare_payload(std::false_type) this->result() == status::not_modified)) { if(! n || *n > 0) - // The response body MUST BE empty for this case + // The response body MUST be empty for this case BOOST_THROW_EXCEPTION(std::invalid_argument{ "invalid response body"}); }