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

[Benjamin Kaduk]

On Fri, Jun 28, 2013 at 12:33 PM, John Baldwin <jhb at freebsd.org> wrote:

> Author: jhb
> Date: Fri Jun 28 16:33:45 2013
> New Revision: 252346
> URL: http://svnweb.freebsd.org/changeset/base/252346
>
> Log:
>   Make a pass over this page to correct and clarify a few things as well as
>   some general word-smithing.
>

Many thanks for this!  A few nits...


> Modified: head/share/man/man9/locking.9
>
> ==============================================================================
> --- head/share/man/man9/locking.9       Fri Jun 28 16:24:14 2013
>  (r252345)
> +++ head/share/man/man9/locking.9       Fri Jun 28 16:33:45 2013
>  (r252346)
> -.Ss Spin mutexes
> -Spin mutexes are variation of basic mutexes; the main difference between
> -the two is that spin mutexes never yield the processor - instead, they
> spin,
> -waiting for the thread holding the lock,
> -(which must be running on another CPU), to release it.
> -Spin mutexes disable interrupts while the held so as to not get
> pre-empted.
> -Since disabling interrupts is expensive, they are also generally slower.
> -Spin mutexes should be used only when necessary, e.g. to protect data
> shared
> +.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).


> +Unlike ordinary mutexes, spin mutexes disable interrupts when acquired.
> +Since disabling interrupts can be expensive, they are generally slower to
> +acquire and release.
> +Spin mutexes should be used only when absolutely necessary,
> +e.g. to protect data shared
>  with interrupt filter code (see
>  .Xr bus_setup_intr 9
> -for details).
> -.Ss Pool mutexes
> -With most synchronization primitives, such as mutexes, programmer must
> -provide a piece of allocated memory to hold the primitive.
> +for details),
> +or for scheduler internals.
>
[...]

> @@ -122,21 +111,41 @@ data structure.
> +.Ss Lockmanager locks
> +Lockmanager locks are sleepable shared/exclusive locks used mostly in
> +.Xr VFS 9
> +.Po
> +as a
> +.Xr vnode 9
> +lock
> +.Pc
> +and in the buffer cache
> +.Po
> +.Xr BUF_LOCK 9
> +.Pc .
> +They have features other lock types do not have such as sleep
> +timeouts, blocking upgrades,
> +writer starvation avoidance, draining, and an interlock mutex,
> +but this makes them complicated to both use and implement;
>

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


> +for this reason, they should be avoided.
> +.Pp
> +See
> +.Xr lock 9
> +for details.
> @@ -194,7 +181,12 @@ The functions
>  .Fn wakeup ,
>  and
>  .Fn wakeup_one
> -handle event-based thread blocking.
> +also handle event-based thread blocking.
> +Unlike condition variables,
> +arbitrary addresses may be used as wait channels and an dedicated
>

s/an /a /


> +structure does not need to be allocated.
> +However, care must be taken to ensure that wait channel addresses are
> +unique to an event.
>  If a thread must wait for an external event, it is put to sleep by
>  .Fn tsleep ,
>  .Fn msleep ,
> @@ -232,122 +225,168 @@ includes the
>  .Sh INTERACTIONS
> -The primitives interact and have a number of rules regarding how
> +The primitives can interact and have a number of rules regarding how
>  they can and can not be combined.
> -Many of these rules are checked using the
> -.Xr witness 4
> -code.
> -.Ss Bounded vs. unbounded sleep
> -The following primitives perform bounded sleep:
> - mutexes, pool mutexes, reader/writer locks and read-mostly locks.
> -.Pp
> -The following primitives may perform an unbounded sleep:
> -shared/exclusive locks, counting semaphores, condition variables,
> sleep/wakeup and lockmanager locks.
> -.Pp
> +Many of these rules are checked by
> +.Xr witness 4 .
> +.Ss Bounded vs. Unbounded Sleep
> +A bounded sleep
> +.Pq or blocking
>

The Pq should probably go before "sleep"?


> +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.


> +This requires that no thread in a bounded sleep is waiting for a lock held
> +by a thread in an unbounded sleep.
> +To avoid priority inversions,
> +a thread in a bounded sleep lends its priority to the owner of the lock
> +that it is waiting for.
>

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

-Ben