From darrenr@FreeBSD.ORG  Tue Dec 28 13:55:35 2004
Return-Path: <darrenr@FreeBSD.ORG>
Received: by hub.freebsd.org (Postfix, from userid 680)
	id F30B916A4CF; Tue, 28 Dec 2004 13:55:34 +0000 (GMT)
Message-Id: <20041228135534.F30B916A4CF@hub.freebsd.org>
Date: Tue, 28 Dec 2004 13:55:34 +0000 (GMT)
From: Darren Reed <darrenr@FreeBSD.ORG>
Reply-To: Darren Reed <darrenr@FreeBSD.ORG>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: man page for sx(9) is misleading
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         75571
>Category:       docs
>Synopsis:       man page for sx(9) is misleading
>Confidential:   no
>Severity:       serious
>Priority:       low
>Responsible:    keramida
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Dec 28 14:00:47 GMT 2004
>Closed-Date:    Mon Jan 17 11:35:56 GMT 2005
>Last-Modified:  Mon Jan 17 11:35:56 GMT 2005
>Originator:     Darren Reed
>Release:        FreeBSD 4.10-STABLE i386
>Organization:
>Environment:
System: FreeBSD hub.freebsd.org 4.10-STABLE FreeBSD 4.10-STABLE #7: Sun Nov 21 15:33:21 GMT 2004 kensmith@hub.freebsd.org:/g/src/sys/compile/HUB i386


	
>Description:
According to discussion on freebsd mailing lists, it is not possible
to hold an sx lock when you want a mtx lock.  This should be documented.
>How-To-Repeat:
	
>Fix:

	


>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@ceid.upatras.gr>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: docs/75571: man page for sx(9) is misleading
Date: Wed, 29 Dec 2004 10:37:13 +0200

 On 2004-12-28 13:55, Darren Reed <darrenr@FreeBSD.ORG> wrote:
 >
 > According to discussion on freebsd mailing lists, it is not possible
 > to hold an sx lock when you want a mtx lock.  This should be documented.
 
 As far as I can tell, by looking at kern_sx.c and sys/sx.h, this is
 because the sx lock initialization uses an mtxpool for the mutex used to
 serialize access to the internal sx lock data.
 
 Leaf locks may be used in operations that msleep() but there can be only
 one of them in each lock path and no other lock can be obtained after
 them.
 
 This is sort of implied by the SEE ALSO reference of mtx_pool(9), but we
 should probably state it explicitly in CONTEXT.
 
 %%%
 Index: sx.9
 ===================================================================
 RCS file: /home/ncvs/src/share/man/man9/sx.9,v
 retrieving revision 1.29
 diff -u -r1.29 sx.9
 --- sx.9        11 Jul 2004 16:08:25 -0000      1.29
 +++ sx.9        28 Dec 2004 23:28:22 -0000
 @@ -196,6 +196,11 @@
  A thread may hold a shared or exclusive lock on an
  .Nm
  lock while sleeping.
 +The
 +.Nm
 +locks are implemented using
 +.Xr mtxpool 9
 +shared leaf locks, so they should always be the last lock obtained.
  .Sh SEE ALSO
  .Xr condvar 9 ,
  .Xr mtx_pool 9 ,
 %%%

Adding to audit trail from misfiled PR 75655:

From: Darren Reed <darrenr@hub.freebsd.org>
Date: Thu, 30 Dec 2004 14:06:38 +0000
Subject: Re: man page for sx(9) is misleading

 What you wrote is not right.  You cannot acquire an sx(9) lock while holding
 an mtx(9) lock.
 
 Darren

From: Giorgos Keramidas <keramida@freebsd.org>
To: John Baldwin <jhb@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/75571: man page for sx(9) is misleading
Date: Tue, 4 Jan 2005 01:11:36 +0200

 On 2004-12-29 13:34, John Baldwin <jhb@freebsd.org> wrote:
 >On Wednesday 29 December 2004 03:40 am, Giorgos Keramidas wrote:
 >>On 2004-12-28 13:55, Darren Reed <darrenr@FreeBSD.ORG> wrote:
 >>> According to discussion on freebsd mailing lists, it is not possible
 >>> to hold an sx lock when you want a mtx lock.  This should be documented.
 >>
 >> As far as I can tell, by looking at kern_sx.c and sys/sx.h, this is
 >> because the sx lock initialization uses an mtxpool for the mutex used to
 >> serialize access to the internal sx lock data. [...]
 >
 > The reason is largely because they can be held across a sleep, e.g.:
 >
 > 	sx_xlock(&foo->sx);
 > 	bar = malloc(sizeof(*bar), M_FOO, M_WAITOK);
 > 	TAILQ_INSERT_TAIL(&foo->head, bar, link);
 > 	sx_xunlock(&foo->sx);
 >
 > This is intentional and that is what should be documented.  Basically, it
 > needs a paragraph to the effect of:
 >
 > .Pp
 > An
 > .Nm
 > lock may not be acquired while holding a mutex.
 > Since threads are allowed to sleep while holding an
 > .NM
 > lock,
 > a thread that acquired a mutex and then blocked on an
 > .Nm
 > lock would end up sleeping while holding a mutex which is not allowed.
 
 Nice :-)
 
 Thanks for putting this in words.  Should I commit this?
 
 %%%
 Index: sx.9
 ===================================================================
 RCS file: /home/ncvs/src/share/man/man9/sx.9,v
 retrieving revision 1.29
 diff -u -5 -r1.29 sx.9
 --- sx.9	11 Jul 2004 16:08:25 -0000	1.29
 +++ sx.9	3 Jan 2005 23:08:40 -0000
 @@ -194,10 +194,19 @@
  attempting to do so will result in deadlock.
  .Sh CONTEXT
  A thread may hold a shared or exclusive lock on an
  .Nm
  lock while sleeping.
 +As a result, an
 +.Nm
 +lock may not be acquired while holding a mutex.
 +Since threads are allowed to sleep while holding an
 +.Nm
 +lock,
 +a thread that acquired a mutex and then blocked on an
 +.Nm
 +lock would end up sleeping while holding a mutex which is not allowed.
  .Sh SEE ALSO
  .Xr condvar 9 ,
  .Xr mtx_pool 9 ,
  .Xr mutex 9 ,
  .Xr panic 9 ,
 %%%
State-Changed-From-To: open->patched 
State-Changed-By: keramida 
State-Changed-When: Wed Jan 5 22:04:22 GMT 2005 
State-Changed-Why:  
Committed the last explanation of John to HEAD. 


Responsible-Changed-From-To: freebsd-doc->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Wed Jan 5 22:04:22 GMT 2005 
Responsible-Changed-Why:  
I'll handle the MFC of this in a few days. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=75571 
State-Changed-From-To: patched->closed 
State-Changed-By: keramida 
State-Changed-When: Mon Jan 17 11:35:33 GMT 2005 
State-Changed-Why:  
The sx(9) manpage in RELENG_5 is now in sync with HEAD. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=75571 
>Unformatted:
