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

[John Baldwin]

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 <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 ,
>  %%%

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 <jhb at FreeBSD.org>  <><  http://www.FreeBSD.org/~jhb/
"Power Users Use the Power to Serve"  =  http://www.FreeBSD.org