Allow threads to atomically release rw and sx locks while waiting for an

event.  Locking primitives that support this (mtx, rw, and sx) now each
include their own foo_sleep() routine.
- Rename msleep() to _sleep() and change it's 'struct mtx' object to a
  'struct lock_object' pointer.  _sleep() uses the recently added
  lc_unlock() and lc_lock() function pointers for the lock class of the
  specified lock to release the lock while the thread is suspended.
- Add wrappers around _sleep() for mutexes (mtx_sleep()), rw locks
  (rw_sleep()), and sx locks (sx_sleep()).  msleep() still exists and
  is now identical to mtx_sleep(), but it is deprecated.
- Rename SLEEPQ_MSLEEP to SLEEPQ_SLEEP.
- Rewrite much of sleep.9 to not be msleep(9) centric.
- Flesh out the 'RETURN VALUES' section in sleep.9 and add an 'ERRORS'
  section.
- Add __nonnull(1) to _sleep() and msleep_spin() so that the compiler will
  warn if you try to pass a NULL wait channel.  The functions already have
  a KASSERT to that effect.

1 files changed, 11 insertions, 1 deletions

diff --git a/share/man/man9/sx.9 b/share/man/man9/sx.9
index a204ad5..50c0bc4 100644
--- a/share/man/man9/sx.9
+++ b/share/man/man9/sx.9
@@ -42,6 +42,7 @@
 .Nm sx_unlock ,
 .Nm sx_try_upgrade ,
 .Nm sx_downgrade ,
+.Nm sx_sleep ,
 .Nm sx_xlocked ,
 .Nm sx_assert ,
 .Nm SX_SYSINIT
@@ -73,6 +74,8 @@
 .Ft void
 .Fn sx_downgrade "struct sx *sx"
 .Ft int
+.Fn sx_sleep "void *chan" "struct sx *sx" "int priority" "const char *wmesg" "int timo"
+.Ft int
 .Fn sx_xlocked "struct sx *sx"
 .Pp
 .Cd "options INVARIANTS"
@@ -134,6 +137,13 @@ will return 0 if the shared lock cannot be upgraded to an exclusive lock
 immediately; otherwise the exclusive lock will be acquired and a non-zero value
 will be returned.
 .Pp
+A thread can atomically release a shared/exclusive lock while waiting for an
+event by calling
+.Fn sx_sleep .
+For more details on the parameters to this function,
+see
+.Xr sleep 9 .
+.Pp
 When compiled with
 .Cd "options INVARIANTS"
 and
@@ -169,7 +179,7 @@ by the first argument.
 .El
 .Pp
 .Fn sx_xlocked
-will return non-zero if the current process holds the exclusive lock;
+will return non-zero if the current thread holds the exclusive lock;
 otherwise, it will return zero.
 .Pp
 For ease of programming,