c65780e35887d93915849d7af4cff3e5bcc28b98
[urcu.git] / urcu / wfcqueue.h
1 #ifndef _URCU_WFCQUEUE_H
2 #define _URCU_WFCQUEUE_H
3
4 /*
5 * urcu/wfcqueue.h
6 *
7 * Userspace RCU library - Concurrent Queue with Wait-Free Enqueue/Blocking Dequeue
8 *
9 * Copyright 2010-2012 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
10 * Copyright 2011-2012 - Lai Jiangshan <laijs@cn.fujitsu.com>
11 *
12 * This library is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU Lesser General Public
14 * License as published by the Free Software Foundation; either
15 * version 2.1 of the License, or (at your option) any later version.
16 *
17 * This library is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * Lesser General Public License for more details.
21 *
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with this library; if not, write to the Free Software
24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
25 */
26
27 #include <pthread.h>
28 #include <assert.h>
29 #include <stdbool.h>
30 #include <urcu/compiler.h>
31 #include <urcu/arch.h>
32
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36
37 /*
38 * Concurrent queue with wait-free enqueue/blocking dequeue.
39 *
40 * This queue has been designed and implemented collaboratively by
41 * Mathieu Desnoyers and Lai Jiangshan. Inspired from
42 * half-wait-free/half-blocking queue implementation done by Paul E.
43 * McKenney.
44 */
45
46 #define CDS_WFCQ_WOULDBLOCK ((struct cds_wfcq_node *) -1UL)
47
48 enum cds_wfcq_ret {
49 CDS_WFCQ_RET_WOULDBLOCK = -1,
50 CDS_WFCQ_RET_DEST_EMPTY = 0,
51 CDS_WFCQ_RET_DEST_NON_EMPTY = 1,
52 CDS_WFCQ_RET_SRC_EMPTY = 2,
53 };
54
55 enum cds_wfcq_state {
56 CDS_WFCQ_STATE_LAST = (1U << 0),
57 };
58
59 struct cds_wfcq_node {
60 struct cds_wfcq_node *next;
61 };
62
63 /*
64 * Do not put head and tail on the same cache-line if concurrent
65 * enqueue/dequeue are expected from many CPUs. This eliminates
66 * false-sharing between enqueue and dequeue.
67 */
68 struct __cds_wfcq_head {
69 struct cds_wfcq_node node;
70 };
71
72 struct cds_wfcq_head {
73 struct cds_wfcq_node node;
74 pthread_mutex_t lock;
75 };
76
77 #ifndef __cplusplus
78 /*
79 * The transparent union allows calling functions that work on both
80 * struct cds_wfcq_head and struct __cds_wfcq_head on any of those two
81 * types.
82 */
83 typedef union {
84 struct __cds_wfcq_head *_h;
85 struct cds_wfcq_head *h;
86 } __attribute__((__transparent_union__)) cds_wfcq_head_ptr_t;
87
88 /*
89 * This static inline is only present for compatibility with C++. It is
90 * effect-less in C.
91 */
92 static inline struct __cds_wfcq_head *__cds_wfcq_head_cast(struct __cds_wfcq_head *head)
93 {
94 return head;
95 }
96
97 /*
98 * This static inline is only present for compatibility with C++. It is
99 * effect-less in C.
100 */
101 static inline struct cds_wfcq_head *cds_wfcq_head_cast(struct cds_wfcq_head *head)
102 {
103 return head;
104 }
105 #else /* #ifndef __cplusplus */
106
107 /* C++ ignores transparent union. */
108 typedef union {
109 struct __cds_wfcq_head *_h;
110 struct cds_wfcq_head *h;
111 } cds_wfcq_head_ptr_t;
112
113 /* C++ ignores transparent union. Requires an explicit conversion. */
114 static inline cds_wfcq_head_ptr_t __cds_wfcq_head_cast(struct __cds_wfcq_head *head)
115 {
116 cds_wfcq_head_ptr_t ret = { ._h = head };
117 return ret;
118 }
119 /* C++ ignores transparent union. Requires an explicit conversion. */
120 static inline cds_wfcq_head_ptr_t cds_wfcq_head_cast(struct cds_wfcq_head *head)
121 {
122 cds_wfcq_head_ptr_t ret = { .h = head };
123 return ret;
124 }
125 #endif /* #else #ifndef __cplusplus */
126
127 struct cds_wfcq_tail {
128 struct cds_wfcq_node *p;
129 };
130
131 #ifdef _LGPL_SOURCE
132
133 #include <urcu/static/wfcqueue.h>
134
135 #define cds_wfcq_node_init _cds_wfcq_node_init
136 #define cds_wfcq_init _cds_wfcq_init
137 #define __cds_wfcq_init ___cds_wfcq_init
138 #define cds_wfcq_empty _cds_wfcq_empty
139 #define cds_wfcq_enqueue _cds_wfcq_enqueue
140
141 /* Dequeue locking */
142 #define cds_wfcq_dequeue_lock _cds_wfcq_dequeue_lock
143 #define cds_wfcq_dequeue_unlock _cds_wfcq_dequeue_unlock
144
145 /* Locking performed within cds_wfcq calls. */
146 #define cds_wfcq_dequeue_blocking _cds_wfcq_dequeue_blocking
147 #define cds_wfcq_dequeue_with_state_blocking \
148 _cds_wfcq_dequeue_with_state_blocking
149 #define cds_wfcq_splice_blocking _cds_wfcq_splice_blocking
150 #define cds_wfcq_first_blocking _cds_wfcq_first_blocking
151 #define cds_wfcq_next_blocking _cds_wfcq_next_blocking
152
153 /* Locking ensured by caller by holding cds_wfcq_dequeue_lock() */
154 #define __cds_wfcq_dequeue_blocking ___cds_wfcq_dequeue_blocking
155 #define __cds_wfcq_dequeue_with_state_blocking \
156 ___cds_wfcq_dequeue_with_state_blocking
157 #define __cds_wfcq_splice_blocking ___cds_wfcq_splice_blocking
158 #define __cds_wfcq_first_blocking ___cds_wfcq_first_blocking
159 #define __cds_wfcq_next_blocking ___cds_wfcq_next_blocking
160
161 /*
162 * Locking ensured by caller by holding cds_wfcq_dequeue_lock().
163 * Non-blocking: deque, first, next return CDS_WFCQ_WOULDBLOCK if they
164 * need to block. splice returns nonzero if it needs to block.
165 */
166 #define __cds_wfcq_dequeue_nonblocking ___cds_wfcq_dequeue_nonblocking
167 #define __cds_wfcq_dequeue_with_state_nonblocking \
168 ___cds_wfcq_dequeue_with_state_nonblocking
169 #define __cds_wfcq_splice_nonblocking ___cds_wfcq_splice_nonblocking
170 #define __cds_wfcq_first_nonblocking ___cds_wfcq_first_nonblocking
171 #define __cds_wfcq_next_nonblocking ___cds_wfcq_next_nonblocking
172
173 #else /* !_LGPL_SOURCE */
174
175 /*
176 * Mutual exclusion of cds_wfcq_* / __cds_wfcq_* API
177 *
178 * Synchronization table:
179 *
180 * External synchronization techniques described in the API below is
181 * required between pairs marked with "X". No external synchronization
182 * required between pairs marked with "-".
183 *
184 * Legend:
185 * [1] cds_wfcq_enqueue
186 * [2] __cds_wfcq_splice (destination queue)
187 * [3] __cds_wfcq_dequeue
188 * [4] __cds_wfcq_splice (source queue)
189 * [5] __cds_wfcq_first
190 * [6] __cds_wfcq_next
191 *
192 * [1] [2] [3] [4] [5] [6]
193 * [1] - - - - - -
194 * [2] - - - - - -
195 * [3] - - X X X X
196 * [4] - - X - X X
197 * [5] - - X X - -
198 * [6] - - X X - -
199 *
200 * Mutual exclusion can be ensured by holding cds_wfcq_dequeue_lock().
201 *
202 * For convenience, cds_wfcq_dequeue_blocking() and
203 * cds_wfcq_splice_blocking() hold the dequeue lock.
204 *
205 * Besides locking, mutual exclusion of dequeue, splice and iteration
206 * can be ensured by performing all of those operations from a single
207 * thread, without requiring any lock.
208 */
209
210 /*
211 * cds_wfcq_node_init: initialize wait-free queue node.
212 */
213 extern void cds_wfcq_node_init(struct cds_wfcq_node *node);
214
215 /*
216 * cds_wfcq_init: initialize wait-free queue.
217 */
218 extern void cds_wfcq_init(struct cds_wfcq_head *head,
219 struct cds_wfcq_tail *tail);
220
221 /*
222 * __cds_wfcq_init: initialize wait-free queue.
223 */
224 extern void __cds_wfcq_init(struct __cds_wfcq_head *head,
225 struct cds_wfcq_tail *tail);
226
227 /*
228 * cds_wfcq_empty: return whether wait-free queue is empty.
229 *
230 * No memory barrier is issued. No mutual exclusion is required.
231 */
232 extern bool cds_wfcq_empty(cds_wfcq_head_ptr_t head,
233 struct cds_wfcq_tail *tail);
234
235 /*
236 * cds_wfcq_dequeue_lock: take the dequeue mutual exclusion lock.
237 */
238 extern void cds_wfcq_dequeue_lock(struct cds_wfcq_head *head,
239 struct cds_wfcq_tail *tail);
240
241 /*
242 * cds_wfcq_dequeue_unlock: release the dequeue mutual exclusion lock.
243 */
244 extern void cds_wfcq_dequeue_unlock(struct cds_wfcq_head *head,
245 struct cds_wfcq_tail *tail);
246
247 /*
248 * cds_wfcq_enqueue: enqueue a node into a wait-free queue.
249 *
250 * Issues a full memory barrier before enqueue. No mutual exclusion is
251 * required.
252 *
253 * Returns false if the queue was empty prior to adding the node.
254 * Returns true otherwise.
255 */
256 extern bool cds_wfcq_enqueue(cds_wfcq_head_ptr_t head,
257 struct cds_wfcq_tail *tail,
258 struct cds_wfcq_node *node);
259
260 /*
261 * cds_wfcq_dequeue_blocking: dequeue a node from a wait-free queue.
262 *
263 * Content written into the node before enqueue is guaranteed to be
264 * consistent, but no other memory ordering is ensured.
265 * It is valid to reuse and free a dequeued node immediately.
266 * Mutual exclusion with cds_wfcq_dequeue_blocking and dequeue lock is
267 * ensured.
268 */
269 extern struct cds_wfcq_node *cds_wfcq_dequeue_blocking(
270 struct cds_wfcq_head *head,
271 struct cds_wfcq_tail *tail);
272
273 /*
274 * cds_wfcq_dequeue_with_state_blocking: dequeue with state.
275 *
276 * Same as cds_wfcq_dequeue_blocking, but saves whether dequeueing the
277 * last node of the queue into state (CDS_WFCQ_STATE_LAST).
278 */
279 extern struct cds_wfcq_node *cds_wfcq_dequeue_with_state_blocking(
280 struct cds_wfcq_head *head,
281 struct cds_wfcq_tail *tail,
282 int *state);
283
284 /*
285 * cds_wfcq_splice_blocking: enqueue all src_q nodes at the end of dest_q.
286 *
287 * Dequeue all nodes from src_q.
288 * dest_q must be already initialized.
289 * Content written into the node before enqueue is guaranteed to be
290 * consistent, but no other memory ordering is ensured.
291 * Mutual exclusion with cds_wfcq_dequeue_blocking and dequeue lock is
292 * ensured.
293 *
294 * Returns enum cds_wfcq_ret which indicates the state of the src or
295 * dest queue.
296 */
297 extern enum cds_wfcq_ret cds_wfcq_splice_blocking(
298 struct cds_wfcq_head *dest_q_head,
299 struct cds_wfcq_tail *dest_q_tail,
300 struct cds_wfcq_head *src_q_head,
301 struct cds_wfcq_tail *src_q_tail);
302
303 /*
304 * __cds_wfcq_dequeue_blocking: dequeue a node from a wait-free queue.
305 *
306 * Content written into the node before enqueue is guaranteed to be
307 * consistent, but no other memory ordering is ensured.
308 * It is valid to reuse and free a dequeued node immediately.
309 * Dequeue/splice/iteration mutual exclusion should be ensured by the
310 * caller.
311 */
312 extern struct cds_wfcq_node *__cds_wfcq_dequeue_blocking(
313 cds_wfcq_head_ptr_t head,
314 struct cds_wfcq_tail *tail);
315
316 /*
317 * __cds_wfcq_dequeue_with_state_blocking: dequeue with state.
318 *
319 * Same as __cds_wfcq_dequeue_blocking, but saves whether dequeueing the
320 * last node of the queue into state (CDS_WFCQ_STATE_LAST).
321 */
322 extern struct cds_wfcq_node *__cds_wfcq_dequeue_with_state_blocking(
323 cds_wfcq_head_ptr_t head,
324 struct cds_wfcq_tail *tail,
325 int *state);
326
327 /*
328 * __cds_wfcq_dequeue_nonblocking: dequeue a node from a wait-free queue.
329 *
330 * Same as __cds_wfcq_dequeue_blocking, but returns CDS_WFCQ_WOULDBLOCK
331 * if it needs to block.
332 */
333 extern struct cds_wfcq_node *__cds_wfcq_dequeue_nonblocking(
334 cds_wfcq_head_ptr_t head,
335 struct cds_wfcq_tail *tail);
336
337 /*
338 * __cds_wfcq_dequeue_with_state_blocking: dequeue with state.
339 *
340 * Same as __cds_wfcq_dequeue_nonblocking, but saves whether dequeueing
341 * the last node of the queue into state (CDS_WFCQ_STATE_LAST).
342 */
343 extern struct cds_wfcq_node *__cds_wfcq_dequeue_with_state_nonblocking(
344 cds_wfcq_head_ptr_t head,
345 struct cds_wfcq_tail *tail,
346 int *state);
347
348 /*
349 * __cds_wfcq_splice_blocking: enqueue all src_q nodes at the end of dest_q.
350 *
351 * Dequeue all nodes from src_q.
352 * dest_q must be already initialized.
353 * Mutual exclusion for src_q should be ensured by the caller as
354 * specified in the "Synchronisation table".
355 * Returns enum cds_wfcq_ret which indicates the state of the src or
356 * dest queue. Never returns CDS_WFCQ_RET_WOULDBLOCK.
357 */
358 extern enum cds_wfcq_ret __cds_wfcq_splice_blocking(
359 cds_wfcq_head_ptr_t dest_q_head,
360 struct cds_wfcq_tail *dest_q_tail,
361 cds_wfcq_head_ptr_t src_q_head,
362 struct cds_wfcq_tail *src_q_tail);
363
364 /*
365 * __cds_wfcq_splice_nonblocking: enqueue all src_q nodes at the end of dest_q.
366 *
367 * Same as __cds_wfcq_splice_blocking, but returns
368 * CDS_WFCQ_RET_WOULDBLOCK if it needs to block.
369 */
370 extern enum cds_wfcq_ret __cds_wfcq_splice_nonblocking(
371 cds_wfcq_head_ptr_t dest_q_head,
372 struct cds_wfcq_tail *dest_q_tail,
373 cds_wfcq_head_ptr_t src_q_head,
374 struct cds_wfcq_tail *src_q_tail);
375
376 /*
377 * __cds_wfcq_first_blocking: get first node of a queue, without dequeuing.
378 *
379 * Content written into the node before enqueue is guaranteed to be
380 * consistent, but no other memory ordering is ensured.
381 * Dequeue/splice/iteration mutual exclusion should be ensured by the
382 * caller.
383 *
384 * Used by for-like iteration macros:
385 * __cds_wfcq_for_each_blocking()
386 * __cds_wfcq_for_each_blocking_safe()
387 *
388 * Returns NULL if queue is empty, first node otherwise.
389 */
390 extern struct cds_wfcq_node *__cds_wfcq_first_blocking(
391 cds_wfcq_head_ptr_t head,
392 struct cds_wfcq_tail *tail);
393
394 /*
395 * __cds_wfcq_first_nonblocking: get first node of a queue, without dequeuing.
396 *
397 * Same as __cds_wfcq_first_blocking, but returns CDS_WFCQ_WOULDBLOCK if
398 * it needs to block.
399 */
400 extern struct cds_wfcq_node *__cds_wfcq_first_nonblocking(
401 cds_wfcq_head_ptr_t head,
402 struct cds_wfcq_tail *tail);
403
404 /*
405 * __cds_wfcq_next_blocking: get next node of a queue, without dequeuing.
406 *
407 * Content written into the node before enqueue is guaranteed to be
408 * consistent, but no other memory ordering is ensured.
409 * Dequeue/splice/iteration mutual exclusion should be ensured by the
410 * caller.
411 *
412 * Used by for-like iteration macros:
413 * __cds_wfcq_for_each_blocking()
414 * __cds_wfcq_for_each_blocking_safe()
415 *
416 * Returns NULL if reached end of queue, non-NULL next queue node
417 * otherwise.
418 */
419 extern struct cds_wfcq_node *__cds_wfcq_next_blocking(
420 cds_wfcq_head_ptr_t head,
421 struct cds_wfcq_tail *tail,
422 struct cds_wfcq_node *node);
423
424 /*
425 * __cds_wfcq_next_blocking: get next node of a queue, without dequeuing.
426 *
427 * Same as __cds_wfcq_next_blocking, but returns CDS_WFCQ_WOULDBLOCK if
428 * it needs to block.
429 */
430 extern struct cds_wfcq_node *__cds_wfcq_next_nonblocking(
431 cds_wfcq_head_ptr_t head,
432 struct cds_wfcq_tail *tail,
433 struct cds_wfcq_node *node);
434
435 #endif /* !_LGPL_SOURCE */
436
437 /*
438 * __cds_wfcq_for_each_blocking: Iterate over all nodes in a queue,
439 * without dequeuing them.
440 * @head: head of the queue (struct cds_wfcq_head or __cds_wfcq_head pointer).
441 * @tail: tail of the queue (struct cds_wfcq_tail pointer).
442 * @node: iterator on the queue (struct cds_wfcq_node pointer).
443 *
444 * Content written into each node before enqueue is guaranteed to be
445 * consistent, but no other memory ordering is ensured.
446 * Dequeue/splice/iteration mutual exclusion should be ensured by the
447 * caller.
448 */
449 #define __cds_wfcq_for_each_blocking(head, tail, node) \
450 for (node = __cds_wfcq_first_blocking(head, tail); \
451 node != NULL; \
452 node = __cds_wfcq_next_blocking(head, tail, node))
453
454 /*
455 * __cds_wfcq_for_each_blocking_safe: Iterate over all nodes in a queue,
456 * without dequeuing them. Safe against deletion.
457 * @head: head of the queue (struct cds_wfcq_head or __cds_wfcq_head pointer).
458 * @tail: tail of the queue (struct cds_wfcq_tail pointer).
459 * @node: iterator on the queue (struct cds_wfcq_node pointer).
460 * @n: struct cds_wfcq_node pointer holding the next pointer (used
461 * internally).
462 *
463 * Content written into each node before enqueue is guaranteed to be
464 * consistent, but no other memory ordering is ensured.
465 * Dequeue/splice/iteration mutual exclusion should be ensured by the
466 * caller.
467 */
468 #define __cds_wfcq_for_each_blocking_safe(head, tail, node, n) \
469 for (node = __cds_wfcq_first_blocking(head, tail), \
470 n = (node ? __cds_wfcq_next_blocking(head, tail, node) : NULL); \
471 node != NULL; \
472 node = n, n = (node ? __cds_wfcq_next_blocking(head, tail, node) : NULL))
473
474 #ifdef __cplusplus
475 }
476 #endif
477
478 #endif /* _URCU_WFCQUEUE_H */
This page took 0.056099 seconds and 3 git commands to generate.