From owner-p4-projects@FreeBSD.ORG Mon Sep 29 17:41:40 2014 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id C9065D33; Mon, 29 Sep 2014 17:41:40 +0000 (UTC) Delivered-To: perforce@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 6F976D31 for ; Mon, 29 Sep 2014 17:41:40 +0000 (UTC) Received: from skunkworks.freebsd.org (skunkworks.freebsd.org [IPv6:2001:1900:2254:2068::682:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 5B8B3C3E for ; Mon, 29 Sep 2014 17:41:40 +0000 (UTC) Received: from skunkworks.freebsd.org ([127.0.1.74]) by skunkworks.freebsd.org (8.14.9/8.14.9) with ESMTP id s8THfe9T087437 for ; Mon, 29 Sep 2014 17:41:40 GMT (envelope-from jhb@freebsd.org) Received: (from perforce@localhost) by skunkworks.freebsd.org (8.14.9/8.14.9/Submit) id s8THfeXP087434 for perforce@freebsd.org; Mon, 29 Sep 2014 17:41:40 GMT (envelope-from jhb@freebsd.org) Date: Mon, 29 Sep 2014 17:41:40 GMT Message-Id: <201409291741.s8THfeXP087434@skunkworks.freebsd.org> X-Authentication-Warning: skunkworks.freebsd.org: perforce set sender to jhb@freebsd.org using -f From: John Baldwin Subject: PERFORCE change 1200927 for review To: Perforce Change Reviews Precedence: bulk X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.18-1 List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 29 Sep 2014 17:41:41 -0000 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