diff --git a/doc/ck_elide b/doc/ck_elide index 44c063f..e332d25 100644 --- a/doc/ck_elide +++ b/doc/ck_elide @@ -27,18 +27,37 @@ .Dd July 13, 2013. .Dt ck_elide 3 .Sh NAME -.Nm CK_ELIDE_PROTOTYPE CK_ELIDE_LOCK CK_ELIDE_UNLOCK CK_ELIDE_TRYLOCK_PROTOTYPE CK_ELIDE_TRYLOCK +.Nm CK_ELIDE_PROTOTYPE CK_ELIDE_LOCK_ADAPTIVE CK_ELIDE_UNLOCK_ADAPTIVE CK_ELIDE_LOCK CK_ELIDE_UNLOCK CK_ELIDE_TRYLOCK_PROTOTYPE CK_ELIDE_TRYLOCK .Nd lock elision wrappers .Sh LIBRARY Concurrency Kit (libck, \-lck) .Sh SYNOPSIS .In ck_elide.h -.Fn CK_ELIDE_PROTOTYPE "NAME" "TYPE" "LOCK_PREDICATE" "LOCK_FUNCTION" \ -"UNLOCK_PREDICATE" "UNLOCK_FUNCTION" +.Pp +.Dv ck_elide_stat_t stat = CK_ELIDE_STAT_INITIALIZER; +.Pp +.Ft void +.Fn ck_elide_stat_init "ck_elide_stat_t *" +.Pp +.Dv struct ck_elide_config config = CK_ELIDE_CONFIG_DEFAULT_INITIALIZER; +.Pp +.Bd -literal -offset +struct ck_elide_config { + unsigned short skip_busy; + short retry_busy; + unsigned short skip_other; + short retry_other; + unsigned short skip_conflict; + short retry_conflict; +}; +.Ed +.Pp +.Fn CK_ELIDE_PROTOTYPE "NAME" "TYPE" "LOCK_PREDICATE" "LOCK_FUNCTION" "UNLOCK_PREDICATE" "UNLOCK_FUNCTION" +.Fn CK_ELIDE_LOCK_ADAPTIVE "NAME" "ck_elide_stat_t *" "struct ck_elide_config *" "TYPE *" +.Fn CK_ELIDE_UNLOCK_ADAPTIVE "NAME" "ck_elide_stat_t *" "TYPE *" .Fn CK_ELIDE_LOCK "NAME" "TYPE *" .Fn CK_ELIDE_UNLOCK "NAME" "TYPE *" .Fn CK_ELIDE_TRYLOCK_PROTOTYPE "NAME" "TYPE" "LOCK_PREDICATE" "TRYLOCK_FUNCTION" -.Fn CK_ELIDE_TRYLOCK "NAME" "TYPE *" .Sh DESCRIPTION These macros implement lock elision wrappers for a user-specified single-argument lock interface. The wrappers will attempt to elide lock acquisition, allowing @@ -47,12 +66,14 @@ operations. If any threads have successfully elided a lock acquisition, conflicting memory operations will roll-back any side-effects of the critical section and force every thread to retry the lock acquisition regularly. -.Fn CK_ELIDE_LOCK 3 +.Fn CK_ELIDE_LOCK , +.Fn CK_ELIDE_UNLOCK , +.Fn CK_ELIDE_LOCK_ADAPTIVE , and -.Fn CK_ELIDE_UNLOCK 3 -functions require +.Fn CK_ELIDE_UNLOCK_ADAPTIVE +macros require a previous -.Fn CK_ELIDE_PROTOTYPE 3 +.Fn CK_ELIDE_PROTOTYPE with the same .Fa NAME . Elision is attempted if the @@ -72,17 +93,20 @@ that the lock was not successfully elided. If returns true, then the .Fa UNLOCK_FUNCTION is executed. If RTM is unsupported (no CK_F_PR_RTM macro) then -.Fn CK_ELIDE_LOCK 3 +.Fn CK_ELIDE_LOCK +and +.Fn CK_ELIDE_LOCK_ADAPTIVE will immediately call -.Fn LOCK_FUNCTION +.Fn LOCK_FUNCTION . +.Fn CK_ELIDE_UNLOCK and -.Fn CK_ELIDE_UNLOCK 3 +.Fn CK_ELIDE_UNLOCK_ADAPTIVE will immediately call .Fn UNLOCK_FUNCTION . -.Fn CK_ELIDE_TRYLOCK 3 +.Fn CK_ELIDE_TRYLOCK requires a previous -.Fn CK_ELIDE_TRYLOCK_PROTOTYPE 3 +.Fn CK_ELIDE_TRYLOCK_PROTOTYPE with the same name. Elision is attempted if the .Fa LOCK_PREDICATE @@ -91,12 +115,27 @@ function returns false. If returns true or if elision fails then the operation is aborted. If RTM is unsupported (no CK_F_PR_RTM macro) then -.Fn CK_ELIDE_TRYLOCK 3 +.Fn CK_ELIDE_TRYLOCK will immediately call -.Fn TRYLOCK_FUNCTION 3 . +.Fn TRYLOCK_FUNCTION . -Both ck_spinlock.h and ck_rwlock.h both define -ck_elide wrappers under the ck_spinlock and ck_rwlock -namespace, respectively. +.Fn CK_ELIDE_LOCK_ADAPTIVE +and +.Fn CK_ELIDE_UNLOCK_ADAPTIVE +will adapt the elision behavior associated with lock operations +according to the run-time behavior of the program. This behavior +is defined by the ck_elide_config structure pointer passed to +.Fn CK_ELIDE_LOCK_ADAPTIVE . +A thread-local ck_elide_stat structure must be passed to both +.Fn CK_ELIDE_LOCK_ADAPTIVE +and +.Fn CK_ELIDE_UNLOCK_ADAPTIVE . +This structure is expected to be unique for different workloads, +may not be re-used in recursive acquisitions and must match the +lifetime of the lock it is associated with. + +Both ck_spinlock.h and ck_rwlock.h define ck_elide wrappers under +the ck_spinlock and ck_rwlock namespace, respectively. .Sh SEE ALSO Additional information available at http://en.wikipedia.org/wiki/Transactional_Synchronization_Extensions and http://concurrencykit.org/ +