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
;
81 #if defined(__clang__)
82 #pragma clang diagnostic pop
87 * This static inline is only present for compatibility with C++. It is
90 static inline struct __cds_wfcq_head
*__cds_wfcq_head_cast(struct __cds_wfcq_head
*head
)
96 * This static inline is only present for compatibility with C++. It is
99 static inline struct cds_wfcq_head
*cds_wfcq_head_cast(struct cds_wfcq_head
*head
)
103 #else /* #ifndef __cplusplus */
106 * This static inline is used by internally in the static inline
107 * implementation of the API.
109 static inline cds_wfcq_head_ptr_t
__cds_wfcq_head_cast(struct __cds_wfcq_head
*head
)
111 cds_wfcq_head_ptr_t ret
= { ._h
= head
};
116 * This static inline is used by internally in the static inline
117 * implementation of the API.
119 static inline cds_wfcq_head_ptr_t
cds_wfcq_head_cast(struct cds_wfcq_head
*head
)
121 cds_wfcq_head_ptr_t ret
= { .h
= head
};
124 #endif /* #else #ifndef __cplusplus */
126 struct cds_wfcq_tail
{
127 struct cds_wfcq_node
*p
;
132 #include <urcu/static/wfcqueue.h>
134 #define cds_wfcq_node_init _cds_wfcq_node_init
135 #define cds_wfcq_init _cds_wfcq_init
136 #define __cds_wfcq_init ___cds_wfcq_init
137 #define cds_wfcq_destroy _cds_wfcq_destroy
138 #define cds_wfcq_empty _cds_wfcq_empty
139 #define cds_wfcq_enqueue _cds_wfcq_enqueue
141 /* Dequeue locking */
142 #define cds_wfcq_dequeue_lock _cds_wfcq_dequeue_lock
143 #define cds_wfcq_dequeue_unlock _cds_wfcq_dequeue_unlock
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
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
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.
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
173 #else /* !_LGPL_SOURCE */
176 * Mutual exclusion of cds_wfcq_* / __cds_wfcq_* API
178 * Synchronization table:
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 "-".
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
192 * [1] [2] [3] [4] [5] [6]
200 * Mutual exclusion can be ensured by holding cds_wfcq_dequeue_lock().
202 * For convenience, cds_wfcq_dequeue_blocking() and
203 * cds_wfcq_splice_blocking() hold the dequeue lock.
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.
211 * cds_wfcq_node_init: initialize wait-free queue node.
213 extern void cds_wfcq_node_init(struct cds_wfcq_node
*node
);
216 * cds_wfcq_init: initialize wait-free queue. Pair with
217 * cds_wfcq_destroy().
219 extern void cds_wfcq_init(struct cds_wfcq_head
*head
,
220 struct cds_wfcq_tail
*tail
);
223 * cds_wfcq_destroy: destroy wait-free queue. Pair with
226 extern void cds_wfcq_destroy(struct cds_wfcq_head
*head
,
227 struct cds_wfcq_tail
*tail
);
230 * __cds_wfcq_init: initialize wait-free queue (without lock). Don't
231 * pair with any destroy function.
233 extern void __cds_wfcq_init(struct __cds_wfcq_head
*head
,
234 struct cds_wfcq_tail
*tail
);
237 * cds_wfcq_empty: return whether wait-free queue is empty.
239 * No memory barrier is issued. No mutual exclusion is required.
241 extern bool cds_wfcq_empty(cds_wfcq_head_ptr_t head
,
242 struct cds_wfcq_tail
*tail
);
245 * cds_wfcq_dequeue_lock: take the dequeue mutual exclusion lock.
247 extern void cds_wfcq_dequeue_lock(struct cds_wfcq_head
*head
,
248 struct cds_wfcq_tail
*tail
);
251 * cds_wfcq_dequeue_unlock: release the dequeue mutual exclusion lock.
253 extern void cds_wfcq_dequeue_unlock(struct cds_wfcq_head
*head
,
254 struct cds_wfcq_tail
*tail
);
257 * cds_wfcq_enqueue: enqueue a node into a wait-free queue.
259 * Issues a full memory barrier before enqueue. No mutual exclusion is
262 * Returns false if the queue was empty prior to adding the node.
263 * Returns true otherwise.
265 extern bool cds_wfcq_enqueue(cds_wfcq_head_ptr_t head
,
266 struct cds_wfcq_tail
*tail
,
267 struct cds_wfcq_node
*node
);
270 * cds_wfcq_dequeue_blocking: dequeue a node from a wait-free queue.
272 * Content written into the node before enqueue is guaranteed to be
273 * consistent, but no other memory ordering is ensured.
274 * It is valid to reuse and free a dequeued node immediately.
275 * Mutual exclusion with cds_wfcq_dequeue_blocking and dequeue lock is
278 extern struct cds_wfcq_node
*cds_wfcq_dequeue_blocking(
279 struct cds_wfcq_head
*head
,
280 struct cds_wfcq_tail
*tail
);
283 * cds_wfcq_dequeue_with_state_blocking: dequeue with state.
285 * Same as cds_wfcq_dequeue_blocking, but saves whether dequeueing the
286 * last node of the queue into state (CDS_WFCQ_STATE_LAST).
288 extern struct cds_wfcq_node
*cds_wfcq_dequeue_with_state_blocking(
289 struct cds_wfcq_head
*head
,
290 struct cds_wfcq_tail
*tail
,
294 * cds_wfcq_splice_blocking: enqueue all src_q nodes at the end of dest_q.
296 * Dequeue all nodes from src_q.
297 * dest_q must be already initialized.
298 * Content written into the node before enqueue is guaranteed to be
299 * consistent, but no other memory ordering is ensured.
300 * Mutual exclusion with cds_wfcq_dequeue_blocking and dequeue lock is
303 * Returns enum cds_wfcq_ret which indicates the state of the src or
306 extern enum cds_wfcq_ret
cds_wfcq_splice_blocking(
307 struct cds_wfcq_head
*dest_q_head
,
308 struct cds_wfcq_tail
*dest_q_tail
,
309 struct cds_wfcq_head
*src_q_head
,
310 struct cds_wfcq_tail
*src_q_tail
);
313 * __cds_wfcq_dequeue_blocking: dequeue a node from a wait-free queue.
315 * Content written into the node before enqueue is guaranteed to be
316 * consistent, but no other memory ordering is ensured.
317 * It is valid to reuse and free a dequeued node immediately.
318 * Dequeue/splice/iteration mutual exclusion should be ensured by the
321 extern struct cds_wfcq_node
*__cds_wfcq_dequeue_blocking(
322 cds_wfcq_head_ptr_t head
,
323 struct cds_wfcq_tail
*tail
);
326 * __cds_wfcq_dequeue_with_state_blocking: dequeue with state.
328 * Same as __cds_wfcq_dequeue_blocking, but saves whether dequeueing the
329 * last node of the queue into state (CDS_WFCQ_STATE_LAST).
331 extern struct cds_wfcq_node
*__cds_wfcq_dequeue_with_state_blocking(
332 cds_wfcq_head_ptr_t head
,
333 struct cds_wfcq_tail
*tail
,
337 * __cds_wfcq_dequeue_nonblocking: dequeue a node from a wait-free queue.
339 * Same as __cds_wfcq_dequeue_blocking, but returns CDS_WFCQ_WOULDBLOCK
340 * if it needs to block.
342 extern struct cds_wfcq_node
*__cds_wfcq_dequeue_nonblocking(
343 cds_wfcq_head_ptr_t head
,
344 struct cds_wfcq_tail
*tail
);
347 * __cds_wfcq_dequeue_with_state_blocking: dequeue with state.
349 * Same as __cds_wfcq_dequeue_nonblocking, but saves whether dequeueing
350 * the last node of the queue into state (CDS_WFCQ_STATE_LAST).
352 extern struct cds_wfcq_node
*__cds_wfcq_dequeue_with_state_nonblocking(
353 cds_wfcq_head_ptr_t head
,
354 struct cds_wfcq_tail
*tail
,
358 * __cds_wfcq_splice_blocking: enqueue all src_q nodes at the end of dest_q.
360 * Dequeue all nodes from src_q.
361 * dest_q must be already initialized.
362 * Mutual exclusion for src_q should be ensured by the caller as
363 * specified in the "Synchronisation table".
364 * Returns enum cds_wfcq_ret which indicates the state of the src or
365 * dest queue. Never returns CDS_WFCQ_RET_WOULDBLOCK.
367 extern enum cds_wfcq_ret
__cds_wfcq_splice_blocking(
368 cds_wfcq_head_ptr_t dest_q_head
,
369 struct cds_wfcq_tail
*dest_q_tail
,
370 cds_wfcq_head_ptr_t src_q_head
,
371 struct cds_wfcq_tail
*src_q_tail
);
374 * __cds_wfcq_splice_nonblocking: enqueue all src_q nodes at the end of dest_q.
376 * Same as __cds_wfcq_splice_blocking, but returns
377 * CDS_WFCQ_RET_WOULDBLOCK if it needs to block.
379 extern enum cds_wfcq_ret
__cds_wfcq_splice_nonblocking(
380 cds_wfcq_head_ptr_t dest_q_head
,
381 struct cds_wfcq_tail
*dest_q_tail
,
382 cds_wfcq_head_ptr_t src_q_head
,
383 struct cds_wfcq_tail
*src_q_tail
);
386 * __cds_wfcq_first_blocking: get first node of a queue, without dequeuing.
388 * Content written into the node before enqueue is guaranteed to be
389 * consistent, but no other memory ordering is ensured.
390 * Dequeue/splice/iteration mutual exclusion should be ensured by the
393 * Used by for-like iteration macros:
394 * __cds_wfcq_for_each_blocking()
395 * __cds_wfcq_for_each_blocking_safe()
397 * Returns NULL if queue is empty, first node otherwise.
399 extern struct cds_wfcq_node
*__cds_wfcq_first_blocking(
400 cds_wfcq_head_ptr_t head
,
401 struct cds_wfcq_tail
*tail
);
404 * __cds_wfcq_first_nonblocking: get first node of a queue, without dequeuing.
406 * Same as __cds_wfcq_first_blocking, but returns CDS_WFCQ_WOULDBLOCK if
409 extern struct cds_wfcq_node
*__cds_wfcq_first_nonblocking(
410 cds_wfcq_head_ptr_t head
,
411 struct cds_wfcq_tail
*tail
);
414 * __cds_wfcq_next_blocking: get next node of a queue, without dequeuing.
416 * Content written into the node before enqueue is guaranteed to be
417 * consistent, but no other memory ordering is ensured.
418 * Dequeue/splice/iteration mutual exclusion should be ensured by the
421 * Used by for-like iteration macros:
422 * __cds_wfcq_for_each_blocking()
423 * __cds_wfcq_for_each_blocking_safe()
425 * Returns NULL if reached end of queue, non-NULL next queue node
428 extern struct cds_wfcq_node
*__cds_wfcq_next_blocking(
429 cds_wfcq_head_ptr_t head
,
430 struct cds_wfcq_tail
*tail
,
431 struct cds_wfcq_node
*node
);
434 * __cds_wfcq_next_blocking: get next node of a queue, without dequeuing.
436 * Same as __cds_wfcq_next_blocking, but returns CDS_WFCQ_WOULDBLOCK if
439 extern struct cds_wfcq_node
*__cds_wfcq_next_nonblocking(
440 cds_wfcq_head_ptr_t head
,
441 struct cds_wfcq_tail
*tail
,
442 struct cds_wfcq_node
*node
);
444 #endif /* !_LGPL_SOURCE */
447 * __cds_wfcq_for_each_blocking: Iterate over all nodes in a queue,
448 * without dequeuing them.
449 * @head: head of the queue (struct cds_wfcq_head or __cds_wfcq_head pointer).
450 * @tail: tail of the queue (struct cds_wfcq_tail pointer).
451 * @node: iterator on the queue (struct cds_wfcq_node pointer).
453 * Content written into each node before enqueue is guaranteed to be
454 * consistent, but no other memory ordering is ensured.
455 * Dequeue/splice/iteration mutual exclusion should be ensured by the
458 #define __cds_wfcq_for_each_blocking(head, tail, node) \
459 for (node = __cds_wfcq_first_blocking(head, tail); \
461 node = __cds_wfcq_next_blocking(head, tail, node))
464 * __cds_wfcq_for_each_blocking_safe: Iterate over all nodes in a queue,
465 * without dequeuing them. Safe against deletion.
466 * @head: head of the queue (struct cds_wfcq_head or __cds_wfcq_head pointer).
467 * @tail: tail of the queue (struct cds_wfcq_tail pointer).
468 * @node: iterator on the queue (struct cds_wfcq_node pointer).
469 * @n: struct cds_wfcq_node pointer holding the next pointer (used
472 * Content written into each node before enqueue is guaranteed to be
473 * consistent, but no other memory ordering is ensured.
474 * Dequeue/splice/iteration mutual exclusion should be ensured by the
477 #define __cds_wfcq_for_each_blocking_safe(head, tail, node, n) \
478 for (node = __cds_wfcq_first_blocking(head, tail), \
479 n = (node ? __cds_wfcq_next_blocking(head, tail, node) : NULL); \
481 node = n, n = (node ? __cds_wfcq_next_blocking(head, tail, node) : NULL))
487 * In C++, implement static inline wrappers using function overloading
488 * to obtain an API similar to C.
491 static inline cds_wfcq_head_ptr_t
cds_wfcq_head_cast_cpp(struct __cds_wfcq_head
*head
)
493 cds_wfcq_head_ptr_t ret
= { ._h
= head
};
497 static inline cds_wfcq_head_ptr_t
cds_wfcq_head_cast_cpp(struct cds_wfcq_head
*head
)
499 cds_wfcq_head_ptr_t ret
= { .h
= head
};
503 template<typename T
> static inline bool cds_wfcq_empty(T head
,
504 struct cds_wfcq_tail
*tail
)
506 return cds_wfcq_empty(cds_wfcq_head_cast_cpp(head
), tail
);
509 template<typename T
> static inline bool cds_wfcq_enqueue(T head
,
510 struct cds_wfcq_tail
*tail
,
511 struct cds_wfcq_node
*node
)
513 return cds_wfcq_enqueue(cds_wfcq_head_cast_cpp(head
), tail
, node
);
516 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_dequeue_blocking(
517 T head
, struct cds_wfcq_tail
*tail
)
519 return __cds_wfcq_dequeue_blocking(cds_wfcq_head_cast_cpp(head
), tail
);
522 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_dequeue_with_state_blocking(
523 T head
, struct cds_wfcq_tail
*tail
, int *state
)
525 return __cds_wfcq_dequeue_with_state_blocking(cds_wfcq_head_cast_cpp(head
),
529 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_dequeue_nonblocking(
530 T head
, struct cds_wfcq_tail
*tail
)
532 return __cds_wfcq_dequeue_nonblocking(cds_wfcq_head_cast_cpp(head
), tail
);
535 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_dequeue_with_state_nonblocking(
536 T head
, struct cds_wfcq_tail
*tail
, int *state
)
538 return __cds_wfcq_dequeue_with_state_nonblocking(cds_wfcq_head_cast_cpp(head
),
542 template<typename T
, typename U
> static inline enum cds_wfcq_ret
__cds_wfcq_splice_blocking(
544 struct cds_wfcq_tail
*dest_q_tail
,
546 struct cds_wfcq_tail
*src_q_tail
)
548 return __cds_wfcq_splice_blocking(cds_wfcq_head_cast_cpp(dest_q_head
),
550 cds_wfcq_head_cast_cpp(src_q_head
),
554 template<typename T
, typename U
> static inline enum cds_wfcq_ret
__cds_wfcq_splice_nonblocking(
556 struct cds_wfcq_tail
*dest_q_tail
,
558 struct cds_wfcq_tail
*src_q_tail
)
560 return __cds_wfcq_splice_nonblocking(cds_wfcq_head_cast_cpp(dest_q_head
),
562 cds_wfcq_head_cast_cpp(src_q_head
),
566 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_first_blocking(
567 T head
, struct cds_wfcq_tail
*tail
)
569 return __cds_wfcq_first_blocking(cds_wfcq_head_cast_cpp(head
), tail
);
572 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_first_nonblocking(
573 T head
, struct cds_wfcq_tail
*tail
)
575 return __cds_wfcq_first_nonblocking(cds_wfcq_head_cast_cpp(head
), tail
);
578 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_next_blocking(
580 struct cds_wfcq_tail
*tail
,
581 struct cds_wfcq_node
*node
)
583 return __cds_wfcq_next_blocking(cds_wfcq_head_cast_cpp(head
), tail
, node
);
586 template<typename T
> static inline struct cds_wfcq_node
*__cds_wfcq_next_nonblocking(
588 struct cds_wfcq_tail
*tail
,
589 struct cds_wfcq_node
*node
)
591 return __cds_wfcq_next_nonblocking(cds_wfcq_head_cast_cpp(head
), tail
, node
);
596 #endif /* _URCU_WFCQUEUE_H */