mutex.9: Misc updates and minor improvements.
authorNuno Antunes <nuno.antunes@gmail.com>
Fri, 24 Aug 2012 14:45:35 +0000 (15:45 +0100)
committerNuno Antunes <nuno.antunes@gmail.com>
Fri, 24 Aug 2012 14:46:46 +0000 (15:46 +0100)
* 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
Makefile_upgrade.inc
share/man/man9/Makefile
share/man/man9/mutex.9

index 65c1732..872d0ac 100644 (file)
@@ -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+=/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
 
 .if ${MACHINE_ARCH} == "x86_64"
 TO_REMOVE+=/usr/libdata/stallion/2681.sys
index b098349..ffcae91 100644 (file)
@@ -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_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 \
        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_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 \
        mutex.9 mtx_uninit.9 \
        mutex.9 mtx_unlock.9 \
        mutex.9 mtx_unlock_ex.9 \
index c114850..0760f07 100644 (file)
@@ -28,7 +28,7 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\" 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
 .Dt MUTEX 9
 .Os
 .Sh NAME
 .Nm mtx_lock_sh_quick ,
 .Nm mtx_lock_ex ,
 .Nm mtx_lock_ex_quick ,
 .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_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_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 ,
 .Nm mtx_islocked ,
 .Nm mtx_islocked_ex ,
 .Nm mtx_notlocked ,
 .Ft void
 .Fn mtx_lock_ex_quick "struct mtx *mtx" "const char *ident"
 .Ft void
 .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
 .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_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
 .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"
 .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
 .Ft int
 .Fn mtx_islocked "struct mtx *mtx"
 .Ft int
@@ -154,9 +160,14 @@ The
 .Fa flags
 parameter is passed to
 .Xr tsleep 9
 .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
 .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
 .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
 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.
 .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
 .Pp
 The
-.Fn mtx_spinlock_ex
+.Fn mtx_spinlock
 function attempts to lock the mutex in exclusive mode and spins until it is
 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
 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 .
 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
 .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
 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.
 .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 crit_enter 9 ,
 .Xr lockmgr 9 ,
 .Xr serializer 9 ,
+.Xr sleep 9 ,
 .Xr spinlock 9
 .Sh HISTORY
 Mutexes first appeared in
 .Xr spinlock 9
 .Sh HISTORY
 Mutexes first appeared in