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

El 20/04/2026 a las 23:47, Peter Turcan via Boost escribió:
> 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.

Hi Peter, thanks for your review!

> 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.

With respect to this, boost::container::hub serves pretty much the same 
use cases std::hive does, whatever these are. The selling point for the 
former is that it's generally faster.

> 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.*

I'll see to change the intro statement along the lines you suggest. As 
for O(1), this is technical parlance for "executes in constant time 
regardless of the size of the container". It's quite common terminology 
in the standard, maybe I should reassess if the average Boost user 
understands it without problem too.

> 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.
Noted. HFT stands for "high-frequency trading". Again, maybe it's an 
acronym the average reader may not get.
> 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?
Probably not: Game of Life lends itself to array-like structures for 
representation. Thinking out loud, something like a deque of deques :-)
> 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.
Good point. It's 64 because CPUs have instructions to very quickly 
identify bits set to one in a 64-bit word: BSF/TXCNT in X86, CTZ in ARM. 
128 bits would be even better performance wise, but we don't have yet 
single CPU instructions for that. I can add a short remark on this.
> 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.
Noted.
> 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.

Umm, this is not the block size (which stays constant at 64 element), 
but the size in bytes of the element itself. In general (though with 
exceptions), a larger element makes boost::container::hub more 
performant relative to plf::hive, basically because cache locality 
matters less.

> 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.)
You mean parentheses? I'm mimicking here the style of the standard, see 
for instance

https://eel.is/c++draft/container.requirements#pre-3

> 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.
I'd rather relegate examples to the code cause we have a tradition, in 
the standard as well as in most of Boost, to keep reference sections 
factual, precise, and, admittedly, somewhat dry :-) FWIW, the reference 
for this particular container is quite unsurprising as the API is the 
same, with minor variations, as that of countless other STL-like 
containers.
> Thanks for your great efforts again Joaquin - and hope my comments are
> useful!

They are! Thanks again for your review.

Joaquín M López Muñoz

_______________________________________________
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/R2X4D7ZPQ62VYFGG3XSAODLLEZFJ2WFZ/