1 // SPDX-FileCopyrightText: 2010-2012 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
2 // SPDX-FileCopyrightText: 2011-2012 Lai Jiangshan <laijs@cn.fujitsu.com>
4 // SPDX-License-Identifier: LGPL-2.1-or-later
6 #ifndef _URCU_WFCQUEUE_H
7 #define _URCU_WFCQUEUE_H
10 * Userspace RCU library - Concurrent Queue with Wait-Free Enqueue/Blocking Dequeue
15 #include <urcu/compiler.h>
16 #include <urcu/arch.h>
23 * Concurrent queue with wait-free enqueue/blocking dequeue.
25 * This queue has been designed and implemented collaboratively by
26 * Mathieu Desnoyers and Lai Jiangshan. Inspired from
27 * half-wait-free/half-blocking queue implementation done by Paul E.
31 #define CDS_WFCQ_WOULDBLOCK ((struct cds_wfcq_node *) -1UL)
34 CDS_WFCQ_RET_WOULDBLOCK
= -1,
35 CDS_WFCQ_RET_DEST_EMPTY
= 0,
36 CDS_WFCQ_RET_DEST_NON_EMPTY
= 1,
37 CDS_WFCQ_RET_SRC_EMPTY
= 2,
41 CDS_WFCQ_STATE_LAST
= (1U << 0),
44 struct cds_wfcq_node
{
45 struct cds_wfcq_node
*next
;
49 * Do not put head and tail on the same cache-line if concurrent
50 * enqueue/dequeue are expected from many CPUs. This eliminates
51 * false-sharing between enqueue and dequeue.
53 struct __cds_wfcq_head
{
54 struct cds_wfcq_node node
;
57 struct cds_wfcq_head
{
58 struct cds_wfcq_node node
;
63 * In C, the transparent union allows calling functions that work on both
64 * struct cds_wfcq_head and struct __cds_wfcq_head on any of those two
67 * In C++, implement static inline wrappers using function overloading
68 * to obtain an API similar to C.
70 * Avoid complaints from clang++ not knowing the transparent union
73 #if defined(__clang__)
74 #pragma clang diagnostic push
75 #pragma clang diagnostic ignored "-Wignored-attributes"
78 struct __cds_wfcq_head
*_h
;
79 struct cds_wfcq_head
*h
;
80 } __attribute__((__transparent_union__
)) cds_wfcq_head_ptr_t
;
83 const struct __cds_wfcq_head
*_h
;
84 const struct cds_wfcq_head
*h
;
85 } __attribute__((__transparent_union__
)) cds_wfcq_head_const_ptr_t
;
86 #if defined(__clang__)
87 #pragma clang diagnostic pop
92 * This static inline is only present for compatibility with C++. It is
95 static inline struct __cds_wfcq_head
*__cds_wfcq_head_cast(struct __cds_wfcq_head
*head
)
101 * This static inline is only present for compatibility with C++. It is
104 static inline struct cds_wfcq_head
*cds_wfcq_head_cast(struct cds_wfcq_head
*head
)
110 * This static inline is only present for compatibility with C++. It is
113 static inline const struct __cds_wfcq_head
*__cds_wfcq_head_const_cast(const struct __cds_wfcq_head
*head
)
119 * This static inline is only present for compatibility with C++. It is
122 static inline const struct cds_wfcq_head
*cds_wfcq_head_const_cast(const struct cds_wfcq_head
*head
)
127 #else /* #ifndef __cplusplus */
130 * This static inline is used by internally in the static inline
131 * implementation of the API.
133 static inline cds_wfcq_head_ptr_t
__cds_wfcq_head_cast(struct __cds_wfcq_head
*head
)
135 cds_wfcq_head_ptr_t ret
= { ._h
= head
};
140 * This static inline is used by internally in the static inline
141 * implementation of the API.
143 static inline cds_wfcq_head_ptr_t
cds_wfcq_head_cast(struct cds_wfcq_head
*head
)
145 cds_wfcq_head_ptr_t ret
= { .h
= head
};
150 * This static inline is used by internally in the static inline
151 * implementation of the API.
153 static inline cds_wfcq_head_const_ptr_t
__cds_wfcq_head_const_cast(const struct __cds_wfcq_head
*head
)
155 cds_wfcq_head_const_ptr_t ret
= { ._h
= head
};
160 * This static inline is used by internally in the static inline
161 * implementation of the API.
163 static inline cds_wfcq_head_const_ptr_t
cds_wfcq_head_const_cast(const struct cds_wfcq_head
*head
)
165 cds_wfcq_head_const_ptr_t ret
= { .h
= head
};
169 #endif /* #else #ifndef __cplusplus */
171 struct cds_wfcq_tail
{
172 struct cds_wfcq_node
*p
;
177 #include <urcu/static/wfcqueue.h>
179 #define cds_wfcq_node_init _cds_wfcq_node_init
180 #define cds_wfcq_init _cds_wfcq_init
181 #define __cds_wfcq_init ___cds_wfcq_init
182 #define cds_wfcq_destroy _cds_wfcq_destroy
183 #define cds_wfcq_empty _cds_wfcq_empty
184 #define cds_wfcq_enqueue _cds_wfcq_enqueue
186 /* Dequeue locking */
187 #define cds_wfcq_dequeue_lock _cds_wfcq_dequeue_lock
188 #define cds_wfcq_dequeue_unlock _cds_wfcq_dequeue_unlock
190 /* Locking performed within cds_wfcq calls. */
191 #define cds_wfcq_dequeue_blocking _cds_wfcq_dequeue_blocking
192 #define cds_wfcq_dequeue_with_state_blocking \
193 _cds_wfcq_dequeue_with_state_blocking
194 #define cds_wfcq_splice_blocking _cds_wfcq_splice_blocking
195 #define cds_wfcq_first_blocking _cds_wfcq_first_blocking
196 #define cds_wfcq_next_blocking _cds_wfcq_next_blocking
198 /* Locking ensured by caller by holding cds_wfcq_dequeue_lock() */
199 #define __cds_wfcq_dequeue_blocking ___cds_wfcq_dequeue_blocking
200 #define __cds_wfcq_dequeue_with_state_blocking \
201 ___cds_wfcq_dequeue_with_state_blocking
202 #define __cds_wfcq_splice_blocking ___cds_wfcq_splice_blocking
203 #define __cds_wfcq_first_blocking ___cds_wfcq_first_blocking
204 #define __cds_wfcq_next_blocking ___cds_wfcq_next_blocking
207 * Locking ensured by caller by holding cds_wfcq_dequeue_lock().
208 * Non-blocking: deque, first, next return CDS_WFCQ_WOULDBLOCK if they
209 * need to block. splice returns nonzero if it needs to block.
211 #define __cds_wfcq_dequeue_nonblocking ___cds_wfcq_dequeue_nonblocking
212 #define __cds_wfcq_dequeue_with_state_nonblocking \
213 ___cds_wfcq_dequeue_with_state_nonblocking
214 #define __cds_wfcq_splice_nonblocking ___cds_wfcq_splice_nonblocking
215 #define __cds_wfcq_first_nonblocking ___cds_wfcq_first_nonblocking
216 #define __cds_wfcq_next_nonblocking ___cds_wfcq_next_nonblocking
218 #else /* !_LGPL_SOURCE */
221 * Mutual exclusion of cds_wfcq_* / __cds_wfcq_* API
223 * Synchronization table:
225 * External synchronization techniques described in the API below is
226 * required between pairs marked with "X". No external synchronization
227 * required between pairs marked with "-".
230 * [1] cds_wfcq_enqueue
231 * [2] __cds_wfcq_splice (destination queue)
232 * [3] __cds_wfcq_dequeue
233 * [4] __cds_wfcq_splice (source queue)
234 * [5] __cds_wfcq_first
235 * [6] __cds_wfcq_next
237 * [1] [2] [3] [4] [5] [6]
245 * Mutual exclusion can be ensured by holding cds_wfcq_dequeue_lock().
247 * For convenience, cds_wfcq_dequeue_blocking() and
248 * cds_wfcq_splice_blocking() hold the dequeue lock.
250 * Besides locking, mutual exclusion of dequeue, splice and iteration
251 * can be ensured by performing all of those operations from a single
252 * thread, without requiring any lock.
256 * cds_wfcq_node_init: initialize wait-free queue node.
258 extern void cds_wfcq_node_init(struct cds_wfcq_node
*node
);
261 * cds_wfcq_init: initialize wait-free queue. Pair with
262 * cds_wfcq_destroy().
264 extern void cds_wfcq_init(struct cds_wfcq_head
*head
,
265 struct cds_wfcq_tail
*tail
);
268 * cds_wfcq_destroy: destroy wait-free queue. Pair with
271 extern void cds_wfcq_destroy(struct cds_wfcq_head
*head
,
272 struct cds_wfcq_tail
*tail
);
275 * __cds_wfcq_init: initialize wait-free queue (without lock). Don't
276 * pair with any destroy function.
278 extern void __cds_wfcq_init(struct __cds_wfcq_head
*head
,
279 struct cds_wfcq_tail
*tail
);
282 * cds_wfcq_empty: return whether wait-free queue is empty.
284 * No memory barrier is issued. No mutual exclusion is required.
286 extern bool cds_wfcq_empty(cds_wfcq_head_const_ptr_t head
,
287 const struct cds_wfcq_tail
*tail
);
290 * cds_wfcq_dequeue_lock: take the dequeue mutual exclusion lock.
292 extern void cds_wfcq_dequeue_lock(struct cds_wfcq_head
*head
,
293 struct cds_wfcq_tail
*tail
);
296 * cds_wfcq_dequeue_unlock: release the dequeue mutual exclusion lock.
298 extern void cds_wfcq_dequeue_unlock(struct cds_wfcq_head
*head
,
299 struct cds_wfcq_tail
*tail
);
302 * cds_wfcq_enqueue: enqueue a node into a wait-free queue.
304 * Issues a full memory barrier before enqueue. No mutual exclusion is
307 * Returns false if the queue was empty prior to adding the node.
308 * Returns true otherwise.
310 extern bool cds_wfcq_enqueue(cds_wfcq_head_ptr_t head
,
311 struct cds_wfcq_tail
*tail
,
312 struct cds_wfcq_node
*node
);
315 * cds_wfcq_dequeue_blocking: dequeue a node from a wait-free queue.
317 * Content written into the node before enqueue is guaranteed to be
318 * consistent, but no other memory ordering is ensured.
319 * It is valid to reuse and free a dequeued node immediately.
320 * Mutual exclusion with cds_wfcq_dequeue_blocking and dequeue lock is
323 extern struct cds_wfcq_node
*cds_wfcq_dequeue_blocking(
324 struct cds_wfcq_head
*head
,
325 struct cds_wfcq_tail
*tail
);
328 * cds_wfcq_dequeue_with_state_blocking: dequeue with state.
330 * Same as cds_wfcq_dequeue_blocking, but saves whether dequeueing the
331 * last node of the queue into state (CDS_WFCQ_STATE_LAST).
333 extern struct cds_wfcq_node
*cds_wfcq_dequeue_with_state_blocking(
334 struct cds_wfcq_head
*head
,
335 struct cds_wfcq_tail
*tail
,
339 * cds_wfcq_splice_blocking: enqueue all src_q nodes at the end of dest_q.
341 * Dequeue all nodes from src_q.
342 * dest_q must be already initialized.
343 * Content written into the node before enqueue is guaranteed to be
344 * consistent, but no other memory ordering is ensured.
345 * Mutual exclusion with cds_wfcq_dequeue_blocking and dequeue lock is
348 * Returns enum cds_wfcq_ret which indicates the state of the src or
351 extern enum cds_wfcq_ret
cds_wfcq_splice_blocking(
352 struct cds_wfcq_head
*dest_q_head
,
353 struct cds_wfcq_tail
*dest_q_tail
,
354 struct cds_wfcq_head
*src_q_head
,
355 struct cds_wfcq_tail
*src_q_tail
);
358 * __cds_wfcq_dequeue_blocking: dequeue a node from a wait-free queue.
360 * Content written into the node before enqueue is guaranteed to be
361 * consistent, but no other memory ordering is ensured.
362 * It is valid to reuse and free a dequeued node immediately.
363 * Dequeue/splice/iteration mutual exclusion should be ensured by the
366 extern struct cds_wfcq_node
*__cds_wfcq_dequeue_blocking(
367 cds_wfcq_head_ptr_t head
,
368 struct cds_wfcq_tail
*tail
);
371 * __cds_wfcq_dequeue_with_state_blocking: dequeue with state.
373 * Same as __cds_wfcq_dequeue_blocking, but saves whether dequeueing the
374 * last node of the queue into state (CDS_WFCQ_STATE_LAST).
376 extern struct cds_wfcq_node
*__cds_wfcq_dequeue_with_state_blocking(
377 cds_wfcq_head_ptr_t head
,
378 struct cds_wfcq_tail
*tail
,
382 * __cds_wfcq_dequeue_nonblocking: dequeue a node from a wait-free queue.
384 * Same as __cds_wfcq_dequeue_blocking, but returns CDS_WFCQ_WOULDBLOCK
385 * if it needs to block.
387 extern struct cds_wfcq_node
*__cds_wfcq_dequeue_nonblocking(
388 cds_wfcq_head_ptr_t head
,
389 struct cds_wfcq_tail
*tail
);
392 * __cds_wfcq_dequeue_with_state_blocking: dequeue with state.
394 * Same as __cds_wfcq_dequeue_nonblocking, but saves whether dequeueing
395 * the last node of the queue into state (CDS_WFCQ_STATE_LAST).
397 extern struct cds_wfcq_node
*__cds_wfcq_dequeue_with_state_nonblocking(
398 cds_wfcq_head_ptr_t head
,
399 struct cds_wfcq_tail
*tail
,
403 * __cds_wfcq_splice_blocking: enqueue all src_q nodes at the end of dest_q.
405 * Dequeue all nodes from src_q.
406 * dest_q must be already initialized.
407 * Mutual exclusion for src_q should be ensured by the caller as
408 * specified in the "Synchronisation table".
409 * Returns enum cds_wfcq_ret which indicates the state of the src or
410 * dest queue. Never returns CDS_WFCQ_RET_WOULDBLOCK.
412 extern enum cds_wfcq_ret
__cds_wfcq_splice_blocking(
413 cds_wfcq_head_ptr_t dest_q_head
,
414 struct cds_wfcq_tail
*dest_q_tail
,
415 cds_wfcq_head_ptr_t src_q_head
,
416 struct cds_wfcq_tail
*src_q_tail
);
419 * __cds_wfcq_splice_nonblocking: enqueue all src_q nodes at the end of dest_q.
421 * Same as __cds_wfcq_splice_blocking, but returns
422 * CDS_WFCQ_RET_WOULDBLOCK if it needs to block.
424 extern enum cds_wfcq_ret
__cds_wfcq_splice_nonblocking(
425 cds_wfcq_head_ptr_t dest_q_head
,
426 struct cds_wfcq_tail
*dest_q_tail
,
427 cds_wfcq_head_ptr_t src_q_head
,
428 struct cds_wfcq_tail
*src_q_tail
);
431 * __cds_wfcq_first_blocking: get first node of a queue, without dequeuing.
433 * Content written into the node before enqueue is guaranteed to be
434 * consistent, but no other memory ordering is ensured.
435 * Dequeue/splice/iteration mutual exclusion should be ensured by the
438 * Used by for-like iteration macros:
439 * __cds_wfcq_for_each_blocking()
440 * __cds_wfcq_for_each_blocking_safe()
442 * Returns NULL if queue is empty, first node otherwise.
444 extern struct cds_wfcq_node
*__cds_wfcq_first_blocking(
445 cds_wfcq_head_ptr_t head
,
446 struct cds_wfcq_tail
*tail
);
449 * __cds_wfcq_first_nonblocking: get first node of a queue, without dequeuing.
451 * Same as __cds_wfcq_first_blocking, but returns CDS_WFCQ_WOULDBLOCK if
454 extern struct cds_wfcq_node
*__cds_wfcq_first_nonblocking(
455 cds_wfcq_head_ptr_t head
,
456 struct cds_wfcq_tail
*tail
);
459 * __cds_wfcq_next_blocking: get next node of a queue, without dequeuing.
461 * Content written into the node before enqueue is guaranteed to be
462 * consistent, but no other memory ordering is ensured.
463 * Dequeue/splice/iteration mutual exclusion should be ensured by the
466 * Used by for-like iteration macros:
467 * __cds_wfcq_for_each_blocking()
468 * __cds_wfcq_for_each_blocking_safe()
470 * Returns NULL if reached end of queue, non-NULL next queue node
473 extern struct cds_wfcq_node
*__cds_wfcq_next_blocking(
474 cds_wfcq_head_ptr_t head
,
475 struct cds_wfcq_tail
*tail
,
476 struct cds_wfcq_node
*node
);
479 * __cds_wfcq_next_blocking: get next node of a queue, without dequeuing.
481 * Same as __cds_wfcq_next_blocking, but returns CDS_WFCQ_WOULDBLOCK if
484 extern struct cds_wfcq_node
*__cds_wfcq_next_nonblocking(
485 cds_wfcq_head_ptr_t head
,
486 struct cds_wfcq_tail
*tail
,
487 struct cds_wfcq_node
*node
);
489 #endif /* !_LGPL_SOURCE */
492 * __cds_wfcq_for_each_blocking: Iterate over all nodes in a queue,
493 * without dequeuing them.
494 * @head: head of the queue (struct cds_wfcq_head or __cds_wfcq_head pointer).
495 * @tail: tail of the queue (struct cds_wfcq_tail pointer).
496 * @node: iterator on the queue (struct cds_wfcq_node pointer).
498 * Content written into each node before enqueue is guaranteed to be
499 * consistent, but no other memory ordering is ensured.
500 * Dequeue/splice/iteration mutual exclusion should be ensured by the
503 #define __cds_wfcq_for_each_blocking(head, tail, node) \
504 for (node = __cds_wfcq_first_blocking(head, tail); \
506 node = __cds_wfcq_next_blocking(head, tail, node))
509 * __cds_wfcq_for_each_blocking_safe: Iterate over all nodes in a queue,
510 * without dequeuing them. Safe against deletion.
511 * @head: head of the queue (struct cds_wfcq_head or __cds_wfcq_head pointer).
512 * @tail: tail of the queue (struct cds_wfcq_tail pointer).
513 * @node: iterator on the queue (struct cds_wfcq_node pointer).
514 * @n: struct cds_wfcq_node pointer holding the next pointer (used
517 * Content written into each node before enqueue is guaranteed to be
518 * consistent, but no other memory ordering is ensured.
519 * Dequeue/splice/iteration mutual exclusion should be ensured by the
522 #define __cds_wfcq_for_each_blocking_safe(head, tail, node, n) \
523 for (node = __cds_wfcq_first_blocking(head, tail), \
524 n = (node ? __cds_wfcq_next_blocking(head, tail, node) : NULL); \
526 node = n, n = (node ? __cds_wfcq_next_blocking(head, tail, node) : NULL))
532 * In C++, implement static inline wrappers using function overloading
533 * to obtain an API similar to C.
536 static inline cds_wfcq_head_ptr_t
cds_wfcq_head_cast_cpp(struct __cds_wfcq_head
*head
)
538 cds_wfcq_head_ptr_t ret
= { ._h
= head
};
542 static inline cds_wfcq_head_ptr_t
cds_wfcq_head_cast_cpp(struct cds_wfcq_head
*head
)
544 cds_wfcq_head_ptr_t ret
= { .h
= head
};
548 static inline cds_wfcq_head_const_ptr_t
cds_wfcq_head_const_cast_cpp(const struct __cds_wfcq_head
*head
)
550 cds_wfcq_head_const_ptr_t ret
= { ._h
= head
};
554 static inline cds_wfcq_head_const_ptr_t
cds_wfcq_head_const_cast_cpp(const struct cds_wfcq_head
*head
)
556 cds_wfcq_head_const_ptr_t ret
= { .h
= head
};
560 template<typename T
> static inline bool cds_wfcq_empty(T head
,
561 const struct cds_wfcq_tail
*tail
)
563 return cds_wfcq_empty(cds_wfcq_head_const_cast_cpp(head
), tail
);
566 template<typename T
> static inline bool cds_wfcq_enqueue(T head
,
567 struct cds_wfcq_tail
*tail
,
568 struct cds_wfcq_node
*node
)
570 return cds_wfcq_enqueue(cds_wfcq_head_cast_cpp(head
), tail
, node
);
573 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_dequeue_blocking(
574 T head
, struct cds_wfcq_tail
*tail
)
576 return __cds_wfcq_dequeue_blocking(cds_wfcq_head_cast_cpp(head
), tail
);
579 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_dequeue_with_state_blocking(
580 T head
, struct cds_wfcq_tail
*tail
, int *state
)
582 return __cds_wfcq_dequeue_with_state_blocking(cds_wfcq_head_cast_cpp(head
),
586 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_dequeue_nonblocking(
587 T head
, struct cds_wfcq_tail
*tail
)
589 return __cds_wfcq_dequeue_nonblocking(cds_wfcq_head_cast_cpp(head
), tail
);
592 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_dequeue_with_state_nonblocking(
593 T head
, struct cds_wfcq_tail
*tail
, int *state
)
595 return __cds_wfcq_dequeue_with_state_nonblocking(cds_wfcq_head_cast_cpp(head
),
599 template<typename T
, typename U
> static inline enum cds_wfcq_ret
__cds_wfcq_splice_blocking(
601 struct cds_wfcq_tail
*dest_q_tail
,
603 struct cds_wfcq_tail
*src_q_tail
)
605 return __cds_wfcq_splice_blocking(cds_wfcq_head_cast_cpp(dest_q_head
),
607 cds_wfcq_head_cast_cpp(src_q_head
),
611 template<typename T
, typename U
> static inline enum cds_wfcq_ret
__cds_wfcq_splice_nonblocking(
613 struct cds_wfcq_tail
*dest_q_tail
,
615 struct cds_wfcq_tail
*src_q_tail
)
617 return __cds_wfcq_splice_nonblocking(cds_wfcq_head_cast_cpp(dest_q_head
),
619 cds_wfcq_head_cast_cpp(src_q_head
),
623 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_first_blocking(
624 T head
, struct cds_wfcq_tail
*tail
)
626 return __cds_wfcq_first_blocking(cds_wfcq_head_cast_cpp(head
), tail
);
629 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_first_nonblocking(
630 T head
, struct cds_wfcq_tail
*tail
)
632 return __cds_wfcq_first_nonblocking(cds_wfcq_head_cast_cpp(head
), tail
);
635 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_next_blocking(
637 struct cds_wfcq_tail
*tail
,
638 struct cds_wfcq_node
*node
)
640 return __cds_wfcq_next_blocking(cds_wfcq_head_cast_cpp(head
), tail
, node
);
643 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_next_nonblocking(
645 struct cds_wfcq_tail
*tail
,
646 struct cds_wfcq_node
*node
)
648 return __cds_wfcq_next_nonblocking(cds_wfcq_head_cast_cpp(head
), tail
, node
);
653 #endif /* _URCU_WFCQUEUE_H */