- Boost - lists.preview.boost.org

The standard library is better documented
by Niilo Huovila 07 Dec '23

07 Dec '23

By better I mean cppreference.com. There's a page for pretty much everything in the standard library. Related pages are linked. The preconditions and behavior of functions are specified. Consequentially I come to Boost only when the standard library doesn't do enough. If you are going to compete with the standard library instead of just supplementing it, you need outstanding documentation.

14 26

Master branch is now open for bug fixes
by Marshall Clow 06 Dec '23

06 Dec '23

The master branch is now open for bug fixes and documentation changes. Other changes by release manager permission, as described in https://github.com/boostorg/wiki/wiki/Releases%3A-Beta-Merge-Policy The next deadline: On December 6th, master closes for all changes. As always, the calendar is at https://www.boost.org/development/ — Marshall

10 23

[release] Master Branch will close for the 1.84.0 release TOMORROW
by Marshall Clow 05 Dec '23

05 Dec '23

Don’t forget your release notes, too! — Marshall

1 0

[scope] Formal review - David Sankel
by David Sankel 05 Dec '23

05 Dec '23

- What is your evaluation of the design? I'm overall happy with the design. I like the API provided and think it is useful in many scenarios. The one question I have is why unique_resource::allocated instead of a bool conversion. This is the one aspect of the API that makes me hesitate using unique_resource for things like POSIX file descriptors as .allocated() would be quite foreign for users. - What is your evaluation of the implementation? I gave the implementation only a quick glance, but it looked fine to me. - What is your evaluation of the documentation? The documentation was good. I'd suggest the front page focuses on usage examples instead of a Boost.ScopeExit comparison though. Most people reading this page won't know about ScopeExit and are trying to evaluate whether not this library will solve their problem. - What is your evaluation of the potential usefulness of the library? I think this has wide applicability. - Did you try to use the library? With what compiler? Did you have any problems? I did not attempt to use it. - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? I spent about an hour working through the documentation. - Are you knowledgeable about the problem domain? Yes And finally, every review should answer this question: - Do you think the library should be accepted as a Boost library? Be sure to say this explicitly so that your other comments don't obscure your overall opinion. Yes, I do.

1 0

Proposal for Inclusion of Async.MQTT5 Library in Boost
by Ivica Siladic 05 Dec '23

05 Dec '23

Dear Boost Developers, we are writing to introduce a new C++ Async.MQTT5 library that we believe would be a valuable addition to Boost. MQTT has become the de-facto standard for IoT communication, with billions of IoT devices relying on it to publish or retrieve data from the cloud. Despite its widespread use, integrating MQTT into a C++ embedded application remains a complex and error-prone task. This challenge primarily arises from the absence of a higher-level library that offers a straightforward interface for message publishing and receiving while abstracting MQTT protocol intricacies and effectively managing various corner cases inherent in MQTT implementation. The primary objective behind developing Async.MQTT5 was to address these challenges comprehensively, allowing developers to focus on the messages they need to send without concerns about underlying network connectivity issues. Async.MQTT5 is a C++20 client implementation of the MQTT 5.0 protocol, leveraging Boost Asio and Boost Spirit. It fully adheres to the Asio asynchronous model, providing comprehensive support for all forms of asynchronous completion tokens, per-operation cancellation, and custom allocators. The library is designed to work seamlessly with any ordered network transport, typically TCP, SSL/TLS over TCP, or WebSockets (secured and unsecured). Our goal with Async.MQTT5 is to offer developers a simple and clear C++ interface for sending and receiving messages using the MQTT 5.0 protocol. Emphasizing code readability was a key design principle of Async.MQTT5. For instance, tedious protocol message parsing/composing is implemented declaratively (partially utilizing Boost Spirit). Additionally, Asio composed operations are implemented using a novel, clear, and highly efficient "chaining functional operators" approach. It is worth noting that the library is already written following Boost style guidelines, and the documentation is crafted and formatted in line with Boost conventions. You can find the library at https://github.com/mireo/async-mqtt5, and the documentation is available at https://spacetime.mireo.com/async-mqtt5/. We highly value your opinion and would appreciate any feedback you can provide on the Async.MQTT5 library. Thank you for your time and consideration. Best regards, Ivica Siladic Bruno Iljazovic Korina Simicevic

