From 91ef0220c73534d8f9d74be0c0ded73de4c09664 Mon Sep 17 00:00:00 2001 From: Brendon Scheinman Date: Sat, 9 Mar 2013 10:05:01 -0600 Subject: [PATCH] ck_cohort: Cleaned up documentation changes --- doc/CK_COHORT_PROTOTYPE | 15 ++++++++------- doc/CK_COHORT_TRYLOCK | 7 ++++--- doc/CK_COHORT_TRYLOCK_PROTOTYPE | 19 ++++++++++--------- doc/ck_cohort | 2 +- 4 files changed, 23 insertions(+), 20 deletions(-) diff --git a/doc/CK_COHORT_PROTOTYPE b/doc/CK_COHORT_PROTOTYPE index c019209..e8766af 100644 --- a/doc/CK_COHORT_PROTOTYPE +++ b/doc/CK_COHORT_PROTOTYPE @@ -39,23 +39,24 @@ Concurrency Kit (libck, \-lck) The ck_cohort.h header file does not define any cohort types. Instead, the user must use the CK_COHORT_PROTOTYPE or .Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 -macros to define any types they want to use. The CK_COHORT_PROTOTYPE macro takes the -following arguments: +macros to define any types they want to use. They must use CK_COHORT_TRYLOCK_PROTOTYPE +if they want their cohort type to support trylock operations. +The CK_COHORT_PROTOTYPE macro takes the following arguments: .Pp -.Fa COHORT_NAME cohort_name +.Fa cohort_name : An identifier used for this cohort type. This will have to be passed to each of the other CK_COHORT macros. .br -.Fa LOCK_FXN global_lock_method +.Fa global_lock_method : The method that should be called to acquire the global lock .br -.Fa LOCK_FXN global_unlock_method +.Fa global_unlock_method : The method that should be called to relinquish the global lock .br -.Fa LOCK_FXN local_lock_method +.Fa local_lock_method : The method that should be called to acquire the local lock .br -.Fa LOCK_FXN local_unlock_method +.Fa local_unlock_method : The method that should be called to relinquish the local lock .Pp Instances of the defined cohort type can be declared as: diff --git a/doc/CK_COHORT_TRYLOCK b/doc/CK_COHORT_TRYLOCK index 23c08fc..55959df 100644 --- a/doc/CK_COHORT_TRYLOCK +++ b/doc/CK_COHORT_TRYLOCK @@ -37,7 +37,8 @@ Concurrency Kit (libck, \-lck) "void *local_trylock_context" "void *lock_unlock_context" .Sh DESCRIPTION This call attempts to acquire both the local and global (if necessary) locks from -.Fa cohort . It can only be used with cohort types that were defined using the +.Fa cohort . +It can only be used with cohort types that were defined using the .Xr CK_COHORT_TRYLOCK_PROTOTYPE 3 macro. The call will not block and will return a bool that will evaluate to true iff the cohort was successfully acquired. @@ -47,8 +48,8 @@ will be passed as the second argument to the function that was provided as the argument to CK_COHORT_TRYLOCK_PROTOTYPE if that method is called, and .Fa local_trylock_context will be passed to the function specified by -.Fa local_trylock_method -. If the global lock acquisition fails, then the cohort will immediately release its +.Fa local_trylock_method . +If the global lock acquisition fails, then the cohort will immediately release its local lock as well, and .Fa local_unlock_context will be passed to the function specified by diff --git a/doc/CK_COHORT_TRYLOCK_PROTOTYPE b/doc/CK_COHORT_TRYLOCK_PROTOTYPE index d7eddc4..62f3e68 100644 --- a/doc/CK_COHORT_TRYLOCK_PROTOTYPE +++ b/doc/CK_COHORT_TRYLOCK_PROTOTYPE @@ -39,30 +39,31 @@ Concurrency Kit (libck, \-lck) .Sh DESCRIPTION The ck_cohort.h header file does not define any cohort types. Instead, the user must use the CK_COHORT_PROTOTYPE or CK_COHORT_TRYLOCK_PROTOTYPE macros to define any types -they want to use. The CK_COHORT_TRYLOCK_PROTOTYPE macro takes the -following arguments: +they want to use. +They must use CK_COHORT_TRYLOCK_PROTOTYPE if they want their cohort type to have support +for trylock operations. The CK_COHORT_TRYLOCK_PROTOTYPE macro takes the following arguments: .Pp -.Fa COHORT_NAME cohort_name +.Fa cohort_name : An identifier used for this cohort type. This will have to be passed to each of the other CK_COHORT macros. .br -.Fa LOCK_FXN global_lock_method +.Fa global_lock_method : The method that should be called to acquire the global lock .br -.Fa LOCK_FXN global_unlock_method +.Fa global_unlock_method : The method that should be called to relinquish the global lock .br -.Fa TRYLOCK_FXN global_trylock_method +.Fa global_trylock_method : The method that should be called to try to acquire the global lock. It should not block and return true iff the lock was successfully acquired. .br -.Fa LOCK_FXN local_lock_method +.Fa local_lock_method : The method that should be called to acquire the local lock .br -.Fa LOCK_FXN local_unlock_method +.Fa local_unlock_method : The method that should be called to relinquish the local lock .br -.Fa TRYLOCK_FXN local_trylock_method +.Fa local_trylock_method : The method that should be called to try to acquire the local lock. It should not block and return true iff the lock was successfully acquired. .Pp diff --git a/doc/ck_cohort b/doc/ck_cohort index cc6ba17..91f6c1e 100644 --- a/doc/ck_cohort +++ b/doc/ck_cohort @@ -55,7 +55,7 @@ and TRYLOCK_FXN refers to a method with the signature bool(void *lock, void *context) .Pp The -.Fa context +.Fa context argument in each signature is used to pass along any additional information that the lock might need for its lock, unlock and trylock methods. The values for this argument are provided to each call to