Boost.Beast vs Boost.Asio

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

Boost.Beast vs Boost.Asio

Boost - Users mailing list
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/writing_composed_operations.html
- 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.
_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
On Mon, Dec 3, 2018 at 7:45 AM Cristian Morales Vega via Boost-users
<[hidden email]> 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/writing_composed_operations.html

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
_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
On Mon, 3 Dec 2018 at 16:58, Vinnie Falco via Boost-users
<[hidden email]> 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?
_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
On Mon, Dec 3, 2018 at 10:25 AM Cristian Morales Vega
<[hidden email]> 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
_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
> -----Original Message-----
> From: Boost-users [mailto:[hidden email]] On Behalf Of Vinnie Falco via Boost-users
> Sent: 03 December 2018 19:00
> To: [hidden email]; 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
> <[hidden email]> 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





_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
On Tue, Dec 4, 2018 at 2:50 AM Paul A. Bristow via Boost-users
<[hidden email]> 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
_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
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
> <[hidden email]> 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).

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
>


_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
In reply to this post by Boost - Users mailing list
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
>


_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
In reply to this post by Boost - Users mailing list


> -----Original Message-----
> From: Boost-users [mailto:[hidden email]] On Behalf Of Vinnie Falco via Boost-users
> Sent: 04 December 2018 13:47
> To: [hidden email]
> 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
> <[hidden email]> 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).

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




_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
On Tue, Dec 4, 2018 at 6:25 AM Paul A. Bristow via Boost-users
<[hidden email]> 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
_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users
Reply | Threaded
Open this post in threaded view
|

Re: Boost.Beast vs Boost.Asio

Boost - Users mailing list
In reply to this post by Boost - Users mailing list
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".
_______________________________________________
Boost-users mailing list
[hidden email]
https://lists.boost.org/mailman/listinfo.cgi/boost-users