From owner-freebsd-doc@FreeBSD.ORG Wed Jan 5 21:07:43 2005 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 7E63316A4E6 for ; Wed, 5 Jan 2005 21:07:43 +0000 (GMT) Received: from mail5.speakeasy.net (mail5.speakeasy.net [216.254.0.205]) by mx1.FreeBSD.org (Postfix) with ESMTP id 1A89143D2F for ; Wed, 5 Jan 2005 21:07:43 +0000 (GMT) (envelope-from jhb@FreeBSD.org) Received: (qmail 15745 invoked from network); 5 Jan 2005 21:07:42 -0000 Received: from dsl027-160-063.atl1.dsl.speakeasy.net (HELO server.baldwin.cx) ([216.27.160.63]) (envelope-sender ) encrypted SMTP for ; 5 Jan 2005 21:07:42 -0000 Received: from [10.50.41.243] (gw1.twc.weather.com [216.133.140.1]) (authenticated bits=0) by server.baldwin.cx (8.12.11/8.12.11) with ESMTP id j05L7QC6076097; Wed, 5 Jan 2005 16:07:35 -0500 (EST) (envelope-from jhb@FreeBSD.org) From: John Baldwin To: freebsd-doc@FreeBSD.org, Giorgos Keramidas Date: Wed, 5 Jan 2005 15:49:58 -0500 User-Agent: KMail/1.6.2 References: <200501032320.j03NKQDR098896@freefall.freebsd.org> In-Reply-To: <200501032320.j03NKQDR098896@freefall.freebsd.org> MIME-Version: 1.0 Content-Disposition: inline Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Message-Id: <200501051549.58949.jhb@FreeBSD.org> X-Spam-Checker-Version: SpamAssassin 2.63 (2004-01-11) on server.baldwin.cx Subject: Re: docs/75571: man page for sx(9) is misleading X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 05 Jan 2005 21:07:43 -0000 On Monday 03 January 2005 06:20 pm, Giorgos Keramidas wrote: > The following reply was made to PR docs/75571; it has been noted by GNATS. > > From: Giorgos Keramidas > To: John Baldwin > 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 wrote: > >On Wednesday 29 December 2004 03:40 am, Giorgos Keramidas wrote: > >>On 2004-12-28 13:55, Darren Reed 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 , > %%% Hmm, that's a good place to put that, here's a minor wording tweak: As a result, an .Nm lock may not be acquired while holding a mutex. Otherwise, if one thread slept while holding an .Nm lock while another thread blocked on the same .Nm lock after acquiring a mutex, then the second thread would effectively end up sleeping while holding a mutex. Eesh, any way you say it it ends up being a mouthful. :-P -- John Baldwin <>< http://www.FreeBSD.org/~jhb/ "Power Users Use the Power to Serve" = http://www.FreeBSD.org