Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libcxx / f6fe084fd45d1f835c46406dc2c92bc1fc6e6251 / . / www / atomic_design_a.html
blob: d8cc6c6124191dae09b1fa60c88e7fa7f036f766 [file] [log] [blame]
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
4<html>
5<head>
6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7 <title>&lt;atomic&gt; design</title>
8 <link type="text/css" rel="stylesheet" href="menu.css">
9 <link type="text/css" rel="stylesheet" href="content.css">
10</head>
11
12<body>
13<div id="menu">
14 <div>
15 <a href="http://llvm.org/">LLVM Home</a>
16 </div>
17
18 <div class="submenu">
19 <label>libc++ Info</label>
20 <a href="/index.html">About</a>
21 </div>
22
23 <div class="submenu">
24 <label>Quick Links</label>
25 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a>
26 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a>
27 <a href="http://llvm.org/bugs/">Bug Reports</a>
28 <a href="http://llvm.org/svn/llvm-project/libcxx/trunk/">Browse SVN</a>
29 <a href="http://llvm.org/viewvc/llvm-project/libcxx/trunk/">Browse ViewVC</a>
30 </div>
31</div>
32
33<div id="content">
34 <!--*********************************************************************-->
35 <h1>&lt;atomic&gt; design</h1>
36 <!--*********************************************************************-->
37
38<p>
Howard Hinnantf6fe0842010-10-18 16:02:24 +0000[diff] [blame^]39The compiler supplies all of the intrinsics as described below. This list of
40intrinsics roughly parallels the requirements of the C and C++ atomics
41proposals. The C and C++ library imlpementations simply drop through to these
42intrinsics. Anything the platform does not support in hardware, the compiler
43arranges for a (compiler-rt) library call to be made which will do the job with
44a mutex, and in this case ignoring the memory ordering parameter (effectively
45implementing <tt>memory_order_seq_cst</tt>).
46</p>
47
48<p>
49Ultimate efficiency is preferred over run time error checking. Undefined
50behavior is acceptable when the inputs do not conform as defined below.
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]51</p>
52
53<blockquote><pre>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]54<font color="#C80000">// In every intrinsic signature below, type* atomic_obj may be a pointer to a</font>
55<font color="#C80000">// volatile-qualifed type.</font>
Howard Hinnantf6fe0842010-10-18 16:02:24 +0000[diff] [blame^]56<font color="#C80000">// Memory ordering values map to the following meanings:</font>
57<font color="#C80000">// memory_order_relaxed == 0</font>
58<font color="#C80000">// memory_order_consume == 1</font>
59<font color="#C80000">// memory_order_acquire == 2</font>
60<font color="#C80000">// memory_order_release == 3</font>
61<font color="#C80000">// memory_order_acq_rel == 4</font>
62<font color="#C80000">// memory_order_seq_cst == 5</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]63
64<font color="#C80000">// type must be trivially copyable</font>
Howard Hinnantf6fe0842010-10-18 16:02:24 +0000[diff] [blame^]65<font color="#C80000">// type represents a "type argument"</font>
66bool __atomic_is_lock_free(type);
Howard Hinnant08f29692010-10-08 17:36:50 +0000[diff] [blame]67
68<font color="#C80000">// type must be trivially copyable</font>
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]69<font color="#C80000">// Behavior is defined for mem_ord = 0, 1, 2, 5</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]70type __atomic_load(const type* atomic_obj, int mem_ord);
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]71
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]72<font color="#C80000">// type must be trivially copyable</font>
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]73<font color="#C80000">// Behavior is defined for mem_ord = 0, 3, 5</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]74type __atomic_store(type* atomic_obj, type desired, int mem_ord);
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]75
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]76<font color="#C80000">// type must be trivially copyable</font>
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]77<font color="#C80000">// Behavior is defined for mem_ord = [0 ... 5]</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]78type __atomic_exchange(type* atomic_obj, type desired, int mem_ord);
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]79
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]80<font color="#C80000">// type must be trivially copyable</font>
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]81<font color="#C80000">// Behavior is defined for mem_success = [0 ... 5],</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]82<font color="#C80000">// mem_falure &lt;= mem_success</font>
Howard Hinnantf6fe0842010-10-18 16:02:24 +0000[diff] [blame^]83<font color="#C80000">// mem_falure != 3</font>
84<font color="#C80000">// mem_falure != 4</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]85bool __atomic_compare_exchange_strong(type* atomic_obj,
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]86 type* expected, type desired,
87 int mem_success, int mem_failure);
88
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]89<font color="#C80000">// type must be trivially copyable</font>
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]90<font color="#C80000">// Behavior is defined for mem_success = [0 ... 5],</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]91<font color="#C80000">// mem_falure &lt;= mem_success</font>
Howard Hinnantf6fe0842010-10-18 16:02:24 +0000[diff] [blame^]92<font color="#C80000">// mem_falure != 3</font>
93<font color="#C80000">// mem_falure != 4</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]94bool __atomic_compare_exchange_weak(type* atomic_obj,
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]95 type* expected, type desired,
96 int mem_success, int mem_failure);
97
98<font color="#C80000">// type is one of: char, signed char, unsigned char, short, unsigned short, int,</font>
99<font color="#C80000">// unsigned int, long, unsigned long, long long, unsigned long long,</font>
100<font color="#C80000">// char16_t, char32_t, wchar_t</font>
101<font color="#C80000">// Behavior is defined for mem_ord = [0 ... 5]</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]102type __atomic_fetch_add(type* atomic_obj, type operand, int mem_ord);
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]103
104<font color="#C80000">// type is one of: char, signed char, unsigned char, short, unsigned short, int,</font>
105<font color="#C80000">// unsigned int, long, unsigned long, long long, unsigned long long,</font>
106<font color="#C80000">// char16_t, char32_t, wchar_t</font>
107<font color="#C80000">// Behavior is defined for mem_ord = [0 ... 5]</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]108type __atomic_fetch_sub(type* atomic_obj, type operand, int mem_ord);
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]109
110<font color="#C80000">// type is one of: char, signed char, unsigned char, short, unsigned short, int,</font>
111<font color="#C80000">// unsigned int, long, unsigned long, long long, unsigned long long,</font>
112<font color="#C80000">// char16_t, char32_t, wchar_t</font>
113<font color="#C80000">// Behavior is defined for mem_ord = [0 ... 5]</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]114type __atomic_fetch_and(type* atomic_obj, type operand, int mem_ord);
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]115
116<font color="#C80000">// type is one of: char, signed char, unsigned char, short, unsigned short, int,</font>
117<font color="#C80000">// unsigned int, long, unsigned long, long long, unsigned long long,</font>
118<font color="#C80000">// char16_t, char32_t, wchar_t</font>
119<font color="#C80000">// Behavior is defined for mem_ord = [0 ... 5]</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]120type __atomic_fetch_or(type* atomic_obj, type operand, int mem_ord);
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]121
122<font color="#C80000">// type is one of: char, signed char, unsigned char, short, unsigned short, int,</font>
123<font color="#C80000">// unsigned int, long, unsigned long, long long, unsigned long long,</font>
124<font color="#C80000">// char16_t, char32_t, wchar_t</font>
125<font color="#C80000">// Behavior is defined for mem_ord = [0 ... 5]</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]126type __atomic_fetch_xor(type* atomic_obj, type operand, int mem_ord);
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]127
128<font color="#C80000">// Behavior is defined for mem_ord = [0 ... 5]</font>
Howard Hinnant77868b92010-10-07 14:18:37 +0000[diff] [blame]129void* __atomic_fetch_add(void** atomic_obj, ptrdiff_t operand, int mem_ord);
130void* __atomic_fetch_sub(void** atomic_obj, ptrdiff_t operand, int mem_ord);
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]131
132<font color="#C80000">// Behavior is defined for mem_ord = [0 ... 5]</font>
133void __atomic_thread_fence(int mem_ord);
134void __atomic_signal_fence(int mem_ord);
135</pre></blockquote>
136
137<p>
138If desired the intrinsics taking a single <tt>mem_ord</tt> parameter can default
139this argument to 5.
140</p>
141
142<p>
143If desired the intrinsics taking two ordering parameters can default
Howard Hinnantf6fe0842010-10-18 16:02:24 +0000[diff] [blame^]144<tt>mem_success</tt> to 5, and <tt>mem_failure</tt> to
145<tt>translate_memory_order(mem_success)</tt> where
146<tt>translate_memory_order(mem_success)</tt> is defined as:
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]147</p>
148
Howard Hinnantf6fe0842010-10-18 16:02:24 +0000[diff] [blame^]149<blockquote><pre>
150int
151translate_memory_order(int o)
152{
153 switch (o)
154 {
155 case 4:
156 return 2;
157 case 3:
158 return 0;
159 }
160 return o;
161}
162</pre></blockquote>
Howard Hinnant086b7182010-10-06 16:15:10 +0000[diff] [blame]163</div>
164</body>
165</html>