RFC: additions to the Glossary

[George Keramidas]

On 2004-06-08 03:07, Mark Linimon <linimon at lonesome.com> wrote:
> This patch adds definitions for Giant, LOR, NDISulator, OBE, pointyhat,
> and Project Evil, and expands the entry for BSD.
>
> Unless anyone objects, I would like to go ahead and commit these changes.

I think they're great :-)

: +      <glossterm>Giant</glossterm>
: +      <glossdef>
: +       <para>The name of a kernel resource lock that protects a large
: +         set of kernel resources.  It is an unwanted remnant of much
: +         earlier <acronym>BSD</acronym> kernels which used very coarse
: +         locking mechanisms (for instance, if any process was in the
: +         network stack, every other process was locked out).  While
: +         this was adequate in the days where a machine might have only
: +         a few dozen processes, one networking card, and certainly only
: +         one processor, in current times it is an unacceptable
: +         performance bottleneck.  &os; developers are actively working
: +         on replacing every occurrence with fine-grained locks that
: +         protect individual resources.</para>

Cool, this is probably a much needed entry, since a lot of people are
going to ask what "Giant" is, once they see it referenced in a commit
log or an old, archived mail message.  I don't like to sound like I'm
knit picking too much, but perhaps "every occurence with..." could be
"every use of Giant with..."?

An explanation of what "coarse" and "fine-grained" locking is, is
probably going to be useful too.

: +      <glossterm>Lock Order Reversal</glossterm>
: +      <acronym>LOR</acronym>
: +      <glossdef>
: +       <para>The &os; kernel uses a number of resource locks to
: +         arbitrate contention for those resources.  A run-time
: +         lock diagnostic system found in &os.current; kernels
: +         (but removed for releases), called &man.witness.4;,
: +         detects the potential for deadlocks due to locking errors.
: +         (&man.witness.4; is actually slightly conservative, so
: +         it is possible to get false positives.)  A true positive
: +         report indicates "if you were unlucky, a deadlock would
: +         have happened here".</para>

''...indicates "that" if you were unlucky...'' sounds a bit better.

: +      <glossterm>Overtaken By Events</glossterm>
: +      <acronym>OBE</acronym>
: +      <glossdef>
: +       <para>Indicates a suggested change (such as a Problem Report
: +         or a feature request) which is no longer relevant or
: +         applicable due to passage of time or more recent changes
: +         to &os;.</para>

When time simply passes a problem is not very likely to just go away.
More often than not, the user that reported it loses interest or changes
his/her tools to avoid hitting the problem again.  I don't think that
mentioning the "passage of time" is a good idea here and it does sound a
bit funny as a phrase.

- Giorgos