From 695e29fd7bb09a1b32915d280e544a024895b000 Mon Sep 17 00:00:00 2001 From: Brendon Scheinman Date: Sat, 9 Mar 2013 22:27:47 -0600 Subject: [PATCH] ck_cohort: Updated documentation to reflect ck_cohort_rw changes --- doc/CK_COHORT_INIT | 1 + doc/CK_COHORT_INSTANCE | 1 + doc/CK_COHORT_LOCK | 1 + doc/CK_COHORT_PROTOTYPE | 8 ++++++++ doc/CK_COHORT_TRYLOCK | 2 ++ doc/CK_COHORT_TRYLOCK_PROTOTYPE | 16 ++++++++++++---- doc/CK_COHORT_UNLOCK | 1 + doc/ck_cohort | 28 +++++++++++++++++++--------- 8 files changed, 45 insertions(+), 13 deletions(-) diff --git a/doc/CK_COHORT_INIT b/doc/CK_COHORT_INIT index 5f367de..ed97487 100644 --- a/doc/CK_COHORT_INIT +++ b/doc/CK_COHORT_INIT @@ -60,6 +60,7 @@ argument, you should use CK_COHORT_DEFAULT_LOCAL_PASS_LIMIT. .Xr CK_COHORT_INITIALIZER 3 , .Xr CK_COHORT_LOCK 3 , .Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , .Xr CK_COHORT_TRYLOCK 3 , .Pp Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_INSTANCE b/doc/CK_COHORT_INSTANCE index ca622a0..ee75465 100644 --- a/doc/CK_COHORT_INSTANCE +++ b/doc/CK_COHORT_INSTANCE @@ -53,6 +53,7 @@ CK_COHORT_INSTANCE(foo) *cohorts = malloc(4 * sizeof(CK_COHORT_INSTANCE(foo))); .Xr CK_COHORT_INITIALIZER 3 , .Xr CK_COHORT_LOCK 3 , .Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , .Xr CK_COHORT_TRYLOCK 3 , .Pp Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_LOCK b/doc/CK_COHORT_LOCK index a1e42e5..7f5e558 100644 --- a/doc/CK_COHORT_LOCK +++ b/doc/CK_COHORT_LOCK @@ -55,6 +55,7 @@ will be passed to the function specified by .Xr CK_COHORT_INITIALIZER 3 , .Xr CK_COHORT_INIT 3 , .Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , .Xr CK_COHORT_TRYLOCK 3 , .Pp Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_PROTOTYPE b/doc/CK_COHORT_PROTOTYPE index e8766af..f0977e0 100644 --- a/doc/CK_COHORT_PROTOTYPE +++ b/doc/CK_COHORT_PROTOTYPE @@ -53,11 +53,17 @@ of the other CK_COHORT macros. .Fa global_unlock_method : The method that should be called to relinquish the global lock .br +.Fa global_locked_method +: This method should return true iff the global lock is acquired by a thread. +.br .Fa local_lock_method : The method that should be called to acquire the local lock .br .Fa local_unlock_method : The method that should be called to relinquish the local lock +.br +.Fa global_locked_method +: This method should return true iff the local lock is acquired by a thread. .Pp Instances of the defined cohort type can be declared as: .br @@ -70,5 +76,7 @@ Instances of the defined cohort type can be declared as: .Xr CK_COHORT_INIT 3 , .Xr CK_COHORT_LOCK 3 , .Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , .Pp Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_TRYLOCK b/doc/CK_COHORT_TRYLOCK index 55959df..6330642 100644 --- a/doc/CK_COHORT_TRYLOCK +++ b/doc/CK_COHORT_TRYLOCK @@ -62,6 +62,8 @@ when this call is made. .Xr CK_COHORT_INSTANCE 3 , .Xr CK_COHORT_INITIALIZER 3 , .Xr CK_COHORT_INIT 3 , +.Xr CK_COHORT_LOCK 3 , .Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , .Pp Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_TRYLOCK_PROTOTYPE b/doc/CK_COHORT_TRYLOCK_PROTOTYPE index 62f3e68..6a038e5 100644 --- a/doc/CK_COHORT_TRYLOCK_PROTOTYPE +++ b/doc/CK_COHORT_TRYLOCK_PROTOTYPE @@ -34,13 +34,13 @@ Concurrency Kit (libck, \-lck) .Sh SYNOPSIS .In ck_cohort.h .Fn CK_COHORT_TRYLOCK_PROTOTYPE "COHORT_NAME cohort_name" "LOCK_FXN global_lock_method" \ -"LOCK_FXN global_unlock_method" "TRYLOCK_FXN global_trylock_method" \ -"LOCK_FXN local_lock_method" "LOCK_FXN local_unlock_method" "TRYLOCK_FXN local_trylock_method" +"LOCK_FXN global_unlock_method" "BOOL_LOCK_FXN global_locked_method" \ +"BOOL_LOCK_FXN global_trylock_method" "LOCK_FXN local_lock_method" \ +"LOCK_FXN local_unlock_method" "BOOL_LOCK_FXN local_locked_method" "BOOL_LOCK_FXN local_trylock_method" .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. -They must use CK_COHORT_TRYLOCK_PROTOTYPE if they want their cohort type to have support +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 @@ -53,6 +53,9 @@ of the other CK_COHORT macros. .Fa global_unlock_method : The method that should be called to relinquish the global lock .br +.Fa global_locked_method +: This method should return true iff the global lock is acquired by a thread. +.br .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. @@ -63,6 +66,9 @@ It should not block and return true iff the lock was successfully acquired. .Fa local_unlock_method : The method that should be called to relinquish the local lock .br +.Fa global_locked_method +: This method should return true iff the global lock is acquired by a thread. +.br .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. @@ -78,5 +84,7 @@ Instances of the defined cohort type can be declared as: .Xr CK_COHORT_INIT 3 , .Xr CK_COHORT_LOCK 3 , .Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , +.Xr CK_COHORT_TRYLOCK 3 , .Pp Additional information available at http://concurrencykit.org/ diff --git a/doc/CK_COHORT_UNLOCK b/doc/CK_COHORT_UNLOCK index 7dca173..ffecaa4 100644 --- a/doc/CK_COHORT_UNLOCK +++ b/doc/CK_COHORT_UNLOCK @@ -55,6 +55,7 @@ will be passed to the function specified by .Xr CK_COHORT_INITIALIZER 3 , .Xr CK_COHORT_INIT 3 , .Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_LOCKED 3 , .Xr CK_COHORT_TRYLOCK 3 , .Pp Additional information available at http://concurrencykit.org/ diff --git a/doc/ck_cohort b/doc/ck_cohort index 91f6c1e..a053385 100644 --- a/doc/ck_cohort +++ b/doc/ck_cohort @@ -36,8 +36,10 @@ Concurrency Kit (libck, \-lck) .Fn CK_COHORT_PROTOTYPE "COHORT_NAME cohort_name" "LOCK_FXN global_lock_method" \ "LOCK_FXN global_unlock_method" "LOCK_FXN local_lock_method" "LOCK_FXN local_unlock_method" .Fn CK_COHORT_TRYLOCK_PROTOTYPE "COHORT_NAME cohort_name" \ -"LOCK_FXN global_lock_method" "LOCK_FXN global_unlock_method" "TRYLOCK_FXN global_trylock_method" \ -"LOCK_FXN local_lock_method" "LOCK_FXN local_unlock_method" "TRYLOCK_FXN local_trylock_method" +"LOCK_FXN global_lock_method" "LOCK_FXN global_unlock_method" \ +"BOOL_LOCK_FXN global_locked_method" BOOL_LOCK_FXN global_trylock_method" \ +"LOCK_FXN local_lock_method" "LOCK_FXN local_unlock_method" \ +"BOOL_LOCK_FXN local_locked_method" BOOL_LOCK_FXN local_trylock_method" .Fn CK_COHORT_INSTANCE "COHORT_NAME cohort_name" .Fn CK_COHORT_INIT "COHORT_NAME cohort_name" "ck_cohort *cohort" \ "void *global_lock" "void *local_lock" "unsigned int pass_limit" @@ -50,7 +52,7 @@ Where LOCK_FXN refers to a method with the signature .br void(void *lock, void *context) .br -and TRYLOCK_FXN refers to a method with the signature +BOOL_LOCK_FXN refers to a method with the signature .br bool(void *lock, void *context) .Pp @@ -59,9 +61,9 @@ The 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 -.Xr CK_COHORT_LOCK 3 -, -.Xr CK_COHORT_UNLOCK 3 +.Xr CK_COHORT_LOCK 3 , +.Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , and .Xr CK_COHORT_TRYLOCK 3 . @@ -94,7 +96,7 @@ man pages for more details. #include /* - * Create lock/unlock methods with signatures that match + * Create cohort methods with signatures that match * the required signature */ static void @@ -113,13 +115,20 @@ ck_spinlock_unlock_with_context(ck_spinlock_t *lock, void *context) return; } +static bool +ck_spinlock_locked_with_context(ck_spinlock_t *lock, void *context) +{ + (void)context; + return ck_spinlock_locked(lock); +} + /* * define a cohort type named "test_cohort" that will use * the above methods for both its global and local locks */ CK_COHORT_PROTOTYPE(test_cohort, - ck_spinlock_lock_with_context, ck_spinlock_unlock_with_context, - ck_spinlock_lock_with_context, ck_spinlock_unlock_with_context) + ck_spinlock_lock_with_context, ck_spinlock_unlock_with_context, ck_spinlock_locked_with_context + ck_spinlock_lock_with_context, ck_spinlock_unlock_with_context, ck_spinlock_locked_with_context) static ck_spinlock_t global_lock = CK_SPINLOCK_INITIALIZER; static unsigned int ready; @@ -197,6 +206,7 @@ main(void) .Xr CK_COHORT_INIT 3 , .Xr CK_COHORT_LOCK 3 , .Xr CK_COHORT_UNLOCK 3 , +.Xr CK_COHORT_LOCKED 3 , .Xr CK_COHORT_TRYLOCK 3 , .Pp Additional information available at http://concurrencykit.org/