[apple/libplatform.git] / man / atomic_deprecated.3

.Dd May 26, 2004
.Dt ATOMIC_DEPRECATED 3
.Os Darwin
.Sh NAME
.Nm OSAtomicAdd32 ,
.Nm OSAtomicAdd32Barrier ,
.Nm OSAtomicIncrement32 ,
.Nm OSAtomicIncrement32Barrier ,
.Nm OSAtomicDecrement32 ,
.Nm OSAtomicDecrement32Barrier ,
.Nm OSAtomicOr32 ,
.Nm OSAtomicOr32Barrier ,
.Nm OSAtomicOr32Orig ,
.Nm OSAtomicOr32OrigBarrier ,
.Nm OSAtomicAnd32 ,
.Nm OSAtomicAnd32Barrier ,
.Nm OSAtomicAnd32Orig ,
.Nm OSAtomicAnd32OrigBarrier ,
.Nm OSAtomicXor32 ,
.Nm OSAtomicXor32Barrier ,
.Nm OSAtomicXor32Orig ,
.Nm OSAtomicXor32OrigBarrier ,
.Nm OSAtomicAdd64 ,
.Nm OSAtomicAdd64Barrier ,
.Nm OSAtomicIncrement64 ,
.Nm OSAtomicIncrement64Barrier ,
.Nm OSAtomicDecrement64 ,
.Nm OSAtomicDecrement64Barrier ,
.Nm OSAtomicCompareAndSwapInt ,
.Nm OSAtomicCompareAndSwapIntBarrier ,
.Nm OSAtomicCompareAndSwapLong ,
.Nm OSAtomicCompareAndSwapLongBarrier ,
.Nm OSAtomicCompareAndSwapPtr ,
.Nm OSAtomicCompareAndSwapPtrBarrier ,
.Nm OSAtomicCompareAndSwap32 ,
.Nm OSAtomicCompareAndSwap32Barrier ,
.Nm OSAtomicCompareAndSwap64 ,
.Nm OSAtomicCompareAndSwap64Barrier ,
.Nm OSAtomicTestAndSet ,
.Nm OSAtomicTestAndSetBarrier ,
.Nm OSAtomicTestAndClear ,
.Nm OSAtomicTestAndClearBarrier ,
.Nm OSMemoryBarrier
.Nd deprecated atomic add, increment, decrement, or, and, xor, compare and swap, test and set, test and clear, and memory barrier
.Sh SYNOPSIS
.In libkern/OSAtomic.h
.Ft int32_t
.Fn OSAtomicAdd32 "int32_t theAmount" "volatile int32_t *theValue"
.Ft int32_t
.Fn OSAtomicAdd32Barrier "int32_t theAmount" "volatile int32_t *theValue"
.Ft int32_t
.Fn OSAtomicIncrement32 "volatile int32_t *theValue"
.Ft int32_t
.Fn OSAtomicIncrement32Barrier "volatile int32_t *theValue"
.Ft int32_t
.Fn OSAtomicDecrement32 "volatile int32_t *theValue"
.Ft int32_t
.Fn OSAtomicDecrement32Barrier "volatile int32_t *theValue"
.Ft int32_t
.Fn OSAtomicOr32 "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicOr32Barrier "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicAnd32 "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicAnd32Barrier "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicXor32 "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicXor32Barrier "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicOr32Orig "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicOr32OrigBarrier "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicAnd32Orig "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicAnd32OrigBarrier "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicXor32Orig "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int32_t
.Fn OSAtomicXor32OrigBarrier "uint32_t theMask" "volatile uint32_t *theValue"
.Ft int64_t
.Fn OSAtomicAdd64 "int64_t theAmount" "volatile OSAtomic_int64_aligned64_t *theValue"
.Ft int64_t
.Fn OSAtomicAdd64Barrier "int64_t theAmount" "volatile OSAtomic_int64_aligned64_t *theValue"
.Ft int64_t
.Fn OSAtomicIncrement64 "volatile OSAtomic_int64_aligned64_t *theValue"
.Ft int64_t
.Fn OSAtomicIncrement64Barrier "volatile OSAtomic_int64_aligned64_t *theValue"
.Ft int64_t
.Fn OSAtomicDecrement64 "volatile OSAtomic_int64_aligned64_t *theValue"
.Ft int64_t
.Fn OSAtomicDecrement64Barrier "volatile OSAtomic_int64_aligned64_t *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwapInt "int oldValue" "int newValue" "volatile int *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwapIntBarrier "int oldValue" "int newValue" "volatile int *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwapLong "long oldValue" "long newValue" "volatile long *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwapLongBarrier "long oldValue" "long newValue" "volatile long *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwapPtr "void* oldValue" "void* newValue" "void* volatile *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwapPtrBarrier "void* oldValue" "void* newValue" "void* volatile *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwap32 "int32_t oldValue" "int32_t newValue" "volatile int32_t *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwap32Barrier "int32_t oldValue" "int32_t newValue" "volatile int32_t *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwap64 "int64_t oldValue" "int64_t newValue" "volatile OSAtomic_int64_aligned64_t *theValue"
.Ft bool
.Fn OSAtomicCompareAndSwap64Barrier "int64_t oldValue" "int64_t newValue" "volatile OSAtomic_int64_aligned64_t *theValue"
.Ft bool
.Fn OSAtomicTestAndSet "uint32_t n" "volatile void *theAddress"
.Ft bool
.Fn OSAtomicTestAndSetBarrier "uint32_t n" "volatile void *theAddress"
.Ft bool
.Fn OSAtomicTestAndClear "uint32_t n" "volatile void *theAddress"
.Ft bool
.Fn OSAtomicTestAndClearBarrier "uint32_t n" "volatile void *theAddress"
.Ft bool
.Fn OSAtomicEnqueue "OSQueueHead *list" "void *new" "size_t offset"
.Ft void*
.Fn OSAtomicDequeue "OSQueueHead *list" "size_t offset"
.Ft void
.Fn OSMemoryBarrier "void"
.Sh DESCRIPTION
.Bf -symbolic
These are deprecated interfaces for atomic and synchronization
operations, provided for compatibility with legacy code. New code should use
the C11
.In stdatomic.h
interfaces.
.Ef
.Pp
These functions are thread and multiprocessor safe.  For each function, there
is a version which incorporates a memory barrier and another version which does
not.
Barriers strictly order memory access on a weakly-ordered architecture such as
ARM. All loads and stores executed in sequential program
order before the barrier will complete before any load or store executed after
the barrier.
On some platforms, such as ARM, the barrier operation can be quite expensive.
.Pp
Most code will want to use the barrier functions to ensure that memory shared
between threads is properly synchronized.  For example, if you want to
initialize a shared data structure and then atomically increment a variable to
indicate that the initialization is complete, then you must use
.Fn OSAtomicIncrement32Barrier
to ensure that the stores to your data structure complete before the atomic add.
Likewise, the consumer of that data structure must use
.Fn OSAtomicDecrement32Barrier ,
in order to ensure that their loads of the structure are not executed before
the atomic decrement.  On the other hand, if you are simply incrementing a
global counter, then it is safe and potentially much faster to use
.Fn OSAtomicIncrement32 .
If you are unsure which version to use, prefer the barrier variants as they are
safer.
.Pp
The logical (and, or, xor) and bit test operations are layered on top of the
.Fn OSAtomicCompareAndSwap
primitives.  There are four versions of each logical operation, depending on
whether or not there is a barrier, and whether the return value is the result
of the operation (eg,
.Fn OSAtomicOr32
) or the original value before the operation (eg,
.Fn OSAtomicOr32Orig
).
.Pp
The memory address
.Fa theValue
must be "naturally aligned", i.e. 32-bit aligned for 32-bit operations and
64-bit aligned for 64-bit operations. Note that this is not the default alignment
of the
.Vt int64_t
in the iOS ARMv7 ABI, the
.Vt OSAtomic_int64_aligned64_t
type can be used to declare variables with the required alignment.
.Pp
The
.Fn OSAtomicCompareAndSwap
operations compare
.Fa oldValue
to
.Fa *theValue ,
and set
.Fa *theValue
to
.Fa newValue
if the comparison is equal.  The comparison and assignment
occur as one atomic operation.
.Pp
.Fn OSAtomicTestAndSet
and
.Fn OSAtomicTestAndClear
operate on bit (0x80 >> (
.Fa n
& 7)) of byte ((char*)
.Fa theAddress
+ (
.Fa n
>> 3)).  They set the named bit to either 1 or 0, respectively.
.Fa theAddress
need not be aligned.
.Pp
The
.Fn OSMemoryBarrier
function strictly orders memory accesses in a weakly ordered memory model such
as with ARM, by creating a barrier.
All loads and stores executed in sequential program order before the barrier
will complete with respect to the memory coherence mechanism, before any load
or store executed after the barrier. Used with an atomic operation, the barrier
can be used to create custom synchronization protocols as an alternative to the
spinlock or queue/dequeue operations. Note that this barrier does not order
uncached loads and stores. On a uniprocessor, the barrier operation is
typically optimized into a no-op.
.Sh RETURN VALUES
The arithmetic operations return the new value, after the operation has been
performed. The boolean operations come in two styles, one of which returns the
new value, and one of which (the "Orig" versions) returns the old.
The compare-and-swap operations return true if the comparison was equal, ie if
the swap occured. The bit test and set/clear operations return the original
value of the bit.
.Sh SEE ALSO
.Xr atomic 3 ,
.Xr spinlock_deprecated 3
.Sh HISTORY
Most of these functions first appeared in Mac OS 10.4 (Tiger).  The "Orig"
forms of the boolean operations, the "int", "long" and "ptr" forms of
compare-and-swap first appeared in Mac OS 10.5 (Leopard).
Commit	Line	Data
ada7c492 A	1	.Dd May 26, 2004
	2	.Dt ATOMIC_DEPRECATED 3
	3	.Os Darwin
	4	.Sh NAME
	5	.Nm OSAtomicAdd32 ,
	6	.Nm OSAtomicAdd32Barrier ,
	7	.Nm OSAtomicIncrement32 ,
	8	.Nm OSAtomicIncrement32Barrier ,
	9	.Nm OSAtomicDecrement32 ,
	10	.Nm OSAtomicDecrement32Barrier ,
	11	.Nm OSAtomicOr32 ,
	12	.Nm OSAtomicOr32Barrier ,
	13	.Nm OSAtomicOr32Orig ,
	14	.Nm OSAtomicOr32OrigBarrier ,
	15	.Nm OSAtomicAnd32 ,
	16	.Nm OSAtomicAnd32Barrier ,
	17	.Nm OSAtomicAnd32Orig ,
	18	.Nm OSAtomicAnd32OrigBarrier ,
	19	.Nm OSAtomicXor32 ,
	20	.Nm OSAtomicXor32Barrier ,
	21	.Nm OSAtomicXor32Orig ,
	22	.Nm OSAtomicXor32OrigBarrier ,
	23	.Nm OSAtomicAdd64 ,
	24	.Nm OSAtomicAdd64Barrier ,
	25	.Nm OSAtomicIncrement64 ,
	26	.Nm OSAtomicIncrement64Barrier ,
	27	.Nm OSAtomicDecrement64 ,
	28	.Nm OSAtomicDecrement64Barrier ,
	29	.Nm OSAtomicCompareAndSwapInt ,
	30	.Nm OSAtomicCompareAndSwapIntBarrier ,
	31	.Nm OSAtomicCompareAndSwapLong ,
	32	.Nm OSAtomicCompareAndSwapLongBarrier ,
	33	.Nm OSAtomicCompareAndSwapPtr ,
	34	.Nm OSAtomicCompareAndSwapPtrBarrier ,
	35	.Nm OSAtomicCompareAndSwap32 ,
	36	.Nm OSAtomicCompareAndSwap32Barrier ,
	37	.Nm OSAtomicCompareAndSwap64 ,
	38	.Nm OSAtomicCompareAndSwap64Barrier ,
	39	.Nm OSAtomicTestAndSet ,
	40	.Nm OSAtomicTestAndSetBarrier ,
	41	.Nm OSAtomicTestAndClear ,
	42	.Nm OSAtomicTestAndClearBarrier ,
	43	.Nm OSMemoryBarrier
	44	.Nd deprecated atomic add, increment, decrement, or, and, xor, compare and swap, test and set, test and clear, and memory barrier
	45	.Sh SYNOPSIS
	46	.In libkern/OSAtomic.h
	47	.Ft int32_t
	48	.Fn OSAtomicAdd32 "int32_t theAmount" "volatile int32_t *theValue"
	49	.Ft int32_t
	50	.Fn OSAtomicAdd32Barrier "int32_t theAmount" "volatile int32_t *theValue"
	51	.Ft int32_t
	52	.Fn OSAtomicIncrement32 "volatile int32_t *theValue"
	53	.Ft int32_t
	54	.Fn OSAtomicIncrement32Barrier "volatile int32_t *theValue"
	55	.Ft int32_t
	56	.Fn OSAtomicDecrement32 "volatile int32_t *theValue"
	57	.Ft int32_t
	58	.Fn OSAtomicDecrement32Barrier "volatile int32_t *theValue"
	59	.Ft int32_t
	60	.Fn OSAtomicOr32 "uint32_t theMask" "volatile uint32_t *theValue"
	61	.Ft int32_t
	62	.Fn OSAtomicOr32Barrier "uint32_t theMask" "volatile uint32_t *theValue"
	63	.Ft int32_t
	64	.Fn OSAtomicAnd32 "uint32_t theMask" "volatile uint32_t *theValue"
