docs/75571: man page for sx(9) is misleading

[Giorgos Keramidas]

The following reply was made to PR docs/75571; it has been noted by GNATS.

From: Giorgos Keramidas <keramida at freebsd.org>
To: John Baldwin <jhb at freebsd.org>
Cc: bug-followup at 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 at freebsd.org> wrote:
 >On Wednesday 29 December 2004 03:40 am, Giorgos Keramidas wrote:
 >>On 2004-12-28 13:55, Darren Reed <darrenr at 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 ,
 %%%