DragonFly On-Line Manual Pages
ck_elide(3) DragonFly Library Functions Manual ck_elide(3)
NAME
CK_ELIDE_PROTOTYPE, CK_ELIDE_LOCK_ADAPTIVE, CK_ELIDE_UNLOCK_ADAPTIVE,
CK_ELIDE_LOCK, CK_ELIDE_UNLOCK, CK_ELIDE_TRYLOCK_PROTOTYPE,
CK_ELIDE_TRYLOCK - lock elision wrappers
LIBRARY
Concurrency Kit (libck, -lck)
SYNOPSIS
#include <ck_elide.h>
ck_elide_stat_t stat = CK_ELIDE_STAT_INITIALIZER;
void
ck_elide_stat_init(ck_elide_stat_t *);
struct ck_elide_config config = CK_ELIDE_CONFIG_DEFAULT_INITIALIZER;
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;
};
CK_ELIDE_PROTOTYPE(NAME, TYPE, LOCK_PREDICATE, LOCK_FUNCTION,
UNLOCK_PREDICATE, UNLOCK_FUNCTION);
CK_ELIDE_LOCK_ADAPTIVE(NAME, ck_elide_stat_t *, struct ck_elide_config *,
TYPE *);
CK_ELIDE_UNLOCK_ADAPTIVE(NAME, ck_elide_stat_t *, TYPE *);
CK_ELIDE_LOCK(NAME, TYPE *);
CK_ELIDE_UNLOCK(NAME, TYPE *);
CK_ELIDE_TRYLOCK_PROTOTYPE(NAME, TYPE, LOCK_PREDICATE, TRYLOCK_FUNCTION);
DESCRIPTION
These macros implement lock elision wrappers for a user-specified single-
argument lock interface. The wrappers will attempt to elide lock
acquisition, allowing concurrent execution of critical sections that do
not issue conflicting memory 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.
CK_ELIDE_LOCK(), CK_ELIDE_UNLOCK(), CK_ELIDE_LOCK_ADAPTIVE(), and
CK_ELIDE_UNLOCK_ADAPTIVE() macros require a previous CK_ELIDE_PROTOTYPE()
with the same NAME. Elision is attempted if the LOCK_PREDICATE function
returns false. If LOCK_PREDICATE returns true then elision is aborted and
LOCK_FUNCTION is executed instead. If any threads are in an elided
critical section, LOCK_FUNCTION must force them to rollback through a
conflicting memory operation. The UNLOCK_PREDICATE function must return
true if the lock is acquired by the caller, meaning that the lock was not
successfully elided. If UNLOCK_PREDICATE returns true, then the
UNLOCK_FUNCTION is executed. If RTM is unsupported (no CK_F_PR_RTM macro)
then CK_ELIDE_LOCK() and CK_ELIDE_LOCK_ADAPTIVE() will immediately call
LOCK_FUNCTION(). CK_ELIDE_UNLOCK() and CK_ELIDE_UNLOCK_ADAPTIVE() will
immediately call UNLOCK_FUNCTION().
CK_ELIDE_TRYLOCK() requires a previous CK_ELIDE_TRYLOCK_PROTOTYPE() with
the same name. Elision is attempted if the LOCK_PREDICATE function
returns false. If LOCK_PREDICATE returns true or if elision fails then
the operation is aborted. If RTM is unsupported (no CK_F_PR_RTM macro)
then CK_ELIDE_TRYLOCK() will immediately call TRYLOCK_FUNCTION().
CK_ELIDE_LOCK_ADAPTIVE() and 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 CK_ELIDE_LOCK_ADAPTIVE(). A
thread-local ck_elide_stat structure must be passed to both
CK_ELIDE_LOCK_ADAPTIVE() and 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. It is safe to mix adaptive calls with best-effort calls.
Both ck_spinlock.h and ck_rwlock.h define ck_elide wrappers under the
ck_spinlock and ck_rwlock namespace, respectively.
EXAMPLES
This example utilizes built-in lock elision facilities in ck_rwlock and
ck_spinlock.
#include <ck_rwlock.h>
#include <ck_spinlock.h>
static ck_rwlock_t rw = CK_RWLOCK_INITIALIZER;
static struct ck_elide_config rw_config =
CK_ELIDE_CONFIG_DEFAULT_INITIALIZER;
static __thread ck_elide_stat_t rw_stat =
CK_ELIDE_STAT_INITIALIZER;
static ck_spinlock_t spinlock = CK_SPINLOCK_INITIALIZER;
static struct ck_elide_config spinlock_config =
CK_ELIDE_CONFIG_DEFAULT_INITIALIZER;
static __thread ck_elide_stat_t spinlock_stat =
CK_ELIDE_STAT_INITIALIZER;
void
function(void)
{
/* Lock-unlock write-side lock in weak best-effort manner. */
CK_ELIDE_LOCK(ck_rwlock_write, &rw);
CK_ELIDE_UNLOCK(ck_rwlock_write, &rw);
/* Attempt to acquire the write-side lock. */
if (CK_ELIDE_TRYLOCK(ck_rwlock_write, &rw) == true)
CK_ELIDE_UNLOCK(ck_rwlock_write, &rw);
/* Lock-unlock read-side lock in weak best-effort manner. */
CK_ELIDE_LOCK(ck_rwlock_read, &rw);
CK_ELIDE_UNLOCK(ck_rwlock_read, &rw);
/* Attempt to acquire the read-side lock. */
if (CK_ELIDE_TRYLOCK(ck_rwlock_read, &rw) == true)
CK_ELIDE_UNLOCK(ck_rwlock_read, &rw);
/* Lock-unlock write-side lock in an adaptive manner. */
CK_ELIDE_LOCK_ADAPTIVE(ck_rwlock_write, &rw_stat,
&rw_config, &rw);
CK_ELIDE_UNLOCK_ADAPTIVE(ck_rwlock_write, &rw_stat,
&rw_config, &rw);
/* Lock-unlock read-side lock in an adaptive manner. */
CK_ELIDE_LOCK_ADAPTIVE(ck_rwlock_read, &rw_stat,
&rw_config, &rw);
CK_ELIDE_UNLOCK_ADAPTIVE(ck_rwlock_read, &rw_stat,
&rw_config, &rw);
/* Lock-unlock spinlock in weak best-effort manner. */
CK_ELIDE_LOCK(ck_spinlock, &spinlock);
CK_ELIDE_UNLOCK(ck_spinlock, &spinlock);
/* Attempt to acquire the lock. */
if (CK_ELIDE_TRYLOCK(ck_spinlock, &lock) == true)
CK_ELIDE_UNLOCK(ck_spinlock, &spinlock);
/* Lock-unlock spinlock in an adaptive manner. */
CK_ELIDE_LOCK_ADAPTIVE(ck_spinlock, &spinlock_stat,
&spinlock_config, &spinlock);
CK_ELIDE_UNLOCK_ADAPTIVE(ck_spinlock, &spinlock_stat,
&spinlock_config, &spinlock);
}
In this example, user-defined locking functions are provided an elision
implementation.
/* Assume lock_t has been previously defined. */
#include <ck_elide.h>
/*
* This function returns true if the lock is unavailable at the time
* it was called or false if the lock is available.
*/
bool is_locked(lock_t *);
/*
* This function acquires the supplied lock.
*/
void lock(lock_t *);
/*
* This function releases the lock.
*/
void unlock(lock_t *);
CK_ELIDE_PROTOTYPE(my_lock, lock_t, is_locked, lock, is_locked, unlock)
static lock_t lock;
void
function(void)
{
CK_ELIDE_LOCK(my_lock, &lock);
CK_ELIDE_UNLOCK(my_lock, &lock);
}
SEE ALSO
ck_rwlock(3), ck_spinlock(3)
Ravi Rajwar and James R. Goodman. 2001. Speculative lock elision:
enabling highly concurrent multithreaded execution. In Proceedings of the
34th annual ACM/IEEE international symposium on Microarchitecture (MICRO
34). IEEE Computer Society, Washington, DC, USA, 294-305.
Additional information available at
http://en.wikipedia.org/wiki/Transactional_Synchronization_Extensions and
http://concurrencykit.org/
July 13, 2013.