X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/blobdiff_plain/24ef8cad2598c8dc0026e4124569498520eff67b..80921833365946e57ec66cf1e43b2e344dafaeee:/share/man/man9/token.9

diff --git a/share/man/man9/token.9 b/share/man/man9/token.9
index 27b4f02a87..0938aefa5e 100644
--- a/share/man/man9/token.9
+++ b/share/man/man9/token.9
@@ -31,9 +31,9 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 31, 2010
-.Os
+.Dd June 10, 2010
 .Dt TOKEN 9
+.Os
 .Sh NAME
 .Nm lwkt_token_init ,
 .Nm lwkt_token_uninit ,
@@ -41,7 +41,9 @@
 .Nm lwkt_trytoken ,
 .Nm lwkt_reltoken ,
 .Nm lwkt_token_pool_lookup ,
-.Nm lwkt_getpooltoken
+.Nm lwkt_getpooltoken ,
+.\".Nm lwkt_relpooltoken ,
+.Nm lwkt_token_swap
 .Nd soft token locks
 .Sh SYNOPSIS
 .In sys/thread.h
@@ -59,8 +61,11 @@
 .Fn lwkt_token_pool_lookup "void *ptr"
 .Ft struct lwkt_token *
 .Fn lwkt_getpooltoken "void *ptr"
+.Ft void
+.Fn lwkt_gettoken_shared "struct lwkt_token *tok"
+.Ft void
+.Fn lwkt_token_swap "void"
 .Sh DESCRIPTION
-.Pp
 A soft token is a lock which is only held while a thread is running.
 If a thread explicitly blocks, all its tokens are released, and reacquired
 when the thread resumes.
@@ -70,14 +75,28 @@ may change and may need to be reevaluated on wakeup.
 Tokens may be taken recursively.
 However, tokens must be released in the reverse order they were acquired.
 .Pp
+Tokens may be acquired in shared mode, allowing multiple concurrent holders,
+via
+.Fn lwkt_gettoken_shared ,
+or in exclusive mode, allowing only one holder, via
+.Fn lwkt_gettoken .
+It is safe to acquire a token shared while holding it exclusively.
+A thread attempting to acquire a token exclusively after holding it shared
+will deadlock. 
+.Pp
 The pool token interface exists to allow using tokens with data structures
 which may be deallocated.
 It allows getting a token reference from an address, which
 is implemented by a set of statically allocated tokens and a hash function.
 .Pp
+It is not recommended to take pool tokens in shared mode. A hash collision
+from a subsequent exclusive pool token request will hit the
+exclusive-after-shared deadlock.
+.Pp
 The
 .Fn lwkt_token_init
-function is called to initialize a token. The
+function is called to initialize a token.
+The
 .Fa desc
 argument specifies the wait string displayed when waiting for the token.
 The
@@ -107,6 +126,12 @@ function acquires a token associated with an address.
 Use these two functions when tokens must protect a data structure,
 but the structure can be deallocated.
 Pool tokens do not need to be initialized.
+.Pp
+The
+.Fn lwkt_token_swap
+function swaps the two most recently acquired tokens; this allows release of
+tokens out-of-order.
+This function should not be called when less than two tokens are held.
 .Sh EXAMPLES
 A simple example of using a token to protect access to a data structure:
 .Bd -literal
@@ -220,6 +245,8 @@ The LWKT Token implementation is in
 .Sh HISTORY
 LWKT tokens first appeared in
 .Dx 1.0 .
+Shared tokens first appeared in
+.Dx 2.11 .
 .Sh AUTHORS
 The
 .Nm token