svn commit: r252346 - head/share/man/man9

[John Baldwin]

On Friday, June 28, 2013 1:08:36 pm Benjamin Kaduk wrote:
> > +.Ss Spin Mutexes
> > +Spin mutexes are a variation of basic mutexes; the main difference between
> > +the two is that spin mutexes never block.
> > +Instead, they spin while waiting for the lock to be released.
> > +Note that a thread that holds a spin mutex must never yield its CPU to
> > +avoid deadlock.
> >
> 
> I think this needs a comma after "CPU" (or reordering to emphasize the
> deadlock avoidance part).

Hmm, perhaps:

To avoid deadlock, a thread that holds a spin mutex must never yield its CPU.

?
  
> I think "complicated both to use and to implement" flows better; in the
> present text, "both" is something of an interruption.

Yes, "both to" does flow better.

> > +Unlike condition variables,
> > +arbitrary addresses may be used as wait channels and an dedicated
> >
> 
> s/an /a /

Agreed.
  
> > +.Ss Bounded vs. Unbounded Sleep
> > +A bounded sleep
> > +.Pq or blocking
> >
> 
> The Pq should probably go before "sleep"?

I think not.  The root sentence is "A bounded sleep is a sleep where..."

If you move the parent you get:

"A bounded is a sleep where..."

However, the "sleep is a sleep" bit is awkward.  Perhaps:

"In a bounded sleep (or blocking), the only resource needed..."

and then

"In an unbounded sleep (often referred to as simply "sleeping"), a thread
waits for an external event..."

 
> > +is a sleep where the only resource needed to resume execution of a thread
> > +is CPU time for the owner of a lock that the thread is waiting to acquire.
> > +An unbounded sleep
> > +.Po
> > +often referred to as simply
> > +.Dq sleeping
> > +.Pc
> > +is a sleep where a thread is waiting for an external event or for a
> > condition
> > +to become true.
> > +In particular,
> > +since there is always CPU time available,
> > +a dependency chain of threads in bounded sleeps should always make forward
> > +progress.
> >
> 
> This sentence is a little bit misleading, as the key fact that the threads
> in question are in bounded sleeps is buried in the last clause.  On first
> reading, one might think that we are still talking about unbounded sleeps,
> so having CPU time always available is quite the non sequitur.  I would
> reorder things so that "since there is always CPU time available" is last.

Agreed.

> Let me know if I should just send a patch off to my mentor for approval.

I can review it.

-- 
John Baldwin