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

[John Baldwin]

On Wednesday 29 December 2004 03:40 am, Giorgos Keramidas wrote:
> The following reply was made to PR docs/75571; it has been noted by GNATS.
>
> From: Giorgos Keramidas <keramida at ceid.upatras.gr>
> To: bug-followup at 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 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.
>
>  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.

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.

>  %%%
>  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 ,
>  %%%
> _______________________________________________
> freebsd-doc at freebsd.org mailing list
> http://lists.freebsd.org/mailman/listinfo/freebsd-doc
> To unsubscribe, send any mail to "freebsd-doc-unsubscribe at freebsd.org"

-- 
John Baldwin <jhb at FreeBSD.org>  <><  http://www.FreeBSD.org/~jhb/
"Power Users Use the Power to Serve"  =  http://www.FreeBSD.org