Document in the ARM, how max-cache-size is used (from 9.16.6 and 9.17.4 and newer) to avoid server delays due to hash table resizing
Related to #1775 (closed), !3935 (merged), !3936 (merged) and Support ticket #16212
We haven't done a very good job of documenting in the ARM how this new hash table sizing thing works.
There's just this snippet in the 9.16 ARM:
8.7.3 Feature Changes • BIND’s cache database implementation has been updated to use a faster hash function with better distribution. In addition, the effective max-cache-size (configured explicitly, defaulting to a value based on system memory or set to unlimited) now pre-allocates fixed-size hash tables. This prevents interruption to query resolution when the hash table sizes need to be increased. [GL #1775 (closed)]
Meanwhile, max-cache-size is still described thus:
max-cache-size This sets the maximum amount of memory to use for the server’s cache, in bytes or percentage of total physical memory. When the amount of data in the cache reaches this limit, the server causes records to expire prematurely based on an LRU-based strategy so that the limit is not exceeded. The keyword unlimited, or the value 0, places no limit on the cache size; records are purged from the cache only when their TTLs expire. Any positive values less than 2MB are ignored and reset to 2MB. In a server with multiple views, the limit applies separately to the cache of each view. The default is 90%. On systems where detection of the amount of physical memory is not supported, values represented as a percentage fall back to unlimited. Note that the detection of physical memory is done only once at startup, so named does not adjust the cache size if the amount of physical memory is changed during runtime
Neither of these really explains how max-cache-size affects cache hash table sizing, which is:
a) Set the initial hash table size to be 4 bits (see !3935 (merged), !3936 (merged) and #2075 (closed))
b) If we have set max-cache-size, or have not specified it at all (defaults to 90% of available system memory) then compute the largest expected hash table size we should need
c) On the first time we need to increase the hash table for any RBT, and assuming we have not set 'unlimited' (max-cache-size 0), then do one single increase, from the minimum, to the biggest size we expect to need (per action b)
Please find a way to explain this clearly in the ARM.
====
We should, I think, also recommend that operators with multiple views in their configuration, set max-cache-size per view, and also (to prevent surprises), for minimal-use-views that they don't know how big a cache they will need, but that it's probably not too big, to use "max-cache-size 0;"