9 15

[scope] A few questions
by Julien Blanc 05 Dec '23

05 Dec '23

Hi, I have a few questions regarding the scope library currently being reviewed: * scope_exit is not default constructible. But it can be released and is movable, so a default constructed scope_exit state makes sense (this is the same as a moved-from scope_exit). I find this a rather strange design choice. What is the rationale behind this? There's even a section on the documentation on how to circumvent this: https://lastique.github.io/scope/libs/scope/doc/html/scope/scope_guards.htm… using cleanup_func_t = std::function< void() >; // Create an inactive scope guard first, since the cleanup function is not set yet boost::scope::scope_exit< cleanup_func_t > cleanup(cleanup_func_t(), false); Why can't i just write? boost::scope::scope_exit< std::function< void() > > cleanup; * the documentation says little about memory allocation. I finally found the answer i was looking for in the boost.ScopeExit comparison: scope_xxx objects do not do any heap allocations themselves. Is that a guarantee of the library? Such a guarantee is needed in some code i work with, i need to know if it is a feature of the library that i can rely upon, and not just an optimization that could go away in a further release. * unique_fd is a resource wrapper for files. But on all major systems, closing a file can fail and return an error. It may well be that the file is not completly written correctly, and this is reported not in the write call, but in the final close call. unique_fd silently drops the return value of close. I'm not sure we should encourage this behaviour. Another issue raises when we look at the example code: void write_string(std::string const& filename, std::string const& str) { // Create a unique resource for a file boost::scope::unique_resource< int, fd_deleter > file(open(filename.c_str(), O_CREAT | O_WRONLY)); if (file.get() < 0) { int err = errno; throw std::system_error(err, std::generic_category(), "Failed to open file " + filename); } // Use it to write data to the file const char* p = str.data(); std::size_t size_left = str.size(); while (size_left > 0) { ssize_t written = write(file.get(), p, size_left); if (written < 0) { int err = errno; if (err == EINTR) continue; throw std::system_error(err, std::generic_category(), "Failed to write data"); } p += written; size_left -= written; } } In case of a failure, what we got is an half-baked file, which we know nothing about. A proper write_string function should at least try to do its cleanup and delete the file in case of error. But that defeats the purpose of unique_resource... In my experience, automatically closing file handles is not error handling. But it has its use cases, maybe it would be better demonstrated by an example like: bool compare_files(std::string const& filename1, std::string const& filename2) { boost::scope::unique_resource< int, fd_deleter > file1(open(filename.c_str(), O_CREAT | O_WRONLY)); if (file1.get() < 0) { int err = errno; throw std::system_error(err, std::generic_category(), "Failed to open file " + filename1); } boost::scope::unique_resource< int, fd_deleter > file2(open(filename.c_str(), O_CREAT | O_WRONLY)); if (file2.get() < 0) { int err = errno; throw std::system_error(err, std::generic_category(), "Failed to open file " + filename2); } // do the comparison } Regards, Julien

2 7

[scope] Mr. Docs rendered reference
by Krystian Stasiowski 05 Dec '23

05 Dec '23

Hi everyone, My name is Krystian, and I'm a Staff Engineer at The C++ Alliance. I’ve been working on Mr. Docs, a clang based C++ documentation generator intended to serve as an alternative to Doxygen. Although Mr. Docs is not yet ready for release, I noticed that there was an issue with rendering the exception specification of destructors due to a bug in Boostbook. Thus, I would like to present Mr. Docs as a potential future alternative, and have generated a multi-page reference for Boost.Scope to demonstrate its capabilities: https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scop… The output was created using the built-in Asciidoc generator and converted to HTML with asciidoctor. Since the Asciidoc generator uses handlebars templates to format the output, customizing the rendered documentation is a matter of modifying the templates. Unlike Doxygen, Mr. Docs operates directly on the clang AST. This means that support for new/obscure language features is only limited by the extent of clang’s conformance to the latest C++ standard. Any feedback is greatly appreciated. 🙂 Best, Krystian Stasiowski

