PERFORCE change 1200927 for review

[John Baldwin]

http://p4web.freebsd.org/@@1200927?ac=10

Change 1200927 by jhb at jhb_ralph on 2014/09/29 17:40:42

	Various fixes.
	
	Submitted by:	wblock (mostly)

Affected files ...

.. //depot/projects/smpng/share/man/man9/timeout.9#15 edit

Differences ...

==== //depot/projects/smpng/share/man/man9/timeout.9#15 (text+ko) ====

@@ -171,18 +171,17 @@
 .Fa rm ,
 or
 .Fa rw
-parameter, respectively.
+parameter.
 The callout subsystem acquires the associated lock before calling the
 callout function.
 The subsystem then checks if the pending callout was cancelled
 while it waited for the associated lock.
-If it was,
+If the callout was cancelled,
 the callout function is not called and the associated lock is released.
-If it was not,
+If the callout was not cancelled,
 the callout function is called and the associated lock is released by the
 subsystem after the callout function returns.
-In addition,
-the callout must only be cancelled or rescheduled while holding the
+The callout must only be cancelled or rescheduled while holding the
 associated lock.
 This guarantees that stopping or rescheduling a callout associated with a
 lock will not race with the callout function itself.
@@ -205,7 +204,7 @@
 cannot be used with callouts because sleeping is not permitted in
 the callout subsystem.
 .Pp
-The following
+These
 .Fa flags
 may be specified for
 .Fn callout_init_mtx ,
@@ -298,7 +297,7 @@
 .Fa flags
 arguments provide more control over the scheduled time including
 support for higher resolution times,
-specifying a precision of the scheduled time,
+specifying the precision of the scheduled time,
 and setting an absolute deadline instead of a relative timeout.
 The callout is scheduled to execute in a time window which begins at
 the time specified in
@@ -312,9 +311,9 @@
 A non-zero value for
 .Fa pr
 allows the callout subsystem to coalesce callouts scheduled close to each
-other into fewer timer interrupts reducing processing overhead and power
-consumption.
-The following
+other into fewer timer interrupts,
+reducing processing overhead and power consumption.
+These
 .Fa flags
 may be specified to adjust the interpretation of
 .Fa sbt
@@ -346,17 +345,17 @@
 .Pq which result in larger time intervals
 allow the callout subsystem to aggregate more events in one timer interrupt.
 .It Dv C_HARDCLOCK
-Align the timeouts to 
-.Fn hardclock  
+Align the timeouts to
+.Fn hardclock
 calls if possible.
 .El
 .Pp
 The
 .Fn callout_reset
-functions specify the function to be called when the time expires via the
+functions accept a
 .Fa func
-argument.
-It should be a pointer to a function that takes a
+argument which identifies the function to be called when the time expires.
+It must be a pointer to a function that takes a single
 .Fa void *
 argument.
 Upon invocation,
@@ -381,27 +380,34 @@
 .Fn callout_schedule
 functions can be used.
 .Pp
-Normally callouts are scheduled to execute on the softclock thread they
-were associated with previously.
-Callouts that have not been scheduled are associated with the softclock
-thread for CPU 0.
+The callout subsystem provides a softclock thread for each CPU in the system.
+Callouts are assigned to a single CPU and are executed by the softclock thread
+for that CPU.
+Initially,
+callouts are assigned to CPU 0.
 The
 .Fn callout_reset_on ,
 .Fn callout_reset_sbt_on ,
 and
 .Fn callout_schedule_on
-functions accept an additional argument which associates the callout with
-the softclock thread for CPU
+functions assign the callout to CPU
 .Fa cpu .
 The
 .Fn callout_reset_curcpu ,
 .Fn callout_reset_sbt_curpu ,
 and
 .Fn callout_schedule_curcpu
-functions associate the callout with the softclock thread for the current CPU.
+functions assign the callout to the current CPU.
+The
+.Fn callout_reset ,
+.Fn callout_reset_sbt ,
+and
+.Fn callout_schedule
+functions schedule the callout to execute in the softclock thread of the CPU
+it is currently assigned to.
 .Pp
 The softclock threads are not pinned to their respective CPUs by default.
-The softclock thread for CPU 0 can be pinned to CPU by setting the
+The softclock thread for CPU 0 can be pinned to CPU 0 by setting the
 .Va kern.pin_default_swi
 loader tunable to a non-zero value.
 The softclock threads for CPUs other than zero can be pinned to their
@@ -454,7 +460,8 @@
 .Ss "Avoiding Race Conditions"
 The callout subsystem invokes callout functions from its own thread
 context.
-Without some kind of synchronization it is possible that a callout
+Without some kind of synchronization,
+it is possible that a callout
 function will be invoked concurrently with an attempt to stop or reset
 the callout by another thread.
 In particular, since callout functions typically acquire a lock as
@@ -463,8 +470,8 @@
 tries to reset or stop the callout.
 .Pp
 One of the following approaches can be used to address these
-synchronization concerns, though the first approach is preferred when
-possible as it is the simplest:
+synchronization concerns.
+The first approach is preferred as it is the simplest:
 .Bl -enum -offset indent
 .It
 Callouts can be associated with a specific lock when they are initialized
@@ -476,9 +483,10 @@
 When a callout is associated with a lock,
 the callout subsystem acquires the lock before the callout function is
 invoked.
-This allows the callout subsystem to handle races between callout cancellation,
+This allows the callout subsystem to transparently handle races between
+callout cancellation,
 scheduling,
-and execution transparently.
+and execution.
 Note that the associated lock must be acquired before calling
 .Fn callout_stop
 or one of the
@@ -497,15 +505,18 @@
 If
 .Va Giant
 is held when cancelling or rescheduling the callout,
-then it's use will prevent races with the callout function.
+then its use will prevent races with the callout function.
 .It
 The return value from
 .Fn callout_stop
-and the
+.Po
+or the
 .Fn callout_reset
 and
 .Fn callout_schedule
-function families indicate whether or not the callout was removed.
+function families
+.Pc
+indicates whether or not the callout was removed.
 If it is known that the callout was set and the callout function has
 not yet executed, then a return value of
 .Dv FALSE