Implement mtx_trylock_spin(9).

Discussed with:	bde
Reviewed by:	jhb
Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
Differential revision:	https://reviews.freebsd.org/D7192

2 files changed, 37 insertions, 11 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 8617cba29f92..f519e0f20f28 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1181,6 +1181,8 @@ MLINKS+=mutex.9 mtx_assert.9 \
 	mutex.9 MTX_SYSINIT.9 \
 	mutex.9 mtx_trylock.9 \
 	mutex.9 mtx_trylock_flags.9 \
+	mutex.9 mtx_trylock_spin.9 \
+	mutex.9 mtx_trylock_spin_flags.9 \
 	mutex.9 mtx_unlock.9 \
 	mutex.9 mtx_unlock_flags.9 \
 	mutex.9 mtx_unlock_spin.9 \
diff --git a/share/man/man9/mutex.9 b/share/man/man9/mutex.9
index 64ec426dd96a..f7d242c84c8b 100644
--- a/share/man/man9/mutex.9
+++ b/share/man/man9/mutex.9
@@ -28,7 +28,7 @@
 .\"	from BSDI $Id: mutex.4,v 1.1.2.3 1998/04/27 22:53:13 ewv Exp $
 .\" $FreeBSD$
 .\"
-.Dd December 13, 2014
+.Dd July 18, 2016
 .Dt MUTEX 9
 .Os
 .Sh NAME
@@ -41,6 +41,8 @@
 .Nm mtx_lock_spin_flags ,
 .Nm mtx_trylock ,
 .Nm mtx_trylock_flags ,
+.Nm mtx_trylock_spin ,
+.Nm mtx_trylock_spin_flags ,
 .Nm mtx_unlock ,
 .Nm mtx_unlock_spin ,
 .Nm mtx_unlock_flags ,
@@ -73,6 +75,10 @@
 .Ft int
 .Fn mtx_trylock_flags "struct mtx *mutex" "int flags"
 .Ft void
+.Fn mtx_trylock_spin "struct mtx *mutex"
+.Ft int
+.Fn mtx_trylock_spin_flags "struct mtx *mutex" "int flags"
+.Ft void
 .Fn mtx_unlock "struct mtx *mutex"
 .Ft void
 .Fn mtx_unlock_spin "struct mtx *mutex"
@@ -249,26 +255,33 @@ argument, then the mutex can be acquired recursively.
 .Pp
 The
 .Fn mtx_trylock
-attempts to acquire the
+and
+.Fn mtx_trylock_spin
+functions attempt to acquire a
 .Dv MTX_DEF
-mutex pointed to by
+or
+.Dv MTX_SPIN
+mutex, respectively, pointed to by
 .Fa mutex .
-If the mutex cannot be immediately acquired
-.Fn mtx_trylock
-will return 0,
-otherwise the mutex will be acquired
-and a non-zero value will be returned.
+If the mutex cannot be immediately acquired, the functions will return 0,
+otherwise the mutex will be acquired and a non-zero value will be returned.
 .Pp
 The
 .Fn mtx_trylock_flags
-function has the same behavior as
+and
+.Fn mtx_trylock_spin_flags
+functions have the same behavior as
 .Fn mtx_trylock
-but should be used when the caller desires to pass in a
+and
+.Fn mtx_trylock_spin
+respectively, but should be used when the caller desires to pass in a
 .Fa flags
 value.
 Presently, the only valid value in the
 .Fn mtx_trylock
-case is
+and
+.Fn mtx_trylock_spin
+cases is
 .Dv MTX_QUIET ,
 and its effects are identical to those described for
 .Fn mtx_lock
@@ -447,6 +460,13 @@ while any spin lock is held.
 .It Dv MTX_RECURSE
 Specifies that the initialized mutex is allowed to recurse.
 This bit must be present if the mutex is permitted to recurse.
+.Pp
+Note that neither
+.Fn mtx_trylock
+nor
+.Fn mtx_trylock_spin
+support recursion;
+that is, attempting to acquire an already-owned mutex fails.
 .It Dv MTX_QUIET
 Do not log any mutex operations for this lock.
 .It Dv MTX_NOWITNESS
@@ -534,3 +554,7 @@ functions appeared in
 .Bsx 4.1
 and
 .Fx 5.0 .
+The
+.Fn mtx_trylock_spin
+function was added in
+.Fx 12.0 .