5 6

Re: [boost] The standard library is better documented
by Niilo Huovila 05 Dec '23

05 Dec '23

On 12/5/23 1:43 AM, boost-request(a)lists.boost.org wrote: > Date: Mon, 4 Dec 2023 12:36:27 > -0800 From: Marshall Clow <mclow.lists(a)gmail.com> To: > boost(a)lists.boost.org Subject: Re: [boost] The standard library is > better documented Message-ID: > <B135B251-3578-40CA-A9D8-34E165EE6C14(a)gmail.com> Content-Type: > text/plain; charset=utf-8 On Dec 4, 2023, at 12:21 PM, Mateusz Loskot > via Boost <boost(a)lists.boost.org> wrote: >> On Mon, 4 Dec 2023 at 21:05, Niilo Huovila via Boost >> <boost(a)lists.boost.org <mailto:boost@lists.boost.org>> wrote: >>> On 12/4/23 4:36 PM, Hans Dembinski wrote: >>>>> On 2. Dec 2023, at 16:57, Ren? Ferdinand Rivera Morell via Boost<boost(a)lists.boost.org> wrote: >>>>> >>>>> It would be useful if you could point to instances of Boost libraries >>>>> that could use better documentation. >>>> Can we organise a user poll that ranks all Boost libraries on how well documented they are? >>>> >>>> Might be a fun way to approach this and it provides an opportunity to create some publicity for Boost when we advertise this. I can see the news headline: "Boost devs finally respond to user cries for better docs" >>> The secret of cppreference seems to be that it is a wiki. How about >>> that? Users could put their energy to improving the docs instead of >>> complaining. :) >> Users can already do that by submitting pull requests on GitHub. > Or, if they don?t grok Quickbook, they can open a GitHub issue and suggest better wording. They seem relatively heavy-handed ways to add a link or correct spelling. > Date: Tue, 5 Dec 2023 00:12:17 +0300 > From: Andrey Semashev<andrey.semashev(a)gmail.com> > To:boost@lists.boost.org > Subject: Re: [boost] The standard library is better documented > Message-ID:<9e217656-9b05-4e82-a5a3-67c55d949b4f(a)gmail.com> > Content-Type: text/plain; charset=UTF-8 > > On 12/4/23 20:53, Niilo Huovila via Boost wrote: >> On 12/4/23 4:36 PM, Hans Dembinski wrote: >>>> On 2. Dec 2023, at 16:57, Ren? Ferdinand Rivera Morell via Boost >>>> <boost(a)lists.boost.org> wrote: >>>> >>>> It would be useful if you could point to instances of Boost libraries >>>> that could use better documentation. >>> Can we organise a user poll that ranks all Boost libraries on how well >>> documented they are? >>> >>> Might be a fun way to approach this and it provides an opportunity to >>> create some publicity for Boost when we advertise this. I can see the >>> news headline: "Boost devs finally respond to user cries for better docs" >> The secret of cppreference seems to be that it is a wiki. How about >> that? Users could put their energy to improving the docs instead of >> complaining. :) > Wiki is prone to vandalism and edit wars. > > Also, aside from stylistic and wording edits, the documentation is > supposed to be written by people who are very knowledgeable in the > subject. Those people are likely very few, often maintainers only. > > Wiki is good for "public knowledge" kind of documentation. The official > library documentation is very different from that. In fact, it is the > ground truth upon which that public knowledge is built. Would separating the reference from other documentation also separate it from those concerns? Then it could be a wiki and editing the other stuff can be restricted to maintainers.

1 0

[scope] some more thoughts
by Andrzej Krzemienski 04 Dec '23

04 Dec '23

