Boost.Beast vs Boost.Asio
There are lots of things which I would expect to be in Boost.Asio which are actually in Boost.Beast. Why? Most of it is "helping" code/docs. For example: - Documentation about (and public interfaces to simplify) the creation of composed operations https://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/using_io/wr... - beast::buffers_cat - beast::test::stream (to be fair, it's in experimental) But now we even have code to work around issues in Boost.Asio which ideally would simply be fixed in Boost.Asio. For example: beast::ssl_stream. I'm personally using all of the above, they are extremely useful. I just supposed it is because there is only one person working on Boost.Asio, and Christopher must be quite busy with life and getting Networking TS into the standard. I was hoping all this would go away by 2020 and I was ignoring the issue. But since now it seems Networking TS will have to wait for 2023... well, I am asking myself how to handle an increasing amount of references to Beast that in a future could change to Asio (potentially with slightly different names/semantics). So I am writing this hoping for some light on the situation.
On Mon, Dec 3, 2018 at 7:45 AM Cristian Morales Vega via Boost-users <boost-users@lists.boost.org> wrote:
There are lots of things which I would expect to be in Boost.Asio which are actually in Boost.Beast. Why?
Most of it is "helping" code/docs. For example: - Documentation about (and public interfaces to simplify) the creation of composed operations https://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/using_io/wr...
It states very clearly in the Beast documentation, that an understanding of Asio is required. Of course, this doesn't stop people who are new to Beast, new to Asio, new to Networking, new to C++, new to programming (or all of the above) from picking up the library and trying to implement something. It is true that there is a notable lack of authoritative tutorials and guides on all of the finer aspects of using Boost.Asio (and by extension, stand-alone Asio and Networking TS). I don't think it is fair to expect that the author of Asio (Christopher Kohlhoff) should be responsible for writing these things. I expect this situation to change once Networking TS is merged into the standard. By making networking a standard, it reduces the risk and increases the incentive for authors and publishers to produce these missing educational materials. As far as networking goes, I believe C++ is behind largely because of decisions made by wg21, which is the ISO group responsible for updating and producing the C++ standards. Fortunately, competition and pressure from other languages has lit the proverbial fire and networking is finally being taken seriously (although some people, like myself, think that fire could be stoked a bit).
- beast::buffers_cat
I follow Chris' design work closely and I think his "layered" approach is the right way to build up libraries. Asio provides the low level building blocks which cannot be further decomposed without losing portability. My opinion is that most C++ users should not be writing code for Asio or Networking TS. These interfaces are mainly designed for building layers on top of it, layers such as Beast. End users want to perform an HTTP GET to retrieve a file using a single line of code. They don't want to have to know about the intimate details of the protocol. Even Beast could be considered too low-level for most end-users. I wrote Beast mainly as a run up in the ladder of abstractions, so that other people could build on it. With respect to buffers_cat, yeah - it is really handy! There is no question that it has utility. Although I don't know that Asio is the place for it. There are other ways to implement buffers_cat with different tradeoffs. For example, you could use a fixed C-style array of const_buffer. This would accomplish type-erasure at the expense of a larger structure. That said, I have proposed some of Beast's buffer sequence adaptors for the standard library: <http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1145r0.html>
- beast::test::stream (to be fair, it's in experimental)
Interfaces in _experimental/ are very likely to change which is why they are specially marked. They can also have bugs or lack documentation. As these things become fully baked they will be promoted to public interfaces (moved from _experimental to one of the public interface directories).
But now we even have code to work around issues in Boost.Asio which ideally would simply be fixed in Boost.Asio. For example: beast::ssl_stream.
asio::ssl::stream implementation does not handle scatter/gather I/O. When you call write() with a buffer sequences having length greater than one, it results in a separate I/O for each element of the sequence. This kills performance, especially in Beast where the implementation makes heavy use of buffers_cat. Beast's ssl_stream class is a wrapper which intelligently flattens these sequences at the expense of allocating memory. I think there's an OpenSSL interface for handling a vector of buffers, so if it was fixed in Asio it would be better as there would be no need to allocate memory. I don't know enough to attempt a fix but maybe there is someone else who could?
I am asking myself how to handle an increasing amount of references to Beast that in a future could change to Asio (potentially with slightly different names/semantics). So I am writing this hoping for some light on the situation.
Well, you can be ready with the find and replace tool :) Regards
On Mon, 3 Dec 2018 at 16:58, Vinnie Falco via Boost-users <boost-users@lists.boost.org> wrote:
It is true that there is a notable lack of authoritative tutorials and guides on all of the finer aspects of using Boost.Asio (and by extension, stand-alone Asio and Networking TS). I don't think it is fair to expect that the author of Asio (Christopher Kohlhoff) should be responsible for writing these things.
I would not expect Christopher to be responsible for writing these things. But you have already written it, if you would offer the patch to add that documentation to Asio wouldn't Christopher take it? It's likely it would reach a wider audience if it were in Asio instead of in Beast. There must be people interested in Asio but not in HTTP/Websocket who may not have bothered to look into the Beast docs.
- beast::test::stream (to be fair, it's in experimental)
Interfaces in _experimental/ are very likely to change which is why they are specially marked. They can also have bugs or lack documentation. As these things become fully baked they will be promoted to public interfaces (moved from _experimental to one of the public interface directories).
Sure, but wouldn't make sense for it to be in Asio's experimental instead of in Beast's experimental? It would have a wider audience, which would give you more feedback.
But now we even have code to work around issues in Boost.Asio which ideally would simply be fixed in Boost.Asio. For example: beast::ssl_stream.
asio::ssl::stream implementation does not handle scatter/gather I/O. When you call write() with a buffer sequences having length greater than one, it results in a separate I/O for each element of the sequence. This kills performance, especially in Beast where the implementation makes heavy use of buffers_cat. Beast's ssl_stream class is a wrapper which intelligently flattens these sequences at the expense of allocating memory.
I think there's an OpenSSL interface for handling a vector of buffers, so if it was fixed in Asio it would be better as there would be no need to allocate memory. I don't know enough to attempt a fix but maybe there is someone else who could?
Fair enough. Better to have a workaround than nothing. But until somebody with more OpenSSL knowledge comes with a proper fix, wouldn't the workaround be better in the Asio repository? To be fair, I don't know how the different Boost libraries are developed. Maybe it's too difficult for the developer of one library to contribute to another library?
On Mon, Dec 3, 2018 at 10:25 AM Cristian Morales Vega <cristian@samknows.com> wrote:
But you have already written it, if you would offer the patch to add that documentation to Asio wouldn't Christopher take it?
Well there are a few problems there. He couldn't add it to Boost.Asio without also adding it to stand-alone Asio. My documentation is kind of boost-specific (I'm working on that though). And he would probably have written it differently (or not at all). This means that whenever I want to update it, he will have to also spend time on it. This puts an unnecessary burden on someone. Furthermore it isn't clear that Chris is the best person to be writing tutorials (or myself for that matter). Everyone is specialized differently so I think it is better for the people who have 1. the incentive, and 2. the ability to maintain the work.
Fair enough. Better to have a workaround than nothing. But until somebody with more OpenSSL knowledge comes with a proper fix, wouldn't the workaround be better in the Asio repository?
Yes this would be better if it was fixed upstream (in Asio).
To be fair, I don't know how the different Boost libraries are developed. Maybe it's too difficult for the developer of one library to contribute to another library?
Each Boost library is like its own kingdom with its own ruler. Within a library, the author is mostly free to do as they wish. It would be nice to resolve some of these issues though. Regards
-----Original Message----- From: Boost-users [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Vinnie Falco via Boost-users Sent: 03 December 2018 19:00 To: boost-users@lists.boost.org; Cristian Morales Vega Cc: Vinnie Falco Subject: Re: [Boost-users] Boost.Beast vs Boost.Asio
On Mon, Dec 3, 2018 at 10:25 AM Cristian Morales Vega <cristian@samknows.com> wrote:
But you have already written it, if you would offer the patch to add that documentation to Asio wouldn't Christopher take it?
Well there are a few problems there. He couldn't add it to Boost.Asio without also adding it to stand-alone Asio. My documentation is kind of boost-specific (I'm working on that though). And he would probably have written it differently (or not at all). This means that whenever I want to update it, he will have to also spend time on it. This puts an unnecessary burden on someone. Furthermore it isn't clear that Chris is the best person to be writing tutorials (or myself for that matter). Everyone is specialized differently so I think it is better for the people who have 1. the incentive, and 2. the ability to maintain the work.
Authors should never write their own docs ;-)
Fair enough. Better to have a workaround than nothing. But until somebody with more OpenSSL knowledge comes with a proper fix, wouldn't the workaround be better in the Asio repository?
Yes this would be better if it was fixed upstream (in Asio).
To be fair, I don't know how the different Boost libraries are developed. Maybe it's too difficult for the developer of one library to contribute to another library?
Each Boost library is like its own kingdom with its own ruler. Within a library, the author is mostly free to do as they wish. It would be nice to resolve some of these issues though.
Do 'see also' links of the form https://www.boost.org/doc/libs/release/doc/html/other_library/... help here help in resolving this? Both libraries could (should even) helpfully cross-link each other? A PR that is just a link is much more likely to be accepted than something that needs real effort? Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On Tue, Dec 4, 2018 at 2:50 AM Paul A. Bristow via Boost-users <boost-users@lists.boost.org> wrote:
Do 'see also' links of the form
https://www.boost.org/doc/libs/release/doc/html/other_library/... help here
help in resolving this?
Both libraries could (should even) helpfully cross-link each other?
Beast documentation has extensive cross-links to Boost.Asio docs, for example click on return type ("DEDUCED") of these function signatures: <https://www.boost.org/doc/libs/1_68_0/libs/beast/doc/html/beast/ref/boost__beast__http__async_read.html>
A PR that is just a link is much more likely to be accepted than something that needs real effort?
I don't know that it makes sense for asio to link back to beast. And that wouldn't be meaningful for the stand-alone version (which shares the same docs). Regards
On 12/4/18 5:47 AM, Vinnie Falco via Boost-users wrote:
On Tue, Dec 4, 2018 at 2:50 AM Paul A. Bristow via Boost-users <boost-users@lists.boost.org> wrote:
Do 'see also' links of the form
https://www.boost.org/doc/libs/release/doc/html/other_library/... help here
help in resolving this?
Both libraries could (should even) helpfully cross-link each other?
Beast documentation has extensive cross-links to Boost.Asio docs, for example click on return type ("DEDUCED") of these function signatures:
A PR that is just a link is much more likely to be accepted than something that needs real effort?
I don't know that it makes sense for asio to link back to beast. And that wouldn't be meaningful for the stand-alone version (which shares the same docs).
I think that would be mistake you'd regret for the rest of your life. Cross-linking (in both directions) would effectively make beast/asio one giant library. I know you're talking about only the docs. But if you feel you need to do it for the docs, you've likely intertwined the concepts which determine the design and scope of each library. Bad idea.
Regards
-----Original Message----- From: Boost-users [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Vinnie Falco via Boost-users Sent: 04 December 2018 13:47 To: boost-users@lists.boost.org Cc: Vinnie Falco Subject: Re: [Boost-users] Boost.Beast vs Boost.Asio
On Tue, Dec 4, 2018 at 2:50 AM Paul A. Bristow via Boost-users <boost-users@lists.boost.org> wrote:
Do 'see also' links of the form
https://www.boost.org/doc/libs/release/doc/html/other_library/... help here
help in resolving this?
Both libraries could (should even) helpfully cross-link each other?
Beast documentation has extensive cross-links to Boost.Asio docs, for example click on return type ("DEDUCED") of these function signatures:
A PR that is just a link is much more likely to be accepted than something that needs real effort?
I don't know that it makes sense for asio to link back to beast. And that wouldn't be meaningful for the stand-alone version (which shares the same docs).
It is usually best to link to https://www.boost.org/doc/libs/release/libs/beast ... rather than a Boost release version-specific link like https://www.boost.org/doc/libs/1_68_0/libs/beast/doc/html/beast/... But perhaps you knew and do that already? Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On Tue, Dec 4, 2018 at 6:25 AM Paul A. Bristow via Boost-users <boost-users@lists.boost.org> wrote:
It is usually best to link to https://www.boost.org/doc/libs/release/libs/beast ... rather than...
I link to a particular version so that the link never goes stale. Who knows, maybe some day networking will be part of the standard library and Beast will use that instead, because Boost.Asio no longer exists? Your link would be stale then, but the version 1.68 will live on in perpetuity. Regards
On 12/4/18 2:17 AM, Paul A. Bristow via Boost-users wrote:
Authors should never write their own docs ;-)
I'm aware that this suggestion is made in jest. But I think it reflects the view of many authors that documentation is a chore that can separated from the library development and design which can most expediently left for last, delegated to doxygen or just skipped entirely. I think this view totally wrong. It's a sure sign that the one's library is messed up when documenting how to use it and how it works is too difficult to do. If one is crafting the documents and the code together, difficulties in keeping the documentation working can motivate improvements in the design which make things much simpler. We've had boost submissions where the document is a mess - and generally that implies that the code is also.
Both libraries could (should even) helpfully cross-link each other?
I think that would be mistake you'd regret for the rest of your life. Cross-linking (in both directions) would effectively make beast/asio one giant library. I know you're talking about only the docs. But if you feel you need to do it for the docs, you've likely intertwined the concepts which determine the design and scope of each library. Bad idea.
A PR that is just a link is much more likely to be accepted than something that needs real effort?
Paul
--- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On 5/12/2018 03:20, Robert Ramey wrote:
I'm aware that this suggestion is made in jest. But I think it reflects the view of many authors that documentation is a chore that can separated from the library development and design which can most expediently left for last, delegated to doxygen or just skipped entirely. I think this view totally wrong. It's a sure sign that the one's library is messed up when documenting how to use it and how it works is too difficult to do. If one is crafting the documents and the code together, difficulties in keeping the documentation working can motivate improvements in the design which make things much simpler. We've had boost submissions where the document is a mess - and generally that implies that the code is also.
+1 Authors must write the first version of the docs, because they're the only ones who know the library well enough to do so. They should remain responsible for the "official" docs thereafter, but incorporate constructive feedback from others on review and trying to actually use them. Things are usually less obvious than the author assumes. :) And design and layout of the documentation is just as important (if not more important) than the design of the code itself. No matter how finely-crafted the code is, a library is useless if nobody knows how to actually use it, or their first instinct is to use it "wrong".
participants (3)
-
Cristian Morales Vega -
Gavin Lambert -
Paul A. Bristow -
Robert Ramey -
Vinnie Falco