mutex.9: Misc updates and minor improvements.

* mtx_spinlock_ex() and mtx_spinlock_sh() do not exist anymore. mtx_spinlock()
  replaced both.

* Add MLINKS for mtx_lock(), mtx_spinlock_try() and mtx_spinunlock().

* Use .Fn for function name mtx_lock_ex_quick().

* Add some text describing mtx_lock(), mtx_spinlock_try() and mtx_spinunlock().

* Start a sentence with capital letter but avoid starting with a function name.

* Add a missing .Fa.

* Add a cross reference to sleep(9) in the SEE ALSO section.

* Bump date.

Reviewed-by: swildner

diff --git a/Makefile_upgrade.inc b/Makefile_upgrade.inc
index 65c1732..872d0ac 100644 (file)
--- a/Makefile_upgrade.inc
+++ b/Makefile_upgrade.inc
@@ -2032,6 +2032,10 @@ TO_REMOVE+=/etc/pam.d/kde
 TO_REMOVE+=/etc/rc.d/vfs_accounting
 TO_REMOVE+=/usr/share/man/cat3/svc_control.3.gz
 TO_REMOVE+=/usr/share/man/man3/svc_control.3.gz
+TO_REMOVE+=/usr/share/man/cat9/mtx_spinlock_ex.9.gz
+TO_REMOVE+=/usr/share/man/man9/mtx_spinlock_ex.9.gz
+TO_REMOVE+=/usr/share/man/cat9/mtx_spinlock_sh.9.gz
+TO_REMOVE+=/usr/share/man/man9/mtx_spinlock_sh.9.gz
 
 .if ${MACHINE_ARCH} == "x86_64"
 TO_REMOVE+=/usr/libdata/stallion/2681.sys

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index b098349..ffcae91 100644 (file)
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -682,6 +682,7 @@ MLINKS+=mutex.9 mtx_downgrade.9 \
        mutex.9 mtx_init.9 \
        mutex.9 mtx_islocked.9 \
        mutex.9 mtx_islocked_ex.9 \
+       mutex.9 mtx_lock.9 \
        mutex.9 mtx_lock_ex.9 \
        mutex.9 mtx_lock_ex_quick.9 \
        mutex.9 mtx_lock_ex_try.9 \
@@ -693,8 +694,9 @@ MLINKS+=mutex.9 mtx_downgrade.9 \
        mutex.9 mtx_notlocked_ex.9 \
        mutex.9 mtx_notowned.9 \
        mutex.9 mtx_owned.9 \
-       mutex.9 mtx_spinlock_ex.9 \
-       mutex.9 mtx_spinlock_sh.9 \
+       mutex.9 mtx_spinlock.9 \
+       mutex.9 mtx_spinlock_try.9 \
+       mutex.9 mtx_spinunlock.9 \
        mutex.9 mtx_uninit.9 \
        mutex.9 mtx_unlock.9 \
        mutex.9 mtx_unlock_ex.9 \

diff --git a/share/man/man9/mutex.9 b/share/man/man9/mutex.9
index c114850..0760f07 100644 (file)
--- a/share/man/man9/mutex.9
+++ b/share/man/man9/mutex.9
@@ -28,7 +28,7 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 9, 2010
+.Dd August 24, 2012
 .Dt MUTEX 9
 .Os
 .Sh NAME
@@ -39,15 +39,17 @@
 .Nm mtx_lock_sh_quick ,
 .Nm mtx_lock_ex ,
 .Nm mtx_lock_ex_quick ,
-.Nm mtx_spinlock_ex ,
-.Nm mtx_spinlock_sh ,
+.Nm mtx_lock ,
+.Nm mtx_spinlock ,
 .Nm mtx_lock_ex_try ,
 .Nm mtx_lock_sh_try ,
+.Nm mtx_spinlock_try ,
 .Nm mtx_downgrade ,
 .Nm mtx_upgrade_try ,
 .Nm mtx_unlock ,
 .Nm mtx_unlock_ex ,
 .Nm mtx_unlock_sh ,
