[lttng-ust.git] / include / lttng / urcu / static / pointer.h

/*
 * SPDX-License-Identifier: LGPL-2.1-or-later
 *
 * Copyright (c) 2009 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 * Copyright (c) 2009 Paul E. McKenney, IBM Corporation.
 *
 * Userspace RCU header. Operations on pointers.
 *
 * TO BE INCLUDED ONLY IN CODE THAT IS TO BE RECOMPILED ON EACH LIBURCU
 * RELEASE. See urcu.h for linking dynamically with the userspace rcu library.
 */

#ifndef _LTTNG_URCU_POINTER_STATIC_H
#define _LTTNG_URCU_POINTER_STATIC_H

#include <urcu/compiler.h>
#include <urcu/arch.h>
#include <urcu/system.h>
#include <urcu/uatomic.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * _rcu_dereference - reads (copy) a RCU-protected pointer to a local variable
 * into a RCU read-side critical section. The pointer can later be safely
 * dereferenced within the critical section.
 *
 * This ensures that the pointer copy is invariant thorough the whole critical
 * section.
 *
 * Inserts memory barriers on architectures that require them (currently only
 * Alpha) and documents which pointers are protected by RCU.
 *
 * The compiler memory barrier in CMM_LOAD_SHARED() ensures that value-speculative
 * optimizations (e.g. VSS: Value Speculation Scheduling) does not perform the
 * data read before the pointer read by speculating the value of the pointer.
 * Correct ordering is ensured because the pointer is read as a volatile access.
 * This acts as a global side-effect operation, which forbids reordering of
 * dependent memory operations. Note that such concern about dependency-breaking
 * optimizations will eventually be taken care of by the "memory_order_consume"
 * addition to forthcoming C++ standard.
 *
 * Should match rcu_assign_pointer() or rcu_xchg_pointer().
 *
 * This macro is less than 10 lines long.  The intent is that this macro
 * meets the 10-line criterion in LGPL, allowing this function to be
 * expanded directly in non-LGPL code.
 */
#define _lttng_ust_rcu_dereference(p)					\
				__extension__				\
				({					\
				__typeof__(p) _________p1 = CMM_LOAD_SHARED(p); \
				cmm_smp_read_barrier_depends();		\
				(_________p1);				\
				})

/**
 * _rcu_cmpxchg_pointer - same as rcu_assign_pointer, but tests if the pointer
 * is as expected by "old". If succeeds, returns the previous pointer to the
 * data structure, which can be safely freed after waiting for a quiescent state
 * using synchronize_rcu(). If fails (unexpected value), returns old (which
 * should not be freed !).
 *
 * uatomic_cmpxchg() acts as both release and acquire barriers.
 *
 * This macro is less than 10 lines long.  The intent is that this macro
 * meets the 10-line criterion in LGPL, allowing this function to be
 * expanded directly in non-LGPL code.
 */
#define _lttng_ust_rcu_cmpxchg_pointer(p, old, _new)			\
	__extension__							\
	({								\
		__typeof__(*p) _________pold = (old);			\
		__typeof__(*p) _________pnew = (_new);			\
		uatomic_cmpxchg(p, _________pold, _________pnew);	\
	})

/**
 * _rcu_xchg_pointer - same as rcu_assign_pointer, but returns the previous
 * pointer to the data structure, which can be safely freed after waiting for a
 * quiescent state using synchronize_rcu().
 *
 * uatomic_xchg() acts as both release and acquire barriers.
 *
 * This macro is less than 10 lines long.  The intent is that this macro
 * meets the 10-line criterion in LGPL, allowing this function to be
 * expanded directly in non-LGPL code.
 */
#define _lttng_ust_rcu_xchg_pointer(p, v)		\
	__extension__					\
	({						\
		__typeof__(*p) _________pv = (v);	\
		uatomic_xchg(p, _________pv);		\
	})


#define _lttng_ust_rcu_set_pointer(p, v)		\
	do {						\
		__typeof__(*p) _________pv = (v);	\
		if (!__builtin_constant_p(v) || 	\
		    ((v) != NULL))			\
			cmm_wmb();			\
		uatomic_set(p, _________pv);		\
	} while (0)

/**
 * _rcu_assign_pointer - assign (publicize) a pointer to a new data structure
 * meant to be read by RCU read-side critical sections. Returns the assigned
 * value.
 *
 * Documents which pointers will be dereferenced by RCU read-side critical
 * sections and adds the required memory barriers on architectures requiring
 * them. It also makes sure the compiler does not reorder code initializing the
 * data structure before its publication.
 *
 * Should match rcu_dereference().
 *
 * This macro is less than 10 lines long.  The intent is that this macro
 * meets the 10-line criterion in LGPL, allowing this function to be
 * expanded directly in non-LGPL code.
 */
#define _lttng_ust_rcu_assign_pointer(p, v)	_lttng_ust_rcu_set_pointer(&(p), v)

#ifdef __cplusplus
}
#endif

