Unclear documentation about performance tuning for `*-slabs` values

[kwand]

Describe the bug The documentation regarding the performance tuning of the *-slabs values is very unclear, and to add to the confusion, there are multiple interpretations of what the docs mean exactly online.

The current version of the docs state (https://unbound.docs.nlnetlabs.nl/en/latest/topics/performance.html):

Set *-slabs to a power of 2 close to the num-threads value. Do this for msg-cache-slabs, rrset-cache-slabs, infra-cache-slabs and key-cache-slabs. This reduces lock contention.

My interpretation of this is exactly that the *-slabs should be a power of 2 (i.e. 1, 2, 4, 8, 16, etc.) and this value should be close to the num-threads value. For example:

• if num-threads is 4, then *-slabs should also be 4.
• if num-threads is 12, then *-slabs should be 8 or 16. But this is also where the confusion starts, as it's not stated which power of 2 should be preferred (if this is indeed the correct interpretation), since both 8 and 16 are equally close to 12.

To add to this confusion, there are various interpretations of what the optimal values are online:

• Two issues were opened about this over at the opnsense repo.
  • In https://github.com/opnsense/core/issues/3092, the developers changed the (automatically calculated) defaults to pow(2, floor(log(num-threads, 2)) + 1)) (i.e. 4 threads -> value of 8 for *-slabs) based on a interpretation that it should be a power of 2 higher than num-threads. As backing, they also cite this documentation: https://calomel.org/unbound_dns.html, which claims the number of slabs to use for cache and must be a power of 2 times the number of num-threads set above.
  • In a follow-up issue https://github.com/opnsense/core/issues/4308, it is claimed that this interpretation is wrong and the point of the optimal value is to "reduce lock contention and not to produce excess overhead". However, it is then claimed the correct interpretation should be ceil(log(num-threads)/log(2)) that is the *-slabs value i.e. *-slabs is interpreted to be the exponent such that when used to raise a base of 2, the value is close to num-threads. Some of the examples given are a value of 4 for *-slabs given 12 or 16 num-threads.
• In various unbound.conf posted in gists and repos, there is a mix of *-slabs value interpretations that seem to follow either *-slabs = num-threads or *-slabs = 2 * num-threads. I can't seem to find any other explicit discussion on how to interpret the official docs and calculate the optimal value aside from the two opnsense issues and their cited doc from Calomel.

So, exactly which interpretation is officially correct here? None of the above seem particularly correct to me, as they all stretch what the docs say in odd ways, especially regarding "close to".

Expected behavior

• Documentation should be made clearer, providing an explicit formula and/or sample optimal values.
• "close to" should also be defined explicitly as whether the higher or lower number should be chosen if possible values are equally close to num-threads, as well as the consequences of setting to higher or lower.

(Also, apologies if this is not considered a bug - though, given the docs appear to be hosted on this repo, I feel it is appropriate to open this up and tie any PRs to this should modifications be made)