+.Nm mtx_spinunlock ,
 .Nm mtx_islocked ,
 .Nm mtx_islocked_ex ,
 .Nm mtx_notlocked ,
@@ -74,13 +76,15 @@
 .Ft void
 .Fn mtx_lock_ex_quick "struct mtx *mtx" "const char *ident"
 .Ft void
-.Fn mtx_spinlock_ex "struct mtx *mtx"
+.Fn mtx_lock "struct mtx *mtx"
 .Ft void
-.Fn mtx_spinlock_sh "struct mtx *mtx"
+.Fn mtx_spinlock "struct mtx *mtx"
 .Ft int
 .Fn mtx_lock_ex_try "struct mtx *mtx"
 .Ft int
 .Fn mtx_lock_sh_try "struct mtx *mtx"
+.Ft int
+.Fn mtx_spinlock_try "struct mtx *mtx"
 .Ft void
 .Fn mtx_downgrade "struct mtx *mtx"
 .Ft int
@@ -91,6 +95,8 @@
 .Fn mtx_unlock_ex "struct mtx *mtx"
 .Ft void
 .Fn mtx_unlock_sh "struct mtx *mtx"
+.Ft void
+.Fn mtx_spinunlock "struct mtx *mtx"
 .Ft int
 .Fn mtx_islocked "struct mtx *mtx"
 .Ft int
@@ -154,9 +160,14 @@ The
 .Fa flags
 parameter is passed to
 .Xr tsleep 9
-if the thread must block; the to parameter is a timeout for the sleep.
+if the thread must block; the
+.Fa to
+parameter is a timeout for the sleep.
+The
 .Fn mtx_lock_sh_quick
-is a version without flags or a timeout.
+function is a version of
+.Fn mtx_lock_sh
+without flags or a timeout.
 .Pp
 The
 .Fn mtx_lock_ex
@@ -164,20 +175,27 @@ function attempts to lock a mutex exclusively and blocks the current thread
 until it is able to do so.
 The
 .Fa ident
-parameter and flags parameters are as in
+and
+.Fa flags
+parameters are as in
 .Xr tsleep 9 .
 The
 .Fa to
 parameter is a timeout on the sleep.
-.Fa mtx_lock_ex_quick
-is is a version without flags or a timeout.
+The
+.Fn mtx_lock_ex_quick
+function is is a version of
+.Fn mtx_lock_ex
+without flags or a timeout.
+The
+.Fn mtx_lock
+function is a yet shorter form for exclusively locking a mutex, blocking the
+current thread until acquired.
+It is equivalent to mtx_lock_ex(mtx, "mtxex", 0, 0).
 .Pp
 The
-.Fn mtx_spinlock_ex
+.Fn mtx_spinlock
 function attempts to lock the mutex in exclusive mode and spins until it is
-able to do so; the
-.Fn mtx_spinlock_sh
-function attempts to lock the mutex in shared mode and spins until it is
 able to do so.
 .Pp
 The
@@ -187,6 +205,9 @@ and
 functions attempt to lock the mutex in exclusive or shared mode, respectively.
 If they are not able to, they return
 .Er EAGAIN .
+The
+.Fn mtx_spinlock_try
+function does the same but for spin mutexes.
 .Pp
 The
 .Fn mtx_downgrade
@@ -213,6 +234,10 @@ functions are optimized unlock paths, used when it is known that a lock is held
 exclusively or in shared state.
 .Pp
 The
+.Fn mtx_spinunlock
+function releases a held spin mutex.
+.Pp
+The
 .Fn mtx_islocked
 function returns non-zero if the mutex is locked in either shared of
 exclusive state by any thread.
@@ -258,6 +283,7 @@ The core of the spinlock implementation is in
 .Xr crit_enter 9 ,
 .Xr lockmgr 9 ,
 .Xr serializer 9 ,
+.Xr sleep 9 ,
 .Xr spinlock 9
 .Sh HISTORY
 Mutexes first appeared in