From dcece5c7521207769edc2756956f76ef8b485ce1 Mon Sep 17 00:00:00 2001 From: Nuno Antunes Date: Fri, 24 Aug 2012 15:45:35 +0100 Subject: [PATCH] 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 --- Makefile_upgrade.inc | 4 +++ share/man/man9/Makefile | 6 +++-- share/man/man9/mutex.9 | 54 ++++++++++++++++++++++++++++++----------- 3 files changed, 48 insertions(+), 16 deletions(-) diff --git a/Makefile_upgrade.inc b/Makefile_upgrade.inc index 65c17329dd..872d0ac5a1 100644 --- 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 b098349fe6..ffcae91449 100644 --- 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 c114850cfd..0760f073d4 100644 --- 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 -- 2.41.0