65	.Ft int32_t
66	.Fn OSAtomicAnd32Barrier "uint32_t theMask" "volatile uint32_t *theValue"
67	.Ft int32_t
68	.Fn OSAtomicXor32 "uint32_t theMask" "volatile uint32_t *theValue"
69	.Ft int32_t
70	.Fn OSAtomicXor32Barrier "uint32_t theMask" "volatile uint32_t *theValue"
71	.Ft int32_t
72	.Fn OSAtomicOr32Orig "uint32_t theMask" "volatile uint32_t *theValue"
73	.Ft int32_t
74	.Fn OSAtomicOr32OrigBarrier "uint32_t theMask" "volatile uint32_t *theValue"
75	.Ft int32_t
76	.Fn OSAtomicAnd32Orig "uint32_t theMask" "volatile uint32_t *theValue"
77	.Ft int32_t
78	.Fn OSAtomicAnd32OrigBarrier "uint32_t theMask" "volatile uint32_t *theValue"
79	.Ft int32_t
80	.Fn OSAtomicXor32Orig "uint32_t theMask" "volatile uint32_t *theValue"
81	.Ft int32_t
82	.Fn OSAtomicXor32OrigBarrier "uint32_t theMask" "volatile uint32_t *theValue"
83	.Ft int64_t
84	.Fn OSAtomicAdd64 "int64_t theAmount" "volatile OSAtomic_int64_aligned64_t *theValue"
85	.Ft int64_t
86	.Fn OSAtomicAdd64Barrier "int64_t theAmount" "volatile OSAtomic_int64_aligned64_t *theValue"
87	.Ft int64_t
88	.Fn OSAtomicIncrement64 "volatile OSAtomic_int64_aligned64_t *theValue"
89	.Ft int64_t
90	.Fn OSAtomicIncrement64Barrier "volatile OSAtomic_int64_aligned64_t *theValue"
91	.Ft int64_t
92	.Fn OSAtomicDecrement64 "volatile OSAtomic_int64_aligned64_t *theValue"
93	.Ft int64_t
94	.Fn OSAtomicDecrement64Barrier "volatile OSAtomic_int64_aligned64_t *theValue"
95	.Ft bool
96	.Fn OSAtomicCompareAndSwapInt "int oldValue" "int newValue" "volatile int *theValue"
97	.Ft bool
98	.Fn OSAtomicCompareAndSwapIntBarrier "int oldValue" "int newValue" "volatile int *theValue"
99	.Ft bool
100	.Fn OSAtomicCompareAndSwapLong "long oldValue" "long newValue" "volatile long *theValue"
101	.Ft bool
102	.Fn OSAtomicCompareAndSwapLongBarrier "long oldValue" "long newValue" "volatile long *theValue"
103	.Ft bool
104	.Fn OSAtomicCompareAndSwapPtr "void* oldValue" "void* newValue" "void* volatile *theValue"
105	.Ft bool
106	.Fn OSAtomicCompareAndSwapPtrBarrier "void* oldValue" "void* newValue" "void* volatile *theValue"
107	.Ft bool
108	.Fn OSAtomicCompareAndSwap32 "int32_t oldValue" "int32_t newValue" "volatile int32_t *theValue"
109	.Ft bool
110	.Fn OSAtomicCompareAndSwap32Barrier "int32_t oldValue" "int32_t newValue" "volatile int32_t *theValue"
111	.Ft bool
112	.Fn OSAtomicCompareAndSwap64 "int64_t oldValue" "int64_t newValue" "volatile OSAtomic_int64_aligned64_t *theValue"
113	.Ft bool
114	.Fn OSAtomicCompareAndSwap64Barrier "int64_t oldValue" "int64_t newValue" "volatile OSAtomic_int64_aligned64_t *theValue"
115	.Ft bool
116	.Fn OSAtomicTestAndSet "uint32_t n" "volatile void *theAddress"
117	.Ft bool
118	.Fn OSAtomicTestAndSetBarrier "uint32_t n" "volatile void *theAddress"
119	.Ft bool
120	.Fn OSAtomicTestAndClear "uint32_t n" "volatile void *theAddress"
121	.Ft bool
122	.Fn OSAtomicTestAndClearBarrier "uint32_t n" "volatile void *theAddress"
123	.Ft bool
124	.Fn OSAtomicEnqueue "OSQueueHead list" "void new" "size_t offset"
125	.Ft void*
126	.Fn OSAtomicDequeue "OSQueueHead *list" "size_t offset"
127	.Ft void
128	.Fn OSMemoryBarrier "void"
129	.Sh DESCRIPTION
130	.Bf -symbolic
131	These are deprecated interfaces for atomic and synchronization
132	operations, provided for compatibility with legacy code. New code should use
133	the C11
134	.In stdatomic.h
135	interfaces.
136	.Ef
137	.Pp
138	These functions are thread and multiprocessor safe. For each function, there
139	is a version which incorporates a memory barrier and another version which does
140	not.
141	Barriers strictly order memory access on a weakly-ordered architecture such as
142	ARM. All loads and stores executed in sequential program
143	order before the barrier will complete before any load or store executed after
144	the barrier.
145	On some platforms, such as ARM, the barrier operation can be quite expensive.
146	.Pp
147	Most code will want to use the barrier functions to ensure that memory shared
148	between threads is properly synchronized. For example, if you want to
149	initialize a shared data structure and then atomically increment a variable to
150	indicate that the initialization is complete, then you must use
151	.Fn OSAtomicIncrement32Barrier
152	to ensure that the stores to your data structure complete before the atomic add.
153	Likewise, the consumer of that data structure must use
154	.Fn OSAtomicDecrement32Barrier ,
155	in order to ensure that their loads of the structure are not executed before
156	the atomic decrement. On the other hand, if you are simply incrementing a
157	global counter, then it is safe and potentially much faster to use
158	.Fn OSAtomicIncrement32 .
159	If you are unsure which version to use, prefer the barrier variants as they are
160	safer.
161	.Pp
162	The logical (and, or, xor) and bit test operations are layered on top of the
163	.Fn OSAtomicCompareAndSwap
164	primitives. There are four versions of each logical operation, depending on
165	whether or not there is a barrier, and whether the return value is the result
166	of the operation (eg,
167	.Fn OSAtomicOr32
168	) or the original value before the operation (eg,
169	.Fn OSAtomicOr32Orig
170	).
171	.Pp
172	The memory address
173	.Fa theValue
174	must be "naturally aligned", i.e. 32-bit aligned for 32-bit operations and
175	64-bit aligned for 64-bit operations. Note that this is not the default alignment
176	of the
177	.Vt int64_t
178	in the iOS ARMv7 ABI, the
179	.Vt OSAtomic_int64_aligned64_t
180	type can be used to declare variables with the required alignment.
181	.Pp
182	The
183	.Fn OSAtomicCompareAndSwap
184	operations compare
185	.Fa oldValue
186	to
187	.Fa *theValue ,
188	and set
189	.Fa *theValue
190	to
191	.Fa newValue
192	if the comparison is equal. The comparison and assignment
193	occur as one atomic operation.
194	.Pp
195	.Fn OSAtomicTestAndSet
196	and
197	.Fn OSAtomicTestAndClear
198	operate on bit (0x80 >> (
199	.Fa n
200	& 7)) of byte ((char*)
201	.Fa theAddress
202	+ (
203	.Fa n
204	>> 3)). They set the named bit to either 1 or 0, respectively.
205	.Fa theAddress
206	need not be aligned.
207	.Pp
208	The
209	.Fn OSMemoryBarrier
210	function strictly orders memory accesses in a weakly ordered memory model such
211	as with ARM, by creating a barrier.
212	All loads and stores executed in sequential program order before the barrier
213	will complete with respect to the memory coherence mechanism, before any load
214	or store executed after the barrier. Used with an atomic operation, the barrier
215	can be used to create custom synchronization protocols as an alternative to the
216	spinlock or queue/dequeue operations. Note that this barrier does not order
217	uncached loads and stores. On a uniprocessor, the barrier operation is
218	typically optimized into a no-op.
219	.Sh RETURN VALUES
220	The arithmetic operations return the new value, after the operation has been
221	performed. The boolean operations come in two styles, one of which returns the
222	new value, and one of which (the "Orig" versions) returns the old.
223	The compare-and-swap operations return true if the comparison was equal, ie if
224	the swap occured. The bit test and set/clear operations return the original
225	value of the bit.
226	.Sh SEE ALSO
227	.Xr atomic 3 ,
228	.Xr spinlock_deprecated 3
229	.Sh HISTORY
230	Most of these functions first appeared in Mac OS 10.4 (Tiger). The "Orig"
231	forms of the boolean operations, the "int", "long" and "ptr" forms of
232	compare-and-swap first appeared in Mac OS 10.5 (Leopard).