[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_atomic.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      Declaration of atomic manipulation functions.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_ATOMIC_H_\r
44 #define _CL_ATOMIC_H_\r
45 \r
46 \r
47 #include <complib/cl_atomic_osd.h>\r
48 \r
49 \r
50 /****h* Component Library/Atomic Operations\r
51 * NAME\r
52 *       Atomic Operations\r
53 *\r
54 * DESCRIPTION\r
55 *       The Atomic Operations functions allow callers to operate on\r
56 *       32-bit signed integers in an atomic fashion.\r
57 *********/\r
58 \r
59 \r
60 #ifdef __cplusplus\r
61 extern "C"\r
62 {\r
63 #endif\r
64 \r
65 \r
66 /****f* Component Library: Atomic Operations/cl_atomic_inc\r
67 * NAME\r
68 *       cl_atomic_inc\r
69 *\r
70 * DESCRIPTION\r
71 *       The cl_atomic_inc function atomically increments a 32-bit signed\r
72 *       integer and returns the incremented value.\r
73 *\r
74 * SYNOPSIS\r
75 */\r
76 CL_EXPORT int32_t CL_API\r
77 cl_atomic_inc(\r
78         IN      atomic32_t* const       p_value );\r
79 /*\r
80 * PARAMETERS\r
81 *       p_value\r
82 *               [in] Pointer to a 32-bit integer to increment.\r
83 *\r
84 * RETURN VALUE\r
85 *       Returns the incremented value pointed to by p_value.\r
86 *\r
87 * NOTES\r
88 *       The provided value is incremented and its value returned in one atomic\r
89 *       operation.\r
90 *\r
91 *       cl_atomic_inc maintains data consistency without requiring additional\r
92 *       synchronization mechanisms in multi-threaded environments.\r
93 *\r
94 * SEE ALSO\r
95 *       Atomic Operations, cl_atomic_dec, cl_atomic_add, cl_atomic_sub,\r
96 *       cl_atomic_xchg, cl_atomic_comp_xchg\r
97 *********/\r
98 \r
99 \r
100 /****f* Component Library: Atomic Operations/cl_atomic_dec\r
101 * NAME\r
102 *       cl_atomic_dec\r
103 *\r
104 * DESCRIPTION\r
105 *       The cl_atomic_dec function atomically decrements a 32-bit signed\r
106 *       integer and returns the decremented value.\r
107 *\r
108 * SYNOPSIS\r
109 */\r
110 CL_EXPORT int32_t CL_API\r
111 cl_atomic_dec(\r
112         IN      atomic32_t* const       p_value );\r
113 /*\r
114 * PARAMETERS\r
115 *       p_value\r
116 *               [in] Pointer to a 32-bit integer to decrement.\r
117 *\r
118 * RETURN VALUE\r
119 *       Returns the decremented value pointed to by p_value.\r
120 *\r
121 * NOTES\r
122 *       The provided value is decremented and its value returned in one atomic\r
123 *       operation.\r
124 *\r
125 *       cl_atomic_dec maintains data consistency without requiring additional\r
126 *       synchronization mechanisms in multi-threaded environments.\r
127 *\r
128 * SEE ALSO\r
129 *       Atomic Operations, cl_atomic_inc, cl_atomic_add, cl_atomic_sub,\r
130 *       cl_atomic_xchg, cl_atomic_comp_xchg\r
131 *********/\r
132 \r
133 \r
134 /****f* Component Library: Atomic Operations/cl_atomic_add\r
135 * NAME\r
136 *       cl_atomic_add\r
137 *\r
138 * DESCRIPTION\r
139 *       The cl_atomic_add function atomically adds a value to a\r
140 *       32-bit signed integer and returns the resulting value.\r
141 *\r
142 * SYNOPSIS\r
143 */\r
144 CL_EXPORT int32_t CL_API\r
145 cl_atomic_add(\r
146         IN      atomic32_t* const       p_value,\r
147         IN      const int32_t           increment );\r
148 /*\r
149 * PARAMETERS\r
150 *       p_value\r
151 *               [in] Pointer to a 32-bit integer that will be added to.\r
152 *\r
153 *       increment\r
154 *               [in] Value by which to increment the integer pointed to by p_value.\r
155 *\r
156 * RETURN VALUE\r
157 *       Returns the value pointed to by p_value after the addition.\r
158 *\r
159 * NOTES\r
160 *       The provided increment is added to the value and the result returned in\r
161 *       one atomic operation.\r
162 *\r
163 *       cl_atomic_add maintains data consistency without requiring additional\r
164 *       synchronization mechanisms in multi-threaded environments.\r
165 *\r
166 * SEE ALSO\r
167 *       Atomic Operations, cl_atomic_inc, cl_atomic_dec, cl_atomic_sub,\r
168 *       cl_atomic_xchg, cl_atomic_comp_xchg\r
169 *********/\r
170 \r
171 \r
172 /****f* Component Library: Atomic Operations/cl_atomic_sub\r
173 * NAME\r
174 *       cl_atomic_sub\r
175 *\r
176 * DESCRIPTION\r
177 *       The cl_atomic_sub function atomically subtracts a value from a\r
178 *       32-bit signed integer and returns the resulting value.\r
179 *\r
180 * SYNOPSIS\r
181 */\r
182 CL_EXPORT int32_t CL_API\r
183 cl_atomic_sub(\r
184         IN      atomic32_t* const       p_value,\r
185         IN      const int32_t           decrement );\r
186 /*\r
187 * PARAMETERS\r
188 *       p_value\r
189 *               [in] Pointer to a 32-bit integer that will be subtracted from.\r
190 *\r
191 *       decrement\r
192 *               [in] Value by which to decrement the integer pointed to by p_value.\r
193 *\r
194 * RETURN VALUE\r
195 *       Returns the value pointed to by p_value after the subtraction.\r
196 *\r
197 * NOTES\r
198 *       The provided decrement is subtracted from the value and the result\r
199 *       returned in one atomic operation.\r
200 *\r
201 *       cl_atomic_sub maintains data consistency without requiring additional\r
202 *       synchronization mechanisms in multi-threaded environments.\r
203 *\r
204 * SEE ALSO\r
205 *       Atomic Operations, cl_atomic_inc, cl_atomic_dec, cl_atomic_add,\r
206 *       cl_atomic_xchg, cl_atomic_comp_xchg\r
207 *********/\r
208 \r
209 \r
210 /****f* Component Library: Atomic Operations/cl_atomic_xchg\r
211 * NAME\r
212 *       cl_atomic_xchg\r
213 *\r
214 * DESCRIPTION\r
215 *       The cl_atomic_xchg function atomically sets a value of a\r
216 *       32-bit signed integer and returns the initial value.\r
217 *\r
218 * SYNOPSIS\r
219 */\r
220 CL_EXPORT int32_t CL_API\r
221 cl_atomic_xchg(\r
222         IN      atomic32_t* const       p_value,\r
223         IN      const int32_t           new_value );\r
224 /*\r
225 * PARAMETERS\r
226 *       p_value\r
227 *               [in] Pointer to a 32-bit integer to exchange with new_value.\r
228 *\r
229 *       new_value\r
230 *               [in] Value to assign.\r
231 *\r
232 * RETURN VALUE\r
233 *       Returns the initial value pointed to by p_value.\r
234 *\r
235 * NOTES\r
236 *       The provided value is exchanged with new_value and its initial value\r
237 *       returned in one atomic operation.\r
238 *\r
239 *       cl_atomic_xchg maintains data consistency without requiring additional\r
240 *       synchronization mechanisms in multi-threaded environments.\r
241 *\r
242 * SEE ALSO\r
243 *       Atomic Operations, cl_atomic_inc, cl_atomic_dec, cl_atomic_add,\r
244 *       cl_atomic_sub, cl_atomic_comp_xchg\r
245 *********/\r
246 \r
247 \r
248 /****f* Component Library: Atomic Operations/cl_atomic_comp_xchg\r
249 * NAME\r
250 *       cl_atomic_comp_xchg\r
251 *\r
252 * DESCRIPTION\r
253 *       The cl_atomic_comp_xchg function atomically compares a 32-bit signed\r
254 *       integer to a desired value, sets that integer to the\r
255 *       specified value if equal, and returns the initial value.\r
256 *\r
257 * SYNOPSIS\r
258 */\r
259 CL_EXPORT int32_t CL_API\r
260 cl_atomic_comp_xchg(\r
261         IN      atomic32_t* const       p_value,\r
262         IN      const int32_t           compare,\r
263         IN      const int32_t           new_value );\r
264 /*\r
265 * PARAMETERS\r
266 *       p_value\r
267 *               [in] Pointer to a 32-bit integer to exchange with new_value.\r
268 *\r
269 *       compare\r
270 *               [in] Value to compare to the value pointed to by p_value.\r
271 *\r
272 *       new_value\r
273 *               [in] Value to assign if the value pointed to by p_value is equal to\r
274 *               the value specified by the compare parameter.\r
275 *\r
276 * RETURN VALUE\r
277 *       Returns the initial value of the variable pointed to by p_value.\r
278 *\r
279 * NOTES\r
280 *       The value pointed to by p_value is compared to the value specified by the\r
281 *       compare parameter.  If the two values are equal, the p_value variable is\r
282 *       set to new_value.  The initial value pointed to by p_value is returned.\r
283 *\r
284 *       cl_atomic_comp_xchg maintains data consistency without requiring additional\r
285 *       synchronization mechanisms in multi-threaded environments.\r
286 *\r
287 * SEE ALSO\r
288 *       Atomic Operations, cl_atomic_inc, cl_atomic_dec, cl_atomic_add,\r
289 *       cl_atomic_sub, cl_atomic_xchg\r
290 *********/\r
291 \r
292 \r
293 #ifdef __cplusplus\r
294 }       /* extern "C" */\r
295 #endif\r
296 \r
297 #endif /* _CL_ATOMIC_H_ */\r