ck_elide(3)

1ck_elide(3)              BSD Library Functions Manual              ck_elide(3)
2

NAME

4     CK_ELIDE_PROTOTYPE, CK_ELIDE_LOCK_ADAPTIVE, CK_ELIDE_UNLOCK_ADAPTIVE,
5     CK_ELIDE_LOCK, CK_ELIDE_UNLOCK, CK_ELIDE_TRYLOCK_PROTOTYPE,
6     CK_ELIDE_TRYLOCK — lock elision wrappers
7

LIBRARY

9     Concurrency Kit (libck, -lck)
10

SYNOPSIS

12     #include <ck_elide.h>
13
14     ck_elide_stat_t stat = CK_ELIDE_STAT_INITIALIZER;
15
16     void
17     ck_elide_stat_init(ck_elide_stat_t *);
18
19     struct ck_elide_config config = CK_ELIDE_CONFIG_DEFAULT_INITIALIZER;
20
21     struct ck_elide_config {
22             unsigned short skip_busy;
23             short retry_busy;
24             unsigned short skip_other;
25             short retry_other;
26             unsigned short skip_conflict;
27             short retry_conflict;
28     };
29
30     CK_ELIDE_PROTOTYPE(NAME, TYPE, LOCK_PREDICATE, LOCK_FUNCTION,
31         UNLOCK_PREDICATE, UNLOCK_FUNCTION);
32
33     CK_ELIDE_LOCK_ADAPTIVE(NAME, ck_elide_stat_t *, struct ck_elide_config *,
34         TYPE *);
35
36     CK_ELIDE_UNLOCK_ADAPTIVE(NAME, ck_elide_stat_t *, TYPE *);
37
38     CK_ELIDE_LOCK(NAME, TYPE *);
39
40     CK_ELIDE_UNLOCK(NAME, TYPE *);
41
42     CK_ELIDE_TRYLOCK_PROTOTYPE(NAME, TYPE, LOCK_PREDICATE, TRYLOCK_FUNCTION);
43

DESCRIPTION

45     These macros implement lock elision wrappers for a user-specified single-
46     argument lock interface. The wrappers will attempt to elide lock acquisi‐
47     tion, allowing concurrent execution of critical sections that do not
48     issue conflicting memory operations. If any threads have successfully
49     elided a lock acquisition, conflicting memory operations will roll-back
50     any side-effects of the critical section and force every thread to retry
51     the lock acquisition regularly.
52
53     CK_ELIDE_LOCK(), CK_ELIDE_UNLOCK(), CK_ELIDE_LOCK_ADAPTIVE(), and
54     CK_ELIDE_UNLOCK_ADAPTIVE() macros require a previous CK_ELIDE_PROTOTYPE()
55     with the same NAME.  Elision is attempted if the LOCK_PREDICATE function
56     returns false. If LOCK_PREDICATE returns true then elision is aborted and
57     LOCK_FUNCTION is executed instead. If any threads are in an elided criti‐
58     cal section, LOCK_FUNCTION must force them to rollback through a con‐
59     flicting memory operation.  The UNLOCK_PREDICATE function must return
60     true if the lock is acquired by the caller, meaning that the lock was not
61     successfully elided. If UNLOCK_PREDICATE returns true, then the
62     UNLOCK_FUNCTION is executed. If RTM is unsupported (no CK_F_PR_RTM macro)
63     then CK_ELIDE_LOCK() and CK_ELIDE_LOCK_ADAPTIVE() will immediately call
64     LOCK_FUNCTION().  CK_ELIDE_UNLOCK() and CK_ELIDE_UNLOCK_ADAPTIVE() will
65     immediately call UNLOCK_FUNCTION().
66
67     CK_ELIDE_TRYLOCK() requires a previous CK_ELIDE_TRYLOCK_PROTOTYPE() with
68     the same name.  Elision is attempted if the LOCK_PREDICATE function
69     returns false. If LOCK_PREDICATE returns true or if elision fails then
70     the operation is aborted. If RTM is unsupported (no CK_F_PR_RTM macro)
71     then CK_ELIDE_TRYLOCK() will immediately call TRYLOCK_FUNCTION().
72
73     CK_ELIDE_LOCK_ADAPTIVE() and CK_ELIDE_UNLOCK_ADAPTIVE() will adapt the
74     elision behavior associated with lock operations according to the run-
75     time behavior of the program. This behavior is defined by the
76     ck_elide_config structure pointer passed to CK_ELIDE_LOCK_ADAPTIVE().  A
77     thread-local ck_elide_stat structure must be passed to both
78     CK_ELIDE_LOCK_ADAPTIVE() and CK_ELIDE_UNLOCK_ADAPTIVE().  This structure
79     is expected to be unique for different workloads, may not be re-used in
80     recursive acquisitions and must match the lifetime of the lock it is
81     associated with. It is safe to mix adaptive calls with best-effort calls.
82
83     Both ck_spinlock.h and ck_rwlock.h define ck_elide wrappers under the
84     ck_spinlock and ck_rwlock namespace, respectively.
85

