Date: Thu, 25 Sep 2014 21:25:40 GMT From: John Baldwin <jhb@FreeBSD.org> To: Perforce Change Reviews <perforce@FreeBSD.org> Subject: PERFORCE change 1200789 for review Message-ID: <201409252125.s8PLPeHK035722@skunkworks.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://p4web.freebsd.org/@@1200789?ac=10 Change 1200789 by jhb@jhb_jhbbsd on 2014/09/25 21:25:21 Checkpoint. Affected files ... .. //depot/projects/smpng/share/man/man9/timeout.9#13 edit Differences ... ==== //depot/projects/smpng/share/man/man9/timeout.9#13 (text+ko) ==== @@ -291,16 +291,64 @@ are silently converted to the value .Sq 1 . The -.Fa sbr , +.Fa sbt , .Fa pr , and .Fa flags arguments provide more control over the scheduled time including -support for higher resolution times and setting an absolute deadline -instead of a relative timeout. - -XXX sbt and pr - +support for higher resolution times, +specifying a 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 +.Fa sbt +and extends for the amount of time specified in +.Fa pr . +If +.Fa sbt +specifies a time in the past, +the window is adjusted to start at the current time. +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 +.Fa flags +may be specified to adjust the interpretation of +.Fa sbt +and +.Fa pr : +.Bl -tag -width ".Dv C_DIRECT_EXEC" +.It Dv C_ABSOLUTE +Handle the +.Fa sbt +argument as an absolute time since boot. +By default, +.Fa sbt +is treated as a relative amount of time similar to +.Fa ticks . +.It Dv C_DIRECT_EXEC +Run handler directly from hardware interrupt context instead of from the +softclock thread. +This reduces latency and overhead, but puts more constraints on the callout +function. +Callout functions run in this context may use only spin mutexes for locking +and should be as small as possible because they run with absolute priority. +.It Fn C_PREL +Specifies relative event time precision as binary logarithm of time interval +divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc. +Note that the larger of +.Fa pr +or this value is used as the length of the time window. +Smaller values +.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 +calls if possible. +.El .Pp The .Fn callout_reset @@ -329,59 +377,33 @@ .Fn callout_schedule functions can be used. - .Pp -The functions -.Fn callout_reset_on +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 +.Fn callout_reset_on , +.Fn callout_reset_sbt_on , and .Fn callout_schedule_on -are equivalent to -.Fn callout_reset -and -.Fn callout_schedule -but take an extra parameter specifying the target CPU for the callout. - -.Pp -The function -.Fn callout_reset_sbt_on -allows to get higher time resolution, taking relative or absolute time -and precision instead of relative ticks count. -If specified time is in past, it will be silently converted to present -to run handler as soon as possible. -.Pp -The following -.Fa flags -may be specified: -.Bl -tag -width ".Dv C_DIRECT_EXEC" -.It Dv C_ABSOLUTE -Handle the -.Fa sbt -argument as absolute time of the event since boot, or relative time otherwise. -.It Dv C_DIRECT_EXEC -Run handler directly from hardware interrupt context instead of softclock swi. -It is faster, but puts more constraints on handlers. -Handlers may use only spin mutexes for locking, and they must be fast because -they run with absolute priority. -.It Fn C_PREL -Specifies relative event time precision as binary logarithm of time interval -divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc. -Smaller value allows to aggregate more events in one timer interrupt to -reduce processing overhead and power consumption. -.It Dv C_HARDCLOCK -Align the timeouts, if possible, to -.Fn hardclock -calls. -.El -.Pp -The functions -.Fn callout_reset_curcpu +functions accept an additional argument which associates the callout with +the softclock thread for CPU +.Fa cpu . +The +.Fn callout_reset_curcpu , +.Fn callout_reset_sbt_curpu , and .Fn callout_schedule_curcpu -are wrappers for -.Fn callout_reset_on -and -.Fn callout_schedule_on -using the current CPU as the target CPU. +functions associate the callout with the softclock thread for the current CPU. +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 +.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 +respective CPUs by setting the +.Va kern.pin_pcpu_swi +loader tunable to a non-zero value. .Pp The macros .Fn callout_pending , @@ -389,10 +411,6 @@ and .Fn callout_deactivate provide access to the current state of the callout. -Careful use of these macros can avoid many of the race conditions -that are inherent in asynchronous timer facilities; see -.Sx "Avoiding Race Conditions" -below for further details. The .Fn callout_pending macro checks whether a callout is @@ -405,7 +423,8 @@ .Fn callout_pending will return .Dv FALSE -even though the callout function may not have finished (or even begun) +even though the callout function may not have finished +.Pq or even begun executing. The .Fn callout_active @@ -428,6 +447,9 @@ .Em does not clear it when a callout expires normally via the execution of the callout function. + + + .Ss "Avoiding Race Conditions" The callout subsystem invokes callout functions from its own timer context.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409252125.s8PLPeHK035722>