From owner-freebsd-current@FreeBSD.ORG Sat Mar 17 08:13:05 2007 Return-Path: X-Original-To: freebsd-current@freebsd.org Delivered-To: freebsd-current@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 7360916A402 for ; Sat, 17 Mar 2007 08:13:05 +0000 (UTC) (envelope-from duane@dwlabs.ca) Received: from smtpout.eastlink.ca (smtpout.eastlink.ca [24.222.0.30]) by mx1.freebsd.org (Postfix) with ESMTP id 3248B13C448 for ; Sat, 17 Mar 2007 08:13:05 +0000 (UTC) (envelope-from duane@dwlabs.ca) Received: from ip02.eastlink.ca ([24.222.10.10]) by mta01.eastlink.ca (Sun Java System Messaging Server 6.2-4.03 (built Sep 22 2005)) with ESMTP id <0JF1009ILERLW1H1@mta01.eastlink.ca> for freebsd-current@freebsd.org; Sat, 17 Mar 2007 04:42:57 -0300 (ADT) Received: from blk-224-199-230.eastlink.ca (HELO dwpc.dwlabs.ca) ([24.224.199.230]) by ip02.eastlink.ca with ESMTP; Sat, 17 Mar 2007 04:42:58 -0300 Received: from dwpc.dwlabs.ca (www.dwlabs.ca [192.168.0.10]) by dwpc.dwlabs.ca (8.13.8/8.13.8) with ESMTP id l2H7cuRi059791; Sat, 17 Mar 2007 04:39:02 -0300 (ADT envelope-from duane@dwpc.dwlabs.ca) Received: (from duane@localhost) by dwpc.dwlabs.ca (8.13.8/8.13.8/Submit) id l2H7ctkj059790; Sat, 17 Mar 2007 04:38:55 -0300 (ADT envelope-from duane) Date: Sat, 17 Mar 2007 04:38:55 -0300 From: Duane Whitty In-reply-to: <45F73AE7.6010508@elischer.org> To: Julian Elischer , Duane Whitty Message-id: <20070317073855.GA58662@dwpc.dwlabs.ca> MIME-version: 1.0 Content-type: multipart/mixed; boundary="Boundary_(ID_kUUvEUDVInxTTnzno43fcA)" Content-disposition: inline X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AgAAADc5+0UY4Mfmfmdsb2JhbACBZ412Ag X-IronPort-AV: i="4.14,295,1170648000"; d="scan'208"; a="123603942:sNHT36953154" X-Virus-Scanned: ClamAV 0.88.6/2853/Fri Mar 16 15:48:54 2007 on dwpc.dwlabs.ca X-Virus-Status: Clean X-Spam-Checker-Version: SpamAssassin 3.1.4 (2006-07-25) on dwpc.dwlabs.ca References: <200703092241.l29Mf2Ds062856@repoman.freebsd.org> <200703121535.22140.jhb@freebsd.org> <20070312200345.GB5688@garage.freebsd.pl> <200703121618.41084.jhb@freebsd.org> <45F5E1F9.5090806@elischer.org> <20070313010309.Q25395@fledge.watson.org> <45F73AE7.6010508@elischer.org> User-Agent: Mutt/1.4.2.2i X-Spam-Status: No, score=-1.9 required=5.0 tests=AWL,BAYES_00, UNPARSEABLE_RELAY autolearn=ham version=3.1.4 Cc: freebsd-current@freebsd.org Subject: Re: [RFC] locking.9 X-BeenThere: freebsd-current@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Duane Whitty List-Id: Discussions about the use of FreeBSD-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 17 Mar 2007 08:13:05 -0000 --Boundary_(ID_kUUvEUDVInxTTnzno43fcA) Content-type: text/plain; charset=us-ascii Content-transfer-encoding: 7BIT Content-disposition: inline On Tuesday, 13 March 2007 at 16:59:35 -0700, Julian Elischer wrote: > resend to the right place with a corrected attachment. > > Robert Watson wrote: > > > >The idea of a locking(9) has been kicked around for a while, and its > >time has definitely come. It would summarize the properties and cross > >reference the man pages of the various primitives, and suggest a > >preference and strategy for using them in new code vs. existing code, > >etc. Distinguishing dimensions would include things like whether it is > >sleepable, supports priority propagation, can be acquired in interrupt > >context (a result of the prior two properties), whether it is fair, etc, > >etc. And include stern warnings about not using lockmgr in new code :-). > > > >Robert N M Watson > >Computer Laboratory > >University of Cambridge > > > ok so how about I commit this to get us started and the nroff and > locking experts can take it from there. > > This is great! Thank you on behalf of newcomers everywhere. It turns out the man9 page doesn't get installed. I've attached the patch for /usr/src/share/man/man9/Makefile so that this gets installed. I'm looking forward to reading this and I know I'll learn a lot. Duane Whitty > .\" > .\" Copyright (c) 1998 Berkeley Software Design, Inc. All rights reserved. > .\" > .\" Redistribution and use in source and binary forms, with or without > .\" modification, are permitted provided that the following conditions > .\" are met: > .\" 1. Redistributions of source code must retain the above copyright > .\" notice, this list of conditions and the following disclaimer. > .\" 2. Redistributions in binary form must reproduce the above copyright > .\" notice, this list of conditions and the following disclaimer in the > .\" documentation and/or other materials provided with the distribution. > .\" 3. Berkeley Software Design Inc's name may not be used to endorse or > .\" promote products derived from this software without specific prior > .\" written permission. > .\" > .\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``AS IS'' AND > .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE > .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE > .\" ARE DISCLAIMED. IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN INC BE LIABLE > .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL > .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS > .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) > .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT > .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY > .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF > .\" SUCH DAMAGE. > .\" > .\" from BSDI $Id: mutex.4,v 1.1.2.3 1998/04/27 22:53:13 ewv Exp $ > .\" $FreeBSD: src/share/man/man9/mutex.9,v 1.54 2007/03/09 22:41:01 jhb Exp $ > .\" > .Dd March 14, 2007 > .Dt LOCKING 9 > .Os > .Sh NAME > .Nm locking , > .Nd kernel synchronization primitives > .Sh SYNOPSIS > All sorts of stuff to go here. > .Pp > .Sh DESCRIPTION > The > .Em > FreeBSD > kernel is written to run across multiple CPUs and as such requires > several different sychronization primatives to allow the developers > to safely access and manipulate the many data types required. > .Pp > These include: > .Bl -enum > .It > Spin Mutexes > .It > Sleep Mutexes > .It > pool Mutexes > .It > Shared-Exclusive locks > .It > Reader-Writer locks > .It > Turnstyles > .It > Semaphores > .It > Condition variables > .It > Sleep/wakeup > .It > Giant > .It > Lockmanager locks > .El > > .Pp > The primnatives interact and have a number of rules regarding how > they can and can not be combined. Ther eare too many for the average humanmind and they > keep changing. (if you disagree, please write replacement text) :-) > .Pp > Some of these primatives may be used at the low (interrupt) level and some may not. > .Pp > There are strict ordering requirements and for some of the types this > is checked using the > .Xr witness 4 > code. > .Pp > .Ss SPIN Mutexes > Mutexes are the basic primative. > You either hold it or you don't. > If you don't own it then you just spin, waiting for teh holder (on another CPU) > to release it. Hopefully they are doing something fast. You can not do anythign that > deschedules the thread while you are holding a SPIN mutex. > .Ss Sleep Mutexes > Basically sleep (regular) mutexes will deschedule the thread if > the mutex can not be acquired. As in spin mutexes, you either get it or you don't. > You may call the > .Xr sleep 9 > call > .Fn msleep > or the new > .Fn mtx_sleep > variant. These will atomically drop the mutex and reacquire it > as part of waking up. > .Ss Pool Mutexes > A variant of SLEEP mutexes where the allocation of the mutex is handled more by the system. > .Ss Sx_locks > Shared/exclusive locks are used to protect data that are read far more often > than they are written. > Mutexes are inherently more efficient than shared/exclusive locks, so > shared/exclusive locks should be used prudently. > A thread may hold a shared or exclusive lock on an > .Em sx_lock > lock while sleeping. > As a result, an > .Em sx_lockm > lock may not be acquired while holding a mutex. > Otherwise, if one thread slept while holding an > .Em sx_lockm > lock while another thread blocked on the same > .Em sx_lockm > lock after acquiring a mutex, then the second thread would effectively > end up sleeping while holding a mutex, which is not allowed. > .Ss Rw_locks > Reader/writer locks allow shared access to protected data by multiple threads, > or exclusive access by a single thread. > The threads with shared access are known as > .Em readers > since they only read the protected data. > A thread with exclusive access is known as a > .Em writer > since it can modify protected data. > .Pp > Although reader/writer locks look very similar to > .Xr sx 9 > locks, their usage pattern is different. > Reader/writer locks can be treated as mutexes (see > .Xr mutex 9 ) > with shared/exclusive semantics. > Unlike > .Xr sx 9 , > an > .Em rw_lock > can be locked while holding a non-spin mutex, and an > .Em rw_lock > cannot be held while sleeping. > The > .Em rw_lock > locks have priority propagation like mutexes, but priority > can be propagated only to an exclusive holder. > This limitation comes from the fact that shared owners > are anonymous. > Another important property is that shared holders of > .Em rw_lock > can recurse, > but exclusive locks are not allowed to recurse. > .Ss Turnstyless > Turnstiles are used to hold a queue of threads blocked on > non-sleepable locks. Sleepable locks use condition variables to > implement their queues. Turnstiles differ from a sleep queue in that > turnstile queue's are assigned to a lock held by an owning thread. Thus, > when one thread is enqueued onto a turnstile, it can lend its priority > to the owning thread. > .Ss Semaphores > .Ss Condition variables > Condition variables are used in conjunction with mutexes to wait for conditions > to occur. > A thread must hold the mutex before calling the > .Fn cv_wait* , > functions. > When a thread waits on a condition, the mutex > is atomically released before the thread is blocked, then reacquired > before the function call returns. > .Ss Giant > Giant is a special instance of a sleep lock. > it has several special characteristics. > .Ss Sleep/wakeup > The functions > .Fn tsleep , > .Fn msleep , > .Fn msleep_spin , > .Fn pause , > .Fn wakeup , > and > .Fn wakeup_one > handle event-based thread blocking. > If a thread must wait for an > external event, it is put to sleep by > .Fn tsleep , > .Fn msleep , > .Fn msleep_spin , > or > .Fn pause . > Threads may also wait using one of the locking primitive sleep routines > .Xr mtx_sleep 9 , > .Xr rw_sleep 9 , > or > .Xr sx_sleep 9 . > .Pp > The parameter > .Fa chan > is an arbitrary address that uniquely identifies the event on which > the thread is being put to sleep. > All threads sleeping on a single > .Fa chan > are woken up later by > .Fn wakeup , > often called from inside an interrupt routine, to indicate that the > resource the thread was blocking on is available now. > .Pp > Several of the sleep functions including > .Fn msleep , > .Fn msleep_spin , > and the locking primitive sleep routines specify an additional lock > parameter. > The lock will be released before sleeping and reacquired > before the sleep routine returns. > If > .Fa priority > includes the > .Dv PDROP > flag, then > the lock will not be reacquired before returning. > The lock is used to ensure that a condition can be checked atomically, > and that the current thread can be suspended without missing a > change to the condition, or an associated wakeup. > In addition, all of the sleep routines will fully drop the > .Va Giant > mutex > (even if recursed) > while the thread is suspended and will reacquire the > .Va Giant > mutex before the function returns. > .Pp > .Ss lockmanager locks > Largly deprecated. See the > .Xr lock 9 > page for more information. > I don't know what the downsides are but I'm sure someone will fill in this part. > .Sh Interaction tables. > the following table shows what you can an d can not do if you hold > one of the synchronisation primatives discussed here: > (someone who knows what they are talking about should write this table) > .Bl -column ".Ic You have: You want:" ".Xr sleep" ".Xr sc_lock" ".Xr rw_lock" -offset indent > .It Xo > .Em "You have: You want:" Ta Xr sleep Ta Xr sx_lock Ta Xr rw_lock > .Xc > .It Ic SPIN mutex Ta \&tough Ta \&tough Ta \&tough > .It Ic Sleep mutex Ta \&ok Ta \&??? Ta \&??? > .El > .Sh SEE ALSO > .Xr condvar 9 , > .Xr lock 9 > .Xr mtx_pool 9 , > .Xr rwlock 9 , > .Xr sema 9 , > .Xr sleep 9 , > .Xr sx 9 > .Xr LOCK_PROFILING 9 , > .Xr WITNESS 9 , > .Sh HISTORY > These > functions appeared in > .Bsx 4.1 > through > .Fx 7.0 > _______________________________________________ > freebsd-current@freebsd.org mailing list > http://lists.freebsd.org/mailman/listinfo/freebsd-current > To unsubscribe, send any mail to "freebsd-current-unsubscribe@freebsd.org" --Boundary_(ID_kUUvEUDVInxTTnzno43fcA) Content-type: text/plain; NAME=Makefile.patch; charset=us-ascii Content-transfer-encoding: 7BIT Content-disposition: inline; filename=Makefile.patch --- /usr/src/share/man/man9/Makefile.old Fri Mar 16 20:14:48 2007 +++ /usr/src/share/man/man9/Makefile Fri Mar 16 20:09:01 2007 @@ -133,6 +133,7 @@ kthread.9 \ ktr.9 \ lock.9 \ + locking.9 \ LOCK_PROFILING.9 \ mac.9 \ make_dev.9 \ --Boundary_(ID_kUUvEUDVInxTTnzno43fcA)--