From owner-svn-src-all@FreeBSD.ORG Thu Jan 28 17:09:48 2010 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 2418E10656BD; Thu, 28 Jan 2010 17:09:48 +0000 (UTC) (envelope-from trasz@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 11EC08FC21; Thu, 28 Jan 2010 17:09:48 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id o0SH9l6A000704; Thu, 28 Jan 2010 17:09:47 GMT (envelope-from trasz@svn.freebsd.org) Received: (from trasz@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id o0SH9lv5000702; Thu, 28 Jan 2010 17:09:47 GMT (envelope-from trasz@svn.freebsd.org) Message-Id: <201001281709.o0SH9lv5000702@svn.freebsd.org> From: Edward Tomasz Napierala Date: Thu, 28 Jan 2010 17:09:47 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r203122 - head/share/man/man9 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 28 Jan 2010 17:09:48 -0000 Author: trasz Date: Thu Jan 28 17:09:47 2010 New Revision: 203122 URL: http://svn.freebsd.org/changeset/base/203122 Log: Improve descriptions, remove turnstiles (since, from what I understand, they are only used to implement other synchronization primitives), tweak formatting. Modified: head/share/man/man9/locking.9 Modified: head/share/man/man9/locking.9 ============================================================================== --- head/share/man/man9/locking.9 Thu Jan 28 17:07:14 2010 (r203121) +++ head/share/man/man9/locking.9 Thu Jan 28 17:09:47 2010 (r203122) @@ -24,15 +24,12 @@ .\" .\" $FreeBSD$ .\" -.Dd March 14, 2007 +.Dd January 29, 2010 .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 @@ -43,21 +40,19 @@ to safely access and manipulate the many These include: .Bl -enum .It -Spin Mutexes -.It -Sleep Mutexes +Mutexes .It -pool Mutexes +Spin mutexes .It -Shared-Exclusive locks +Pool mutexes .It -Reader-Writer locks +Shared/exclusive locks .It -Read-Mostly locks +Reader/writer locks .It -Turnstiles +Read-mostly locks .It -Semaphores +Counting semaphores .It Condition variables .It @@ -70,36 +65,17 @@ Lockmanager locks .Pp The primitives interact and have a number of rules regarding how they can and can not be combined. -There are too many for the average -human mind and they keep changing. -(if you disagree, please write replacement text) :-) -.Pp -Some of these primitives 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 +Many of these rules are checked using the .Xr witness 4 code. .Pp -.Ss SPIN Mutexes -Mutexes are the basic primitive. -You either hold it or you don't. -If you don't own it then you just spin, waiting for the holder (on -another CPU) to release it. -Hopefully they are doing something fast. -You -.Em must not -do anything that deschedules the thread while you -are holding a SPIN mutex. .Ss Mutexes -Basically (regular) mutexes will deschedule the thread if the -mutex can not be acquired. -A non-spin mutex can be considered to be equivalent -to getting a write lock on an -.Em rw_lock -(see below), and in fact non-spin mutexes and rw_locks may soon become the same thing. -As in spin mutexes, you either get it or you don't. +Mutexes are the most commonly used synchronization primitive in the kernel. +Thread acquires (locks) a mutex before accessing data shared with other +threads (including interrupt threads), and releases (unlocks) it afterwards. +If the mutex cannot be acquired, the thread requesting it will block. +.Pp +Sleeping while holding mutex is generally prohibited. You may only call the .Xr sleep 9 call via @@ -122,10 +98,35 @@ If any caller above you has any mutex or rwlock, your sleep, will cause a panic. If the sleep only happens rarely it may be years before the bad code path is found. -.Ss Pool Mutexes -A variant of regular mutexes where the allocation of the mutex is handled -more by the system. -.Ss Rw_locks +.Pp +See the +.Xr mutex 9 +page for more information. +.Ss Spin mutexes +Spin mutexes are variation of basic mutexes; the main difference between +the two is that spin mutexes never block - instead, they spin, waiting +for the thread holding the lock, which runs on another CPU, to release it. +Differently from ordinary mutex, spin mutexes disable interrupts when acquired. +Since disabling interrupts is expensive, they are also generally slower. +Spin mutexes should only be used to protect data shared with primary +(INTR_FILTER) interrupt code. +You +.Em must not +do anything that deschedules the thread while you +are holding a spin mutex. +.Ss Pool mutexes +With most synchronisaton primitives, such as mutexes, programmer must +provide a piece of allocated memory to hold the primitive. +For example, a mutex may be embedded inside the structure it protects. +Pool mutex is a variant of mutex without this requirement - to lock or unlock +a pool mutex, one uses address of the structure being protected with it, +not the mutex itself. +Pool mutexes are seldom used. +.Pp +See the +.Xr mtx_pool 9 +page for more information. +.Ss Reader/writer 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 @@ -165,7 +166,11 @@ This ability should not be used lightly .Em may go away. Users of recursion in any locks should be prepared to defend their decision against vigorous criticism. -.Ss Rm_locks +.Pp +See the +.Xr rwlock 9 +page for more information. +.Ss Read-mostly locks Mostly reader locks are similar to .Em Reader/write locks but optimized for very infrequent @@ -176,7 +181,11 @@ locks implement full priority propagatio using a lock user supplied .Em tracker data structure. -.Ss Sx_locks +.Pp +See the +.Xr rmlock 9 +page for more information. +.Ss Shared/exclusive 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 @@ -201,16 +210,21 @@ should be considered to be closely relat .Xr sleep 9 . In fact it could in some cases be considered a conditional sleep. -.Ss Turnstiles -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. -If this sounds confusing, we need to describe it better. -.Ss Semaphores +.Pp +See the +.Xr sx 9 +page for more information. +.Ss Counting semaphores +Counting semaphores provide a mechanism for synchronizing access +to a pool of resources. +Unlike mutexes, semaphores do not have the concept of an owner, +so they can be useful in situations where one thread needs +to acquire a resource, and another thread needs to release it. +They are largely deprecated. +.Pp +See the +.Xr sema 9 +page for more information. .Ss Condition variables Condition variables are used in conjunction with mutexes to wait for conditions to occur. @@ -220,6 +234,10 @@ 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. +.Pp +See the +.Xr condvar 9 +page for more information. .Ss Giant Giant is a special instance of a sleep lock. It has several special characteristics. @@ -298,13 +316,24 @@ while the thread is suspended and will r .Va Giant mutex before the function returns. .Pp -.Ss lockmanager locks -Largely deprecated. +See the +.Xr sleep 9 +page for more information. +.Pp +.Ss Lockmanager locks +Shared/exclusive sleep locks, used mostly in +.Xr VFS 9 , +in particular as a +.Xr vnode 9 +lock. +They have features other lock types don't have, such as sleep timeout, +writer starvation avoidance, draining, and interlock mutex, but this makes them +complicated to implement; for this reason, they are deprecated. +.Pp 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 Usage tables. +.Sh INTERACTIONS .Ss Interaction table. The following table shows what you can and can not do if you hold one of the synchronization primitives discussed here: @@ -362,11 +391,13 @@ At this time this is a rather easy to re .Xr sema 9 , .Xr sleep 9 , .Xr sx 9 , -.Xr LOCK_PROFILING 9 , -.Xr WITNESS 9 +.Xr witness 9 , +.Xr LOCK_PROFILING 9 .Sh HISTORY These functions appeared in .Bsx 4.1 through .Fx 7.0 +.Sh BUGS +There are too many locking primitives to choose from.