EXAMPLES

87     This example utilizes built-in lock elision facilities in ck_rwlock and
88     ck_spinlock.
89
90           #include <ck_rwlock.h>
91           #include <ck_spinlock.h>
92
93           static ck_rwlock_t rw = CK_RWLOCK_INITIALIZER;
94           static struct ck_elide_config rw_config =
95               CK_ELIDE_CONFIG_DEFAULT_INITIALIZER;
96           static __thread ck_elide_stat_t rw_stat =
97               CK_ELIDE_STAT_INITIALIZER;
98
99           static ck_spinlock_t spinlock = CK_SPINLOCK_INITIALIZER;
100           static struct ck_elide_config spinlock_config =
101               CK_ELIDE_CONFIG_DEFAULT_INITIALIZER;
102           static __thread ck_elide_stat_t spinlock_stat =
103               CK_ELIDE_STAT_INITIALIZER;
104
105           void
106           function(void)
107           {
108
109                   /* Lock-unlock write-side lock in weak best-effort manner. */
110                   CK_ELIDE_LOCK(ck_rwlock_write, &rw);
111                   CK_ELIDE_UNLOCK(ck_rwlock_write, &rw);
112
113                   /* Attempt to acquire the write-side lock. */
114                   if (CK_ELIDE_TRYLOCK(ck_rwlock_write, &rw) == true)
115                           CK_ELIDE_UNLOCK(ck_rwlock_write, &rw);
116
117                   /* Lock-unlock read-side lock in weak best-effort manner. */
118                   CK_ELIDE_LOCK(ck_rwlock_read, &rw);
119                   CK_ELIDE_UNLOCK(ck_rwlock_read, &rw);
120
121                   /* Attempt to acquire the read-side lock. */
122                   if (CK_ELIDE_TRYLOCK(ck_rwlock_read, &rw) == true)
123                           CK_ELIDE_UNLOCK(ck_rwlock_read, &rw);
124
125                   /* Lock-unlock write-side lock in an adaptive manner. */
126                   CK_ELIDE_LOCK_ADAPTIVE(ck_rwlock_write, &rw_stat,
127                       &rw_config, &rw);
128                   CK_ELIDE_UNLOCK_ADAPTIVE(ck_rwlock_write, &rw_stat,
129                       &rw_config, &rw);
130
131                   /* Lock-unlock read-side lock in an adaptive manner. */
132                   CK_ELIDE_LOCK_ADAPTIVE(ck_rwlock_read, &rw_stat,
133                       &rw_config, &rw);
134                   CK_ELIDE_UNLOCK_ADAPTIVE(ck_rwlock_read, &rw_stat,
135                       &rw_config, &rw);
136
137                   /* Lock-unlock spinlock in weak best-effort manner. */
138                   CK_ELIDE_LOCK(ck_spinlock, &spinlock);
139                   CK_ELIDE_UNLOCK(ck_spinlock, &spinlock);
140
141                   /* Attempt to acquire the lock. */
142                   if (CK_ELIDE_TRYLOCK(ck_spinlock, &lock) == true)
143                           CK_ELIDE_UNLOCK(ck_spinlock, &spinlock);
144
145                   /* Lock-unlock spinlock in an adaptive manner. */
146                   CK_ELIDE_LOCK_ADAPTIVE(ck_spinlock, &spinlock_stat,
147                       &spinlock_config, &spinlock);
148                   CK_ELIDE_UNLOCK_ADAPTIVE(ck_spinlock, &spinlock_stat,
149                       &spinlock_config, &spinlock);
150           }
151
152     In this example, user-defined locking functions are provided an elision
153     implementation.
154
155           /* Assume lock_t has been previously defined. */
156           #include <ck_elide.h>
157
158           /*
159            * This function returns true if the lock is unavailable at the time
160            * it was called or false if the lock is available.
161            */
162           bool is_locked(lock_t *);
163
164           /*
165            * This function acquires the supplied lock.
166            */
167           void lock(lock_t *);
168
169           /*
170            * This function releases the lock.
171            */
172           void unlock(lock_t *);
173
174           CK_ELIDE_PROTOTYPE(my_lock, lock_t, is_locked, lock, is_locked, unlock)
175
176           static lock_t lock;
177
178           void
179           function(void)
180           {
181
182                   CK_ELIDE_LOCK(my_lock, &lock);
183                   CK_ELIDE_UNLOCK(my_lock, &lock);
184           }
185

NAME

LIBRARY

SYNOPSIS

DESCRIPTION

EXAMPLES

SEE ALSO