STLdoc
STLdocumentation
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros
ConcurrencySal.h
Go to the documentation of this file.
1 /***
2 *concurrencysal.h - markers for documenting the concurrent semantics of APIs
3 *
4 * Copyright (c) Microsoft Corporation. All rights reserved.
5 *
6 *Purpose:
7 * This file contains macros for Concurrency SAL annotations. Definitions
8 * starting with _Internal are low level macros that are subject to change.
9 * Users should not use those low level macros directly.
10 * [ANSI]
11 *
12 * [Public]
13 *
14 ****/
15 
16 #ifndef CONCURRENCYSAL_H
17 #define CONCURRENCYSAL_H
18 
19 #pragma once
20 
21 #ifdef __cplusplus // [
22 extern "C" {
23 #endif // ]
24 
25 #if !defined(__midl) && defined(_PREFAST_) && !defined(_SDV_)
26 
27 __ANNOTATION(SAL_guarded_by(__deferTypecheck void *));
28 __ANNOTATION(SAL_write_guarded_by(__deferTypecheck void *));
29 __ANNOTATION(SAL_requires_lock_held(__deferTypecheck void *));
30 __ANNOTATION(SAL_requires_exclusive_lock_held(__deferTypecheck void *));
31 __ANNOTATION(SAL_requires_shared_lock_held(__deferTypecheck void *));
32 __ANNOTATION(SAL_requires_lock_not_held(__deferTypecheck void *));
33 __ANNOTATION(SAL_requires_no_locks_held(void));
34 __ANNOTATION(SAL_set_lock_count_to_zero(__deferTypecheck void *));
35 __ANNOTATION(SAL_set_lock_count_to_one(__deferTypecheck void *));
36 __ANNOTATION(SAL_acquires_lock(__deferTypecheck void *));
37 __ANNOTATION(SAL_acquires_exclusive_lock(__deferTypecheck void *));
38 __ANNOTATION(SAL_acquires_shared_lock(__deferTypecheck void *));
39 __ANNOTATION(SAL_releases_lock(__deferTypecheck void *));
40 __ANNOTATION(SAL_releases_exclusive_lock(__deferTypecheck void *));
41 __ANNOTATION(SAL_releases_shared_lock(__deferTypecheck void *));
42 __ANNOTATION(SAL_ignore_lock_match(__deferTypecheck void *));
43 __ANNOTATION(SAL_has_lock_property(__AuToQuOtE __In_impl_ char *));
44 __ANNOTATION(SAL_has_lock_level(__AuToQuOtE __In_impl_ char *));
45 __ANNOTATION(SAL_lock_level_order(__deferTypecheck void *, __deferTypecheck void *));
46 __ANNOTATION(SAL_no_competing_thread(void));
47 __ANNOTATION(SAL_set_same_lock(__deferTypecheck void *, __deferTypecheck void *));
48 
49 /*
50  * pre-defined global system locks
51  */
52 extern int _Global_interlock_;
53 extern int _Global_cancel_spin_lock_;
54 extern int _Global_critical_region_;
55 
56 /*
57  * Annotation identifiers
58  */
59 #define _Internal_create_CSAL_identifier_(id) const char id##[] = "";
60 
61 _Internal_create_CSAL_identifier_(_Lock_kind_mutex_)
62 _Internal_create_CSAL_identifier_(_Lock_kind_event_)
63 _Internal_create_CSAL_identifier_(_Lock_kind_semaphore_)
64 _Internal_create_CSAL_identifier_(_Lock_kind_spin_lock_)
65 _Internal_create_CSAL_identifier_(_Lock_kind_critical_section_)
66 
67 /*
68  * data protection
69  */
70 #define _Guarded_by_(lock) _SAL2_Source_(_Guarded_by_, (lock), _SA_annotes1(SAL_guarded_by,lock))
71 #define _Write_guarded_by_(lock) _SAL2_Source_(_Write_guarded_by_, (lock), _SA_annotes1(SAL_write_guarded_by,lock))
72 #define _Interlocked_ _Guarded_by_(_Global_interlock_)
73 
74 /*
75  * interlocked operand used in interlocked instructions
76  */
77 #ifndef _Interlocked_operand_
78 #define _Interlocked_operand_ _SAL2_Source_(_Interlocked_operand_, (), _Pre_ _SA_annotes0(SAL_interlocked))
79 #endif
80 
81 /*
82  * caller/callee locking contracts
83  */
84 #define _Requires_lock_held_(lock) _SAL2_Source_(_Requires_lock_held_, (lock), _Pre_ _SA_annotes1(SAL_requires_lock_held,lock))
85 #define _Requires_exclusive_lock_held_(lock) _SAL2_Source_(_Requires_exclusive_lock_held_, (lock), _Pre_ _SA_annotes1(SAL_requires_exclusive_lock_held,lock))
86 #define _Requires_shared_lock_held_(lock) _SAL2_Source_(_Requires_shared_lock_held_, (lock), _Pre_ _SA_annotes1(SAL_requires_shared_lock_held,lock))
87 
88 #define _Requires_lock_not_held_(lock) _SAL2_Source_(_Requires_lock_not_held_, (lock), _Pre_ _SA_annotes1(SAL_requires_lock_not_held,lock))
89 #define _Requires_no_locks_held_ _SAL2_Source_(_Requires_no_locks_held_, (), _Pre_ _SA_annotes0(SAL_requires_no_locks_held))
90 
91 /*
92  * acquire/release locking side effects
93  */
94 #define _Acquires_lock_(lock) _SAL2_Source_(_Acquires_lock_, (lock), _Post_ _SA_annotes1(SAL_acquires_lock,lock))
95 #define _Acquires_exclusive_lock_(lock) _SAL2_Source_(_Acquires_exclusive_lock_, (lock), _Post_ _SA_annotes1(SAL_acquires_exclusive_lock,lock))
96 #define _Acquires_shared_lock_(lock) _SAL2_Source_(_Acquires_shared_lock_, (lock), _Post_ _SA_annotes1(SAL_acquires_shared_lock,lock))
97 
98 #define _Releases_lock_(lock) _SAL2_Source_(_Releases_lock_, (lock), _Post_ _SA_annotes1(SAL_releases_lock,lock))
99 #define _Releases_exclusive_lock_(lock) _SAL2_Source_(_Releases_exclusive_lock_, (lock), _Post_ _SA_annotes1(SAL_releases_exclusive_lock,lock))
100 #define _Releases_shared_lock_(lock) _SAL2_Source_(_Releases_shared_lock_, (lock), _Post_ _SA_annotes1(SAL_releases_shared_lock,lock))
101 
102 /*
103  * acquire/release locking side effects for non-reentrant locks
104  */
105 #define _Acquires_nonreentrant_lock_(lock) \
106  _SAL2_Source_(_Acquires_nonreentrant_lock_, (lock), \
107  _Requires_lock_not_held_(lock) \
108  _Acquires_lock_(lock))
109 
110 #define _Releases_nonreentrant_lock_(lock) \
111  _SAL2_Source_(_Releases_nonreentrant_lock_, (lock), \
112  _Requires_lock_held_(lock) \
113  _Releases_lock_(lock))
114 
115 #define _Post_same_lock_(a,b) _SAL2_Source_(_Post_same_lock_, (a,b), _Post_ _SA_annotes2(SAL_set_same_lock,a,b))
116 
117 /*
118  * lock level
119  */
120 #define _Create_lock_level_(level) _Internal_create_CSAL_identifier_(level)
121 
122 #define _Has_lock_level_(level) _SAL2_Source_(_Has_lock_level_, (level), _SA_annotes1(SAL_has_lock_level,#level))
123 
124 #define _Internal_lock_level_order_(a,b) _SAL2_Source_(_Internal_lock_level_order_, (a,b), _SA_annotes2(SAL_lock_level_order,a,b))
125 #define _Csalcat1_(x,y) x##y
126 #define _Csalcat2_(x,y) _Csalcat1_(x,y)
127 
128 #define _Lock_level_order_(a,b) \
129  extern _Internal_lock_level_order_(a,b) void _Sal_order_##a##_##b(_In_z_ char*a, _In_z_ char*b); \
130  static __inline void CSALCAT2(CSAL_LockOrder,__COUNTER__)(void){_Sal_order_##a##_##b(#a,#b);}
131 
132 /*
133  * threading context
134  */
135 #define _No_competing_thread_ _SAL2_Source_(_No_competing_thread_, (), _Pre_ _SA_annotes0(SAL_no_competing_thread))
136 
137 /*
138  * refinement and suppression
139  */
140 extern _Acquires_lock_(*plock) void _Internal_acquires_lock_(void* plock);
141 extern _Releases_lock_(*plock) void _Internal_releases_lock_(void* plock);
142 
143 #define _Internal_set_lock_count_to_zero_(lock) _SAL2_Source_(Internal_set_lock_count_to_zero_, (lock), _Post_ _SA_annotes1(SAL_set_lock_count_to_zero,lock))
144 #define _Internal_set_lock_count_to_one_(lock) _SAL2_Source_(_Internal_set_lock_count_to_one_, (lock), _Post_ _SA_annotes1(SAL_set_lock_count_to_one,lock))
145 
146 extern _Internal_set_lock_count_to_one_(*plock) void _Internal_lock_held_(void* plock);
147 extern _Internal_set_lock_count_to_zero_(*plock) void _Internal_lock_not_held_(void* plock);
148 extern _Post_same_lock_(*plock1, *plock2) void _Internal_same_lock_(void* plock1, void* plock2);
149 
150 #define _Analysis_assume_lock_acquired_(lock) _Internal_acquires_lock_((void*)(&(lock)))
151 #define _Analysis_assume_lock_released_(lock) _Internal_releases_lock_((void*)(&(lock)))
152 
153 #define _Analysis_assume_lock_held_(lock) _Internal_lock_held_((void*)(&(lock)))
154 #define _Analysis_assume_lock_not_held_(lock) _Internal_lock_not_held_((void*)(&(lock)))
155 #define _Analysis_assume_same_lock_(lock1, lock2) _Internal_same_lock_((void*)(&(lock1)), (void*)(&(lock2)))
156 
157 /*
158  * _Function_ignore_lock_checking_ may be deprecated in future versions of SAL
159  */
160 #define _Function_ignore_lock_checking_(lock) _SAL2_Source_(_Function_ignore_lock_checking_, (lock), _Pre_ _SA_annotes1(SAL_ignore_lock_match,lock))
161 extern _Function_ignore_lock_checking_(*plock) void _Internal_suppress_lock_checking_(void* plock);
162 
163 /*
164  * _Analysis_suppress_lock_checking_ may be deprecated in future versions of SAL
165  */
166 #define _Analysis_suppress_lock_checking_(lock) _Internal_suppress_lock_checking_((void*)(&(lock)));
167 
168 #define _Benign_race_begin_ __pragma(warning(push)) __pragma(warning(disable:26100 26101 26150 26130 26180 26131 26181 28112))
169 #define _Benign_race_end_ __pragma(warning(pop))
170 
171 #define _No_competing_thread_begin_ __pragma(warning(push)) __pragma(warning(disable:26100 26101 26150 26101 26151 26110 26160 26130 26180 26131 26181 28112))
172 #define _No_competing_thread_end_ __pragma(warning(pop))
173 
174 /*
175  * lock kinds
176  */
177 #define _Has_lock_kind_(kind) _SAL2_Source_(_Has_lock_kind_, (kind), _SA_annotes1(SAL_has_lock_property,#kind))
178 
179 
180 /*
181  * Old spelling
182  * Note: the old version may be deprecated in the future!!!
183  */
184 extern int __system_interlock;
185 extern int __system_cancel_spinlock;
186 extern int __system_critical_region;
187 
188 #define __guarded_by(lock) _SAL1_1_Source_(__guarded_by, (lock), _SA_annotes1(SAL_guarded_by,lock))
189 #define __write_guarded_by(lock) _SAL1_1_Source_(__write_guarded_by, (lock), _SA_annotes1(SAL_write_guarded_by,lock))
190 #define __interlocked __guarded_by(_Global_interlock_)
191 
192 /*
193  * caller/callee locking contracts
194  */
195 #define __requires_lock_held(lock) _SAL1_1_Source_(__requires_lock_held, (lock), __pre _SA_annotes1(SAL_requires_lock_held,lock))
196 #define __requires_exclusive_lock_held(lock) _SAL1_1_Source_(__requires_exclusive_lock_held, (lock), __pre _SA_annotes1(SAL_requires_exclusive_lock_held,lock))
197 #define __requires_shared_lock_held(lock) _SAL1_1_Source_(__requires_shared_lock_held, (lock), __pre _SA_annotes1(SAL_requires_shared_lock_held,lock))
198 
199 #define __requires_lock_not_held(lock) _SAL1_1_Source_(__requires_lock_not_held, (lock), __pre _SA_annotes1(SAL_requires_lock_not_held,lock))
200 #define __requires_no_locks_held _SAL1_1_Source_(__requires_no_locks_held, (), __pre _SA_annotes0(SAL_requires_no_locks_held))
201 
202 /*
203  * acquire/release locking side effects
204  */
205 #define __acquires_lock(lock) _SAL1_1_Source_(__acquires_lock, (lock), __post _SA_annotes1(SAL_acquires_lock,lock))
206 #define __acquires_exclusive_lock(lock) _SAL1_1_Source_(__acquires_exclusive_lock, (lock), __post _SA_annotes1(SAL_acquires_exclusive_lock,lock))
207 #define __acquires_shared_lock(lock) _SAL1_1_Source_(__acquires_shared_lock, (lock), __post _SA_annotes1(SAL_acquires_shared_lock,lock))
208 
209 #define __releases_lock(lock) _SAL1_1_Source_(__releases_lock, (lock), __post _SA_annotes1(SAL_releases_lock,lock))
210 #define __releases_exclusive_lock(lock) _SAL1_1_Source_(__releases_exclusive_lock, (lock),__post _SA_annotes1(SAL_releases_exclusive_lock,lock))
211 #define __releases_shared_lock(lock) _SAL1_1_Source_(__releases_shared_lock, (lock), __post _SA_annotes1(SAL_releases_shared_lock,lock))
212 
213 /*
214  * lock properties
215  * The following kind options are supported:
216  * __has_lock_property(MUTEX)
217  * __has_lock_property(EVENT)
218  * __has_lock_property(SEMAPHORE)
219  * __has_lock_property(OTHER_HANDLE)
220  * __has_lock_property(REENTRANT)
221  * __has_lock_property(NON_REENTRANT)
222  */
223 #define __has_lock_property(kind) _SAL1_1_Source_(__has_lock_property, (kind), _SA_annotes1(SAL_has_lock_property,#kind))
224 
225 /*
226  * lock level
227  */
228 #define __declare_lock_level(level) _Internal_create_CSAL_identifier_(level)
229 #define __has_lock_level(level) _SAL1_1_Source_(__has_lock_level, (level), _SA_annotes1(SAL_has_lock_level,#level))
230 
231 #define __internal_lock_level_order(a,b) _SAL1_1_Source_(__internal_lock_level_order, (a,b), _SA_annotes2(SAL_lock_level_order,#a,#b))
232 #define CSALCAT1(x,y) x##y
233 #define CSALCAT2(x,y) CSALCAT1(x,y)
234 
235 #define __lock_level_order(a,b) \
236  extern __internal_lock_level_order(a,b) void __sal_order_##a##_##b(__in_z char*a, __in_z char*b); \
237  static __inline void CSALCAT2(CSAL_LockOrder,__COUNTER__)(void){__sal_order_##a##_##b(#a,#b);}
238 
239 /*
240  * threading context
241  */
242 #define __no_competing_thread _SAL1_1_Source_(__no_competing_thread, (), __pre _SA_annotes0(SAL_no_competing_thread))
243 
244 /*
245  * refinement and suppression
246  */
247 extern __acquires_lock(*plock) void __internal_acquires_lock(void* plock);
248 extern __releases_lock(*plock) void __internal_releases_lock(void* plock);
249 
250 #define __analysis_assume_lock_acquired(lock) __internal_acquires_lock((void*)(&(lock)))
251 #define __analysis_assume_lock_released(lock) __internal_releases_lock((void*)(&(lock)))
252 
253 #define __function_ignore_lock_checking(lock) _SAL1_1_Source_(__function_ignore_lock_cleanup, (lock), __pre _SA_annotes1(SAL_ignore_lock_match,lock))
254 extern __function_ignore_lock_checking(*plock) void __internal_suppress_lock_checking(void* plock);
255 
256 #define __analysis_suppress_lock_checking(lock) __internal_suppress_lock_checking((void*)(&(lock)));
257 
258 #define BENIGN_RACE_BEGIN __pragma(warning(push)) __pragma(warning(disable:26100 26150 26130 26180 26131 26181))
259 #define BENIGN_RACE_END __pragma(warning(pop))
260 
261 #define NO_COMPETING_THREAD_BEGIN __pragma(warning(push)) __pragma(warning(disable:26100 26150 26101 26151 26110 26160 26130 26180 26131 26181))
262 #define NO_COMPETING_THREAD_END __pragma(warning(pop))
263 
264 #else
265 
266 #ifndef _Interlocked_operand_
267 #define _Interlocked_operand_
268 #endif
269 
270 #define _Guarded_by_(lock)
271 #define _Write_guarded_by_(lock)
272 #define _Interlocked_
273 #define _Requires_lock_held_(lock)
274 #define _Requires_exclusive_lock_held_(lock)
275 #define _Requires_shared_lock_held_(lock)
276 #define _Requires_lock_not_held_(lock)
277 #define _Requires_no_locks_held_
278 #define _Acquires_lock_(lock)
279 #define _Acquires_exclusive_lock_(lock)
280 #define _Acquires_shared_lock_(lock)
281 #define _Releases_lock_(lock)
282 #define _Releases_exclusive_lock_(lock)
283 #define _Releases_shared_lock_(lock)
284 #define _Acquires_nonreentrant_lock_(lock)
285 #define _Releases_nonreentrant_lock_(lock)
286 
287 #define _Post_same_lock_(lock1,lock2)
288 
289 #define _Internal_set_lock_count_(lock, count)
290 
291 #define _Create_lock_level_(level)
292 #define _Has_lock_level_(level)
293 #define _Internal_lock_level_order_(a,b)
294 #define _Csalcat1_(x,y)
295 #define _Csalcat2_(x,y)
296 #define _Lock_level_order_(a,b)
297 #define _No_competing_thread_
298 #define _Analysis_assume_lock_acquired_(lock)
299 #define _Analysis_assume_lock_released_(lock)
300 #define _Analysis_assume_lock_held_(lock)
301 #define _Analysis_assume_lock_not_held_(lock)
302 #define _Analysis_assume_same_lock_(lock1, lock2)
303 #define _Function_ignore_lock_checking_(lock)
304 #define _Analysis_suppress_lock_checking_(lock)
305 
306 #define _Benign_race_begin_ __pragma(warning(push))
307 #define _Benign_race_end_ __pragma(warning(pop))
308 
309 #define _No_competing_thread_begin_ __pragma(warning(push))
310 #define _No_competing_thread_end_ __pragma(warning(pop))
311 
312 #define _Has_lock_kind_(kind)
313 
314 /*
315  * Old spelling: will be deprecated
316  */
317 #define __guarded_by(lock)
318 #define __write_guarded_by(lock)
319 #define __interlocked
320 #define __requires_lock_held(lock)
321 #define __requires_exclusive_lock_held(lock)
322 #define __requires_shared_lock_held(lock)
323 #define __requires_lock_not_held(lock)
324 #define __requires_no_locks_held
325 #define __acquires_lock(lock)
326 #define __acquires_exclusive_lock(lock)
327 #define __acquires_shared_lock(lock)
328 #define __releases_lock(lock)
329 #define __releases_exclusive_lock(lock)
330 #define __releases_shared_lock(lock)
331 
332 #define __has_lock_property(kind)
333 #define __declare_lock_level(level)
334 #define __has_lock_level(level)
335 #define __internal_lock_level_order(a,b)
336 #define CSALCAT1(x,y)
337 #define CSALCAT2(x,y)
338 #define __lock_level_order(a,b)
339 #define __no_competing_thread
340 #define __analysis_assume_lock_acquired(lock)
341 #define __analysis_assume_lock_released(lock)
342 #define __function_ignore_lock_checking(lock)
343 #define __analysis_suppress_lock_checking(lock)
344 
345 #define BENIGN_RACE_BEGIN __pragma(warning(push))
346 #define BENIGN_RACE_END __pragma(warning(pop))
347 
348 #define NO_COMPETING_THREAD_BEGIN __pragma(warning(push))
349 #define NO_COMPETING_THREAD_END __pragma(warning(pop))
350 
351 #endif
352 
353 #ifdef __cplusplus
354 }
355 #endif
356 
357 #endif // CONCURRENCYSAL_H
#define __releases_lock(lock)
Definition: ConcurrencySal.h:328
#define _Releases_lock_(lock)
Definition: ConcurrencySal.h:281
#define __ANNOTATION(fun)
Definition: sal.h:1619
#define _Acquires_lock_(lock)
Definition: ConcurrencySal.h:278
#define __acquires_lock(lock)
Definition: ConcurrencySal.h:325
#define _Post_same_lock_(lock1, lock2)
Definition: ConcurrencySal.h:287
_CRT_BEGIN_C_HEADER typedef void(__CRTDECL *unexpected_handler)()
#define __function_ignore_lock_checking(lock)
Definition: ConcurrencySal.h:342
#define _Function_ignore_lock_checking_(lock)
Definition: ConcurrencySal.h:303