#endif /* _LTTNG_URCU_POINTER_STATIC_H */
Commit	Line	Data
10544ee8	1	/*
c0c0989a	2	* SPDX-License-Identifier: LGPL-2.1-or-later
10544ee8 MD	3	*
	4	* Copyright (c) 2009 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
	5	* Copyright (c) 2009 Paul E. McKenney, IBM Corporation.
	6	*
c0c0989a	7	* Userspace RCU header. Operations on pointers.
10544ee8	8	*
c0c0989a MJ	9	* TO BE INCLUDED ONLY IN CODE THAT IS TO BE RECOMPILED ON EACH LIBURCU
c0c0989a MJ	10	* RELEASE. See urcu.h for linking dynamically with the userspace rcu library.
10544ee8 MD	11	*/
10544ee8 MD	12
c0c0989a MJ	13	#ifndef _LTTNG_URCU_POINTER_STATIC_H
	14	#define _LTTNG_URCU_POINTER_STATIC_H
	15
10544ee8 MD	16	#include <urcu/compiler.h>
	17	#include <urcu/arch.h>
	18	#include <urcu/system.h>
	19	#include <urcu/uatomic.h>
	20
	21	#ifdef __cplusplus
	22	extern "C" {
	23	#endif
	24
	25	/**
	26	* _rcu_dereference - reads (copy) a RCU-protected pointer to a local variable
	27	* into a RCU read-side critical section. The pointer can later be safely
	28	* dereferenced within the critical section.
	29	*
	30	* This ensures that the pointer copy is invariant thorough the whole critical
	31	* section.
	32	*
	33	* Inserts memory barriers on architectures that require them (currently only
	34	* Alpha) and documents which pointers are protected by RCU.
	35	*
	36	* The compiler memory barrier in CMM_LOAD_SHARED() ensures that value-speculative
	37	* optimizations (e.g. VSS: Value Speculation Scheduling) does not perform the
	38	* data read before the pointer read by speculating the value of the pointer.
	39	* Correct ordering is ensured because the pointer is read as a volatile access.
	40	* This acts as a global side-effect operation, which forbids reordering of
	41	* dependent memory operations. Note that such concern about dependency-breaking
	42	* optimizations will eventually be taken care of by the "memory_order_consume"
	43	* addition to forthcoming C++ standard.
	44	*
	45	* Should match rcu_assign_pointer() or rcu_xchg_pointer().
	46	*
	47	* This macro is less than 10 lines long. The intent is that this macro
	48	* meets the 10-line criterion in LGPL, allowing this function to be
	49	* expanded directly in non-LGPL code.
	50	*/
	51	#define _lttng_ust_rcu_dereference(p) \
	52	__extension__ \
	53	({ \
	54	__typeof__(p) _________p1 = CMM_LOAD_SHARED(p); \
	55	cmm_smp_read_barrier_depends(); \
	56	(_________p1); \
	57	})
	58
	59	/**
	60	* _rcu_cmpxchg_pointer - same as rcu_assign_pointer, but tests if the pointer
	61	* is as expected by "old". If succeeds, returns the previous pointer to the
	62	* data structure, which can be safely freed after waiting for a quiescent state
	63	* using synchronize_rcu(). If fails (unexpected value), returns old (which
	64	* should not be freed !).
	65	*
	66	* uatomic_cmpxchg() acts as both release and acquire barriers.
	67	*
	68	* This macro is less than 10 lines long. The intent is that this macro
	69	* meets the 10-line criterion in LGPL, allowing this function to be
	70	* expanded directly in non-LGPL code.
	71	*/
	72	#define _lttng_ust_rcu_cmpxchg_pointer(p, old, _new) \
	73	__extension__ \
	74	({ \
	75	__typeof__(*p) _________pold = (old); \
	76	__typeof__(*p) _________pnew = (_new); \
	77	uatomic_cmpxchg(p, _________pold, _________pnew); \
	78	})
	79
80	/**
81	* _rcu_xchg_pointer - same as rcu_assign_pointer, but returns the previous
82	* pointer to the data structure, which can be safely freed after waiting for a
83	* quiescent state using synchronize_rcu().
84	*
85	* uatomic_xchg() acts as both release and acquire barriers.
86	*
87	* This macro is less than 10 lines long. The intent is that this macro
88	* meets the 10-line criterion in LGPL, allowing this function to be
89	* expanded directly in non-LGPL code.
90	*/
91	#define _lttng_ust_rcu_xchg_pointer(p, v) \
92	__extension__ \
93	({ \
94	__typeof__(*p) _________pv = (v); \
95	uatomic_xchg(p, _________pv); \
96	})
97
98
99	#define _lttng_ust_rcu_set_pointer(p, v) \
100	do { \
101	__typeof__(*p) _________pv = (v); \
102	if (!__builtin_constant_p(v) \|\| \
103	((v) != NULL)) \
104	cmm_wmb(); \
105	uatomic_set(p, _________pv); \
106	} while (0)
107
108	/**
109	* _rcu_assign_pointer - assign (publicize) a pointer to a new data structure
110	* meant to be read by RCU read-side critical sections. Returns the assigned
111	* value.
112	*
113	* Documents which pointers will be dereferenced by RCU read-side critical
114	* sections and adds the required memory barriers on architectures requiring
115	* them. It also makes sure the compiler does not reorder code initializing the
116	* data structure before its publication.
117	*
118	* Should match rcu_dereference().
119	*
120	* This macro is less than 10 lines long. The intent is that this macro
121	* meets the 10-line criterion in LGPL, allowing this function to be
122	* expanded directly in non-LGPL code.
123	*/
124	#define _lttng_ust_rcu_assign_pointer(p, v) _lttng_ust_rcu_set_pointer(&(p), v)
125
126	#ifdef __cplusplus
127	}
128	#endif
129
130	#endif /* _LTTNG_URCU_POINTER_STATIC_H */