Previously, calling `clear()` on `Map`, `Set` or `VectorSet` would remove all
elements but did not free the already allocated capacity. This is fine in most
cases, but has very bad and non-obvious worst-case behavior as can be seen in
#131793. The issue is that having a huge hash table with only very few elements
is inefficient when having to iterate over it (e.g. when clearing).
There used to be a `clear_and_shrink()` method to avoid this worst-case
behavior. However, it's not obvious that this should be used to improve
performance.
This patch changes the behavior of `clear` to what `clear_and_shrink` did before
to avoid accidentally running in worst-case behavior. The old behavior is still
available with the name `clear_and_keep_capacity`. This is more efficient if
it's known that the hash-table is filled with approximately the same number of
elements or more again.
The main annoying aspect from an API perspective is that for `Vector`, the
default behavior of `clear` is and should stay to not free the memory. `Vector`
does not have the same worst-case behavior when there is a lot of unused
capacity (besides taking up memory), because the extra memory is never looked
at. `std::vector::clear` also does not free the memory, so that's the expected
behavior. While this patch introduces an inconsistency between `Vector` and
`Map/Set/VectorSet` with regards to freeing memory, it makes them more
consistent in that `clear` is the better default when reusing the data-structure
repeatedly.
I went over existing uses of `clear` to see if any of them should be changed to
`clear_and_keep_capacity`. None of them seemed to really benefit from that or
showed that it was impossible to get into the worst-case scenario. Therefore,
this patch slightly changes the behavior of these calls (only performance wise,
semantics are exactly the same).
Pull Request: https://projects.blender.org/blender/blender/pulls/131852
0e28920bd8