Hi Everyone, I want to share some thoughts regarding the review of Boost.Scope. The fact that it wants to implement 1-to-1 a feature from a TS -- not from the standard -- impedes the review process. The reviewer says, "this feature is bad". The author responds, "but this is how the TS requires it to be". And now what? Should we accept a bad feature because the TS requires so? Being TS-conformant is very constraining for the author. Maybe this is not a worthy goal. Also, my observation from recent years is that putting stuff into a TS may be a polite way of saying, "we respect you, but we do not want this." Also, the goal of having an implementation for a proposed feature is to check if the interface has been battle-tested to be sound. The Boost Review process is such a test. When the feedback is, this feature is wrong, then this feedback should affect the STD proposal. But Boost shouldn't be compromised by an STD proposal that was submitted without a battle-tested implementation. The move assignment operator in scope_exit and friends. It looks like its existence is against the goal of the feature. You define a guard and then you use it. Why would you assign a different guard to it? Why do we have scope_success? An alternative to using scope success is to just put your instructions at the end of the function. Do you have multiple return statements in your function and at the same time you need the same sequence of operations to be performed at each end? This is a good motivation to restructure your function to have a single return. Multiple returns are generally OK, but needing the same sequence warrants a single return. scope_success seems like a solution that is looking for a problem. "But the TS has scope_success" -- this is not a good argument for me. In Boost Review we should be evaluating a library based on its own merit, not based on a similarity with some other design, which can have its own flaws. Mixing unique_resource with scope guards is not a good idea. The STD tends to use big aggregate headers. Boost does not. The solution from the TS should not be ported 1-to-1 to Boost. Boost.Scope offers at least three ways to do the same thing. For instance, to execute some code only upon some inconvenient condition, I can use scope_fail with my condition, or scope_exit with my condition, or I can add set_active on top of either. I consider this to be a bad design. Source code is not only for the flexibility of writing, but also for the ease of reading and learning. Having multiple ways to do the same thing impedes the understanding of the code. While I understand the existence of the triplet `scope_exit`, `scope_fail` and `scope_success` (D uses an analogous triplet), it takes a while to understand the difference between scope_exit and scope_final. And the choice of name doesn't help there. The Standard library chose to use term guard (std::lock_guard) to indicate something small and cheap. Maybe use this name instead. Not perfect either, but at least consistent with what we have in STD. Also, my experience is that one uses scope guards only in rare situations where you need to satisfy complex guarantees, like maintaining the same size of two vectors. And in those situations one is already very cautious, and tries to structure the code for the minimum surprises. One does not use multiple returns or complex control flows. The justification I heard for so many features in Boost.Scope is that there may be complex situations that require it. I think that in these situations restructuring the code is better than adding more features to Boost.Scope. This looks like a lot of harsh words, but I find a subset of the library very useful: * the unconditional execution of the function * the execution based on manual deactivation (active being the initial state) * execution based on the uncaught exception count, with the caveat that it sometimes doesn't work, and it is not cheap. Regards, &rzej;

2 5

[scope] unique_resource vs unique_ptr
by Bruno Martínez 04 Dec '23

04 Dec '23

Hi, unique_ptr can emulate unique_resource: template<auto nullvalue, auto delete_> class unique { using T = decltype(nullvalue); struct generic_delete { class pointer { T t; public: pointer(T t) : t(t) {} pointer(std::nullptr_t = nullptr) : t(nullvalue) { } explicit operator bool() { return t != nullvalue; } friend bool operator ==(pointer lhs, pointer rhs) { return lhs.t == rhs.t; } friend bool operator !=(pointer lhs, pointer rhs) { return lhs.t != rhs.t; } operator T() { return t; } }; void operator()(T p) { delete_(p); } }; public: using type = std::unique_ptr<struct not_used, generic_delete>; }; int main() { using unique_fd = unique<-1, close>::type; static_assert(sizeof(unique_fd) == sizeof(int), "bloated unique_fd"); unique_fd fd1(open("fd.txt", O_WRONLY | O_CREAT | O_TRUNC)); write(fd1.get(), "hello\n", 6); } The std papers say While std::unique_ptr can be tweaked by using a custom deleter type to almost a perfect handler for resources, it is awkward to use for handle types that are not pointers. But what's the awkwardness? Kind regards, Bruno

3 2