Date: Mon, 29 Sep 2014 17:41:40 GMT From: John Baldwin <jhb@FreeBSD.org> To: Perforce Change Reviews <perforce@FreeBSD.org> Subject: PERFORCE change 1200927 for review Message-ID: <201409291741.s8THfeXP087434@skunkworks.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://p4web.freebsd.org/@@1200927?ac=10 Change 1200927 by jhb@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409291741.s8THfeXP087434>