Re: [review] The review of boost::container::hub starts! April 16 - April 26

Hi Ion, Joaquin,

Here is my review of the Container.Hub documentation, with my 2c thrown in
on the design. The documentation is certainly usable in the state that it
is in, my comments are aimed more at increasing usage of the library should
it be included in Boost.

The use for the library seems narrow - it addresses the perennial dilemma
of a computer language trying to extricate the developer from needing any
knowledge of the underlying hardware - fighting against the performance
improvements which can be gained by taking advantage of that underlying
hardware. The Standard Hive seems to lean towards the former, leaving an
opportunity for the other approach which Hub addresses. It is a tougher
sell to lead developers away from the Standard, unless necessary. Does seem
like strong use cases and example code taken from those use cases are
needed.

1. Not crazy about the first sentence (too much punctuation):
"boost::container::hub is a sequence container with O(1) insertion and
erasure and element stability: pointers/iterators to an element remain
valid as long as the element is not erased."

Better to read more fluidly (avoid pointers/iterators as it's awkward to
read smoothly) and with a more compelling argument than "O(1)" - not sure a
storage system would have a much higher complexity than O(1)? Perhaps
something like:

*Boost.Container.Hub  is a sequence container with accelerated insertion
and erasure, and solid element stability. Pointers and iterators to an
element remain valid and unchanged until the element is explicitly deleted.*

2. Good that use cases are mentioned "game entity systems, particle
simulation and HFT come to mind." I assume HFT means "high-frequency
transfers" or close. However, "come to mind" is too conversational. This is
formal documentation and use cases should be researched more deeply.

Game developers are certainly used to coding for hardware efficiency.
Agreed particle simulation (molecular modelling) is a second compelling use
case - perhaps Conway's Game of Life - Wikipedia
<https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life> would make a good
tutorial example?

3. Might be an idea to explain why "64" provides the performance - is it
word size, simply 8 bytes, or other hardware feature.? I assume it is word
size, though the question does arise as to why this cannot be changed - say
to 32 or 128 or 1024?  I assume the library guarantees word alignment.

4. Good that there are code examples throughout, though I much prefer
English comments to pseudo code as comments, for example:
h.reserve(1000);                           // capacity() == 1024 (rounded
up to 64)
Better to say:                                // The capacity is rounded up
to the next 64 block size, so 1024 in this case

5. On a similar note, using pseudo code like the following - I am not even
sure what the comment is trying to say:
// won't allocate (500 <= 1024)
// ~trim_capacity(0), capacity() == 512

Better to explain in natural language.

6. In the Performance section the sample sizes (16,64,80) do seem to favor
a block size of 64, rather than an arbitrary size. The performance
improvements do seem significant.

7. Don't use brackets in text unless necessary, they are a known barrier to
readability. For example, they are unnecessary in comments such as:
(Note: Potentially faster than the sample code due to internal
optimizations.)

8. The Reference section could do with code examples, ideally including the
errors or exceptions that can be thrown, and best practices in handling
them, or perhaps links to example code in the Tutorial section of the doc
where the code constructs are used.

Thanks for your great efforts again Joaquin - and hope my comments are
useful!

I am the Technical Writer for the Cpp Alliance.

- best
Peter Turcan





On Mon, Apr 20, 2026 at 2:34 AM Ion Gaztañaga via Boost <
[email protected]> wrote:

> El 19/04/2026 a las 21:34, Christian Mazakas via Boost escribió:
> > On Wed, Apr 15, 2026 at 3:48 PM Ion Gaztañaga via Boost <
> > [email protected]> wrote:
> >
> >> Dear users and members of Boost,
> >>
> >> I'm proud to announce that the formal review of Joaquín M López Muñoz's
> >> boost::container::hub container, for inclusion in the Boost.Container
> >> library, starts today ( in my timezone ;-) ), April 16, and runs through
> >> April 26.
> >>
> >
> > I'm not sure if we've already had this discussion or not but I'd actually
> > suggest considering putting Hub either in its own library or one that's
> > unconditionally header-only.
> >
> > My concern here is that if we put Hub into Container, people looking for
> > Hub and using CMake will wind up using Boost::container which I fear
> > transitively carries a binary dependency.
>
> I was certainly not an optimal decision to make Boost.Container compiled
> for some functions. I don't think those functions are very popular, and
> maybe Boost.Container should contain in the future the code that the
> user should put in its own DLL (say, globals for PMR, allocators, etc.).
>
> In the latest CMakeLists.txt there is a BOOST_CONTAINER_HEADER_ONLY
> option to avoid the binary dependency:
>
> https://github.com/boostorg/container/blob/boost-1.90.0/CMakeLists.txt
>
>
> Best,
>
> Ion
> _______________________________________________
> Boost mailing list -- [email protected]
> To unsubscribe send an email to [email protected]
> https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
> Archived at:
> https://lists.boost.org/archives/list/[email protected]/message/5SPO2LOEUGCB7F4TQACFHNL5IWACFWI5/
>
_______________________________________________
Boost mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
Archived at: https://lists.boost.org/archives/list/[email protected]/message/OWEGWDNYIP6JUZJ3FOFC6EC4XYIAEM6R/