brian@surge.insomnia.org wrote:
> This seems to me to be a commitment to allocate based on power of two. 
> Sure, the current implementation does this (going so far as getting into

Ah, but this is not a variable implementation choice, given the
interface. That you get back a hashmask that you can & with any
arbitrary hash to get a valid index is part of the defined interface,
and /that/ commits the implementation to choosing a power of two;
an interface change would be required to change it. The question left
unanswered is /which/ power of two, well worth answering not only
because it's important (and anything that would make a factor of two
difference in the size of a kernel structure is probably worth thinking
about) but also because it's changed a couple of times and differs among
bsds.

> 2: While on one hand, I don't like the mention of LIST and TAILQ, they 
> have to be mentioned. It would be nice to mention that there may be more 
> htypes added in the future, so one should not assume those are the only 
> legal htypes (although they are in the current implementation, of course).

I'm not sure I've often seen documentation go out of the way to say
that a set of choices could conceivably expand in future, as long as
it hasn't gone out of the way to say it can't.  I don't know of any
plans or requests to add any more queue.3 types--there's a type I
would use if it were even in queue.3, but that's another story--and
a programmer using the interface now needs to know what it supports
now. If it supports other htypes a year from now, the documentation
a year from now should say that.

> 3: The documentation does not mention any limits on sizes of the chains. 
> This should be added, since it would be nice if the contract explicitly 
> forbidded hashsize * esize being > the value a u_long can store. I 

Hmm, maybe I need to somehow clarify that the interface doesn't
constrain the size of the chains. When you look at esize you're looking
at the size of a chain /head/, which is fixed and beyond your control
(except that you get to choose whether it's a LIST head or a TAILQ head,
which have sizes of one or two pointers, respectively). The array only
contains the heads; you allocate and manage the stuff on the chains,
and nothing but available memory constrains you in that.  Allocating the
array would be a problem if you really want MAXULONG/sizeof(two pointers)
slots, but I'm not sure if the likelihood of that warrants the verbiage
that would be needed to explain it.  If it's a real concern, maybe the
code should just check for overflow, and the page could say something
generic like "will panic or return NULL (depending on mflags) if an implementation limit is exceeded."

-Chap