1 /*
2 Copyright (c) 2005-2021 Intel Corporation
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16
17 #ifndef _ITTNOTIFY_H_
18 #define _ITTNOTIFY_H_
19
20 /**
21 @file
22 @brief Public User API functions and types
23 @mainpage
24
25 The Instrumentation and Tracing Technology API (ITT API) is used to
26 annotate a user's program with additional information
27 that can be used by correctness and performance tools. The user inserts
28 calls in their program. Those calls generate information that is collected
29 at runtime, and used by Intel(R) Threading Tools.
30
31 @section API Concepts
32 The following general concepts are used throughout the API.
33
34 @subsection Unicode Support
35 Many API functions take character string arguments. On Windows, there
36 are two versions of each such function. The function name is suffixed
37 by W if Unicode support is enabled, and by A otherwise. Any API function
38 that takes a character string argument adheres to this convention.
39
40 @subsection Conditional Compilation
41 Many users prefer having an option to modify ITT API code when linking it
42 inside their runtimes. ITT API header file provides a mechanism to replace
43 ITT API function names inside your code with empty strings. To do this,
44 define the macros INTEL_NO_ITTNOTIFY_API during compilation and remove the
45 static library from the linker script.
46
47 @subsection Domains
48 [see domains]
49 Domains provide a way to separate notification for different modules or
50 libraries in a program. Domains are specified by dotted character strings,
51 e.g. TBB.Internal.Control.
52
53 A mechanism (to be specified) is provided to enable and disable
54 domains. By default, all domains are enabled.
55 @subsection Named Entities and Instances
56 Named entities (frames, regions, tasks, and markers) communicate
57 information about the program to the analysis tools. A named entity often
58 refers to a section of program code, or to some set of logical concepts
59 that the programmer wants to group together.
60
61 Named entities relate to the programmer's static view of the program. When
62 the program actually executes, many instances of a given named entity
63 may be created.
64
65 The API annotations denote instances of named entities. The actual
66 named entities are displayed using the analysis tools. In other words,
67 the named entities come into existence when instances are created.
68
69 Instances of named entities may have instance identifiers (IDs). Some
70 API calls use instance identifiers to create relationships between
71 different instances of named entities. Other API calls associate data
72 with instances of named entities.
73
74 Some named entities must always have instance IDs. In particular, regions
75 and frames always have IDs. Task and markers need IDs only if the ID is
76 needed in another API call (such as adding a relation or metadata).
77
78 The lifetime of instance IDs is distinct from the lifetime of
79 instances. This allows various relationships to be specified separate
80 from the actual execution of instances. This flexibility comes at the
81 expense of extra API calls.
82
83 The same ID may not be reused for different instances, unless a previous
84 [ref] __itt_id_destroy call for that ID has been issued.
85 */
86
87 /** @cond exclude_from_documentation */
88 #ifndef ITT_OS_WIN
89 # define ITT_OS_WIN 1
90 #endif /* ITT_OS_WIN */
91
92 #ifndef ITT_OS_LINUX
93 # define ITT_OS_LINUX 2
94 #endif /* ITT_OS_LINUX */
95
96 #ifndef ITT_OS_MAC
97 # define ITT_OS_MAC 3
98 #endif /* ITT_OS_MAC */
99
100 #ifndef ITT_OS_FREEBSD
101 # define ITT_OS_FREEBSD 4
102 #endif /* ITT_OS_FREEBSD */
103
104 #ifndef ITT_OS
105 # if defined WIN32 || defined _WIN32
106 # define ITT_OS ITT_OS_WIN
107 # elif defined( __APPLE__ ) && defined( __MACH__ )
108 # define ITT_OS ITT_OS_MAC
109 # elif defined( __FreeBSD__ ) || defined(__DragonFly__)
110 # define ITT_OS ITT_OS_FREEBSD
111 # else
112 # define ITT_OS ITT_OS_LINUX
113 # endif
114 #endif /* ITT_OS */
115
116 #ifndef ITT_PLATFORM_WIN
117 # define ITT_PLATFORM_WIN 1
118 #endif /* ITT_PLATFORM_WIN */
119
120 #ifndef ITT_PLATFORM_POSIX
121 # define ITT_PLATFORM_POSIX 2
122 #endif /* ITT_PLATFORM_POSIX */
123
124 #ifndef ITT_PLATFORM_MAC
125 # define ITT_PLATFORM_MAC 3
126 #endif /* ITT_PLATFORM_MAC */
127
128 #ifndef ITT_PLATFORM_FREEBSD
129 # define ITT_PLATFORM_FREEBSD 4
130 #endif /* ITT_PLATFORM_FREEBSD */
131
132 #ifndef ITT_PLATFORM
133 # if ITT_OS==ITT_OS_WIN
134 # define ITT_PLATFORM ITT_PLATFORM_WIN
135 # elif ITT_OS==ITT_OS_MAC
136 # define ITT_PLATFORM ITT_PLATFORM_MAC
137 # elif ITT_OS==ITT_OS_FREEBSD
138 # define ITT_PLATFORM ITT_PLATFORM_FREEBSD
139 # else
140 # define ITT_PLATFORM ITT_PLATFORM_POSIX
141 # endif
142 #endif /* ITT_PLATFORM */
143
144 #if defined(_UNICODE) && !defined(UNICODE)
145 #define UNICODE
146 #endif
147
148 #include <stddef.h>
149 #if ITT_PLATFORM==ITT_PLATFORM_WIN
150 #include <tchar.h>
151 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
152 #include <stdint.h>
153 #if defined(UNICODE) || defined(_UNICODE)
154 #include <wchar.h>
155 #endif /* UNICODE || _UNICODE */
156 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
157
158 #ifndef ITTAPI_CDECL
159 # if ITT_PLATFORM==ITT_PLATFORM_WIN
160 # define ITTAPI_CDECL __cdecl
161 # else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
162 # if defined _M_IX86 || defined __i386__
163 # define ITTAPI_CDECL __attribute__ ((cdecl))
164 # else /* _M_IX86 || __i386__ */
165 # define ITTAPI_CDECL /* actual only on x86 platform */
166 # endif /* _M_IX86 || __i386__ */
167 # endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
168 #endif /* ITTAPI_CDECL */
169
170 #ifndef STDCALL
171 # if ITT_PLATFORM==ITT_PLATFORM_WIN
172 # define STDCALL __stdcall
173 # else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
174 # if defined _M_IX86 || defined __i386__
175 # define STDCALL __attribute__ ((stdcall))
176 # else /* _M_IX86 || __i386__ */
177 # define STDCALL /* supported only on x86 platform */
178 # endif /* _M_IX86 || __i386__ */
179 # endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
180 #endif /* STDCALL */
181
182 #define ITTAPI ITTAPI_CDECL
183 #define LIBITTAPI ITTAPI_CDECL
184
185 /* TODO: Temporary for compatibility! */
186 #define ITTAPI_CALL ITTAPI_CDECL
187 #define LIBITTAPI_CALL ITTAPI_CDECL
188
189 #if ITT_PLATFORM==ITT_PLATFORM_WIN
190 /* use __forceinline (VC++ specific) */
191 #define ITT_INLINE static __forceinline
192 #define ITT_INLINE_ATTRIBUTE /* nothing */
193 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
194 /*
195 * Generally, functions are not inlined unless optimization is specified.
196 * For functions declared inline, this attribute inlines the function even
197 * if no optimization level was specified.
198 */
199 #ifdef __STRICT_ANSI__
200 #define ITT_INLINE static
201 #define ITT_INLINE_ATTRIBUTE __attribute__((unused))
202 #else /* __STRICT_ANSI__ */
203 #define ITT_INLINE static inline
204 #define ITT_INLINE_ATTRIBUTE __attribute__((always_inline, unused))
205 #endif /* __STRICT_ANSI__ */
206 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
207 /** @endcond */
208
209 #ifdef INTEL_ITTNOTIFY_ENABLE_LEGACY
210 # if ITT_PLATFORM==ITT_PLATFORM_WIN
211 # pragma message("WARNING!!! Deprecated API is used. Please undefine INTEL_ITTNOTIFY_ENABLE_LEGACY macro")
212 # else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
213 # warning "Deprecated API is used. Please undefine INTEL_ITTNOTIFY_ENABLE_LEGACY macro"
214 # endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
215 # include "legacy/ittnotify.h"
216 #endif /* INTEL_ITTNOTIFY_ENABLE_LEGACY */
217
218 /** @cond exclude_from_documentation */
219 /* Helper macro for joining tokens */
220 #define ITT_JOIN_AUX(p,n) p##n
221 #define ITT_JOIN(p,n) ITT_JOIN_AUX(p,n)
222
223 #ifdef ITT_MAJOR
224 #undef ITT_MAJOR
225 #endif
226 #ifdef ITT_MINOR
227 #undef ITT_MINOR
228 #endif
229 #define ITT_MAJOR 3
230 #define ITT_MINOR 0
231
232 /* Standard versioning of a token with major and minor version numbers */
233 #define ITT_VERSIONIZE(x) \
234 ITT_JOIN(x, \
235 ITT_JOIN(_, \
236 ITT_JOIN(ITT_MAJOR, \
237 ITT_JOIN(_, ITT_MINOR))))
238
239 #ifndef INTEL_ITTNOTIFY_PREFIX
240 # define INTEL_ITTNOTIFY_PREFIX __itt_
241 #endif /* INTEL_ITTNOTIFY_PREFIX */
242 #ifndef INTEL_ITTNOTIFY_POSTFIX
243 # define INTEL_ITTNOTIFY_POSTFIX _ptr_
244 #endif /* INTEL_ITTNOTIFY_POSTFIX */
245
246 #define ITTNOTIFY_NAME_AUX(n) ITT_JOIN(INTEL_ITTNOTIFY_PREFIX,n)
247 #define ITTNOTIFY_NAME(n) ITT_VERSIONIZE(ITTNOTIFY_NAME_AUX(ITT_JOIN(n,INTEL_ITTNOTIFY_POSTFIX)))
248
249 #define ITTNOTIFY_VOID(n) (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)
250 #define ITTNOTIFY_DATA(n) (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)
251
252 #define ITTNOTIFY_VOID_D0(n,d) (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d)
253 #define ITTNOTIFY_VOID_D1(n,d,x) (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x)
254 #define ITTNOTIFY_VOID_D2(n,d,x,y) (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y)
255 #define ITTNOTIFY_VOID_D3(n,d,x,y,z) (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y,z)
256 #define ITTNOTIFY_VOID_D4(n,d,x,y,z,a) (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y,z,a)
257 #define ITTNOTIFY_VOID_D5(n,d,x,y,z,a,b) (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y,z,a,b)
258 #define ITTNOTIFY_VOID_D6(n,d,x,y,z,a,b,c) (!(d)->flags) ? (void)0 : (!ITTNOTIFY_NAME(n)) ? (void)0 : ITTNOTIFY_NAME(n)(d,x,y,z,a,b,c)
259 #define ITTNOTIFY_DATA_D0(n,d) (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d)
260 #define ITTNOTIFY_DATA_D1(n,d,x) (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x)
261 #define ITTNOTIFY_DATA_D2(n,d,x,y) (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y)
262 #define ITTNOTIFY_DATA_D3(n,d,x,y,z) (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y,z)
263 #define ITTNOTIFY_DATA_D4(n,d,x,y,z,a) (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y,z,a)
264 #define ITTNOTIFY_DATA_D5(n,d,x,y,z,a,b) (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y,z,a,b)
265 #define ITTNOTIFY_DATA_D6(n,d,x,y,z,a,b,c) (!(d)->flags) ? 0 : (!ITTNOTIFY_NAME(n)) ? 0 : ITTNOTIFY_NAME(n)(d,x,y,z,a,b,c)
266
267 #ifdef ITT_STUB
268 #undef ITT_STUB
269 #endif
270 #ifdef ITT_STUBV
271 #undef ITT_STUBV
272 #endif
273 #define ITT_STUBV(api,type,name,args) \
274 typedef type (api* ITT_JOIN(ITTNOTIFY_NAME(name),_t)) args; \
275 extern ITT_JOIN(ITTNOTIFY_NAME(name),_t) ITTNOTIFY_NAME(name);
276 #define ITT_STUB ITT_STUBV
277 /** @endcond */
278
279 #ifdef __cplusplus
280 extern "C" {
281 #endif /* __cplusplus */
282
283 /** @cond exclude_from_gpa_documentation */
284 /**
285 * @defgroup public Public API
286 * @{
287 * @}
288 */
289
290 /**
291 * @defgroup control Collection Control
292 * @ingroup public
293 * General behavior: application continues to run, but no profiling information is being collected
294 *
295 * Pausing occurs not only for the current thread but for all process as well as spawned processes
296 * - Intel(R) Parallel Inspector and Intel(R) Inspector XE:
297 * - Does not analyze or report errors that involve memory access.
298 * - Other errors are reported as usual. Pausing data collection in
299 * Intel(R) Parallel Inspector and Intel(R) Inspector XE
300 * only pauses tracing and analyzing memory access.
301 * It does not pause tracing or analyzing threading APIs.
302 * .
303 * - Intel(R) Parallel Amplifier and Intel(R) VTune(TM) Amplifier XE:
304 * - Does continue to record when new threads are started.
305 * .
306 * - Other effects:
307 * - Possible reduction of runtime overhead.
308 * .
309 * @{
310 */
311 /** @brief Pause collection */
312 void ITTAPI __itt_pause(void);
313 /** @brief Resume collection */
314 void ITTAPI __itt_resume(void);
315 /** @brief Detach collection */
316 void ITTAPI __itt_detach(void);
317
318 /** @cond exclude_from_documentation */
319 #ifndef INTEL_NO_MACRO_BODY
320 #ifndef INTEL_NO_ITTNOTIFY_API
321 ITT_STUBV(ITTAPI, void, pause, (void))
322 ITT_STUBV(ITTAPI, void, resume, (void))
323 ITT_STUBV(ITTAPI, void, detach, (void))
324 #define __itt_pause ITTNOTIFY_VOID(pause)
325 #define __itt_pause_ptr ITTNOTIFY_NAME(pause)
326 #define __itt_resume ITTNOTIFY_VOID(resume)
327 #define __itt_resume_ptr ITTNOTIFY_NAME(resume)
328 #define __itt_detach ITTNOTIFY_VOID(detach)
329 #define __itt_detach_ptr ITTNOTIFY_NAME(detach)
330 #else /* INTEL_NO_ITTNOTIFY_API */
331 #define __itt_pause()
332 #define __itt_pause_ptr 0
333 #define __itt_resume()
334 #define __itt_resume_ptr 0
335 #define __itt_detach()
336 #define __itt_detach_ptr 0
337 #endif /* INTEL_NO_ITTNOTIFY_API */
338 #else /* INTEL_NO_MACRO_BODY */
339 #define __itt_pause_ptr 0
340 #define __itt_resume_ptr 0
341 #define __itt_detach_ptr 0
342 #endif /* INTEL_NO_MACRO_BODY */
343 /** @endcond */
344 /** @} control group */
345 /** @endcond */
346
347 /**
348 * @defgroup Intel Processor Trace control
349 * API from this group provides control over collection and analysis of Intel Processor Trace (Intel PT) data
350 * Information about Intel Processor Trace technology can be found here (Volume 3 chapter 35):
351 * https://software.intel.com/sites/default/files/managed/39/c5/325462-sdm-vol-1-2abcd-3abcd.pdf
352 * Use this API to mark particular code regions for loading detailed performance statistics.
353 * This mode makes your analysis faster and more accurate.
354 * @{
355 */
356 typedef unsigned char __itt_pt_region;
357
358 /**
359 * @brief function saves a region name marked with Intel PT API and returns a region id.
360 * Only 7 names can be registered. Attempts to register more names will be ignored and a region id with auto names will be returned.
361 * For automatic naming of regions pass NULL as function parameter
362 */
363 #if ITT_PLATFORM==ITT_PLATFORM_WIN
364 __itt_pt_region ITTAPI __itt_pt_region_createA(const char *name);
365 __itt_pt_region ITTAPI __itt_pt_region_createW(const wchar_t *name);
366 #if defined(UNICODE) || defined(_UNICODE)
367 # define __itt_pt_region_create __itt_pt_region_createW
368 #else /* UNICODE */
369 # define __itt_pt_region_create __itt_pt_region_createA
370 #endif /* UNICODE */
371 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
372 __itt_pt_region ITTAPI __itt_pt_region_create(const char *name);
373 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
374
375 /** @cond exclude_from_documentation */
376 #ifndef INTEL_NO_MACRO_BODY
377 #ifndef INTEL_NO_ITTNOTIFY_API
378 #if ITT_PLATFORM==ITT_PLATFORM_WIN
379 ITT_STUB(ITTAPI, __itt_pt_region, pt_region_createA, (const char *name))
380 ITT_STUB(ITTAPI, __itt_pt_region, pt_region_createW, (const wchar_t *name))
381 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
382 ITT_STUB(ITTAPI, __itt_pt_region, pt_region_create, (const char *name))
383 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
384 #if ITT_PLATFORM==ITT_PLATFORM_WIN
385 #define __itt_pt_region_createA ITTNOTIFY_DATA(pt_region_createA)
386 #define __itt_pt_region_createA_ptr ITTNOTIFY_NAME(pt_region_createA)
387 #define __itt_pt_region_createW ITTNOTIFY_DATA(pt_region_createW)
388 #define __itt_pt_region_createW_ptr ITTNOTIFY_NAME(pt_region_createW)
389 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
390 #define __itt_pt_region_create ITTNOTIFY_DATA(pt_region_create)
391 #define __itt_pt_region_create_ptr ITTNOTIFY_NAME(pt_region_create)
392 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
393 #else /* INTEL_NO_ITTNOTIFY_API */
394 #if ITT_PLATFORM==ITT_PLATFORM_WIN
395 #define __itt_pt_region_createA(name) (__itt_pt_region)0
396 #define __itt_pt_region_createA_ptr 0
397 #define __itt_pt_region_createW(name) (__itt_pt_region)0
398 #define __itt_pt_region_createW_ptr 0
399 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
400 #define __itt_pt_region_create(name) (__itt_pt_region)0
401 #define __itt_pt_region_create_ptr 0
402 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
403 #endif /* INTEL_NO_ITTNOTIFY_API */
404 #else /* INTEL_NO_MACRO_BODY */
405 #if ITT_PLATFORM==ITT_PLATFORM_WIN
406 #define __itt_pt_region_createA_ptr 0
407 #define __itt_pt_region_createW_ptr 0
408 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
409 #define __itt_pt_region_create_ptr 0
410 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
411 #endif /* INTEL_NO_MACRO_BODY */
412 /** @endcond */
413
414 /**
415 * @brief function contains a special code pattern identified on the post-processing stage and
416 * marks the beginning of a code region targeted for Intel PT analysis
417 * @param[in] region - region id, 0 <= region < 8
418 */
419 void __itt_mark_pt_region_begin(__itt_pt_region region);
420 /**
421 * @brief function contains a special code pattern identified on the post-processing stage and
422 * marks the end of a code region targeted for Intel PT analysis
423 * @param[in] region - region id, 0 <= region < 8
424 */
425 void __itt_mark_pt_region_end(__itt_pt_region region);
426 /** @} Intel PT control group*/
427
428 /**
429 * @defgroup threads Threads
430 * @ingroup public
431 * Give names to threads
432 * @{
433 */
434 /**
435 * @brief Sets thread name of calling thread
436 * @param[in] name - name of thread
437 */
438 #if ITT_PLATFORM==ITT_PLATFORM_WIN
439 void ITTAPI __itt_thread_set_nameA(const char *name);
440 void ITTAPI __itt_thread_set_nameW(const wchar_t *name);
441 #if defined(UNICODE) || defined(_UNICODE)
442 # define __itt_thread_set_name __itt_thread_set_nameW
443 # define __itt_thread_set_name_ptr __itt_thread_set_nameW_ptr
444 #else /* UNICODE */
445 # define __itt_thread_set_name __itt_thread_set_nameA
446 # define __itt_thread_set_name_ptr __itt_thread_set_nameA_ptr
447 #endif /* UNICODE */
448 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
449 void ITTAPI __itt_thread_set_name(const char *name);
450 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
451
452 /** @cond exclude_from_documentation */
453 #ifndef INTEL_NO_MACRO_BODY
454 #ifndef INTEL_NO_ITTNOTIFY_API
455 #if ITT_PLATFORM==ITT_PLATFORM_WIN
456 ITT_STUBV(ITTAPI, void, thread_set_nameA, (const char *name))
457 ITT_STUBV(ITTAPI, void, thread_set_nameW, (const wchar_t *name))
458 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
459 ITT_STUBV(ITTAPI, void, thread_set_name, (const char *name))
460 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
461 #if ITT_PLATFORM==ITT_PLATFORM_WIN
462 #define __itt_thread_set_nameA ITTNOTIFY_VOID(thread_set_nameA)
463 #define __itt_thread_set_nameA_ptr ITTNOTIFY_NAME(thread_set_nameA)
464 #define __itt_thread_set_nameW ITTNOTIFY_VOID(thread_set_nameW)
465 #define __itt_thread_set_nameW_ptr ITTNOTIFY_NAME(thread_set_nameW)
466 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
467 #define __itt_thread_set_name ITTNOTIFY_VOID(thread_set_name)
468 #define __itt_thread_set_name_ptr ITTNOTIFY_NAME(thread_set_name)
469 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
470 #else /* INTEL_NO_ITTNOTIFY_API */
471 #if ITT_PLATFORM==ITT_PLATFORM_WIN
472 #define __itt_thread_set_nameA(name)
473 #define __itt_thread_set_nameA_ptr 0
474 #define __itt_thread_set_nameW(name)
475 #define __itt_thread_set_nameW_ptr 0
476 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
477 #define __itt_thread_set_name(name)
478 #define __itt_thread_set_name_ptr 0
479 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
480 #endif /* INTEL_NO_ITTNOTIFY_API */
481 #else /* INTEL_NO_MACRO_BODY */
482 #if ITT_PLATFORM==ITT_PLATFORM_WIN
483 #define __itt_thread_set_nameA_ptr 0
484 #define __itt_thread_set_nameW_ptr 0
485 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
486 #define __itt_thread_set_name_ptr 0
487 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
488 #endif /* INTEL_NO_MACRO_BODY */
489 /** @endcond */
490
491 /** @cond exclude_from_gpa_documentation */
492
493 /**
494 * @brief Mark current thread as ignored from this point on, for the duration of its existence.
495 */
496 void ITTAPI __itt_thread_ignore(void);
497
498 /** @cond exclude_from_documentation */
499 #ifndef INTEL_NO_MACRO_BODY
500 #ifndef INTEL_NO_ITTNOTIFY_API
501 ITT_STUBV(ITTAPI, void, thread_ignore, (void))
502 #define __itt_thread_ignore ITTNOTIFY_VOID(thread_ignore)
503 #define __itt_thread_ignore_ptr ITTNOTIFY_NAME(thread_ignore)
504 #else /* INTEL_NO_ITTNOTIFY_API */
505 #define __itt_thread_ignore()
506 #define __itt_thread_ignore_ptr 0
507 #endif /* INTEL_NO_ITTNOTIFY_API */
508 #else /* INTEL_NO_MACRO_BODY */
509 #define __itt_thread_ignore_ptr 0
510 #endif /* INTEL_NO_MACRO_BODY */
511 /** @endcond */
512 /** @} threads group */
513
514 /**
515 * @defgroup suppress Error suppression
516 * @ingroup public
517 * General behavior: application continues to run, but errors are suppressed
518 *
519 * @{
520 */
521
522 /*****************************************************************//**
523 * @name group of functions used for error suppression in correctness tools
524 *********************************************************************/
525 /** @{ */
526 /**
527 * @hideinitializer
528 * @brief possible value for suppression mask
529 */
530 #define __itt_suppress_all_errors 0x7fffffff
531
532 /**
533 * @hideinitializer
534 * @brief possible value for suppression mask (suppresses errors from threading analysis)
535 */
536 #define __itt_suppress_threading_errors 0x000000ff
537
538 /**
539 * @hideinitializer
540 * @brief possible value for suppression mask (suppresses errors from memory analysis)
541 */
542 #define __itt_suppress_memory_errors 0x0000ff00
543
544 /**
545 * @brief Start suppressing errors identified in mask on this thread
546 */
547 void ITTAPI __itt_suppress_push(unsigned int mask);
548
549 /** @cond exclude_from_documentation */
550 #ifndef INTEL_NO_MACRO_BODY
551 #ifndef INTEL_NO_ITTNOTIFY_API
552 ITT_STUBV(ITTAPI, void, suppress_push, (unsigned int mask))
553 #define __itt_suppress_push ITTNOTIFY_VOID(suppress_push)
554 #define __itt_suppress_push_ptr ITTNOTIFY_NAME(suppress_push)
555 #else /* INTEL_NO_ITTNOTIFY_API */
556 #define __itt_suppress_push(mask)
557 #define __itt_suppress_push_ptr 0
558 #endif /* INTEL_NO_ITTNOTIFY_API */
559 #else /* INTEL_NO_MACRO_BODY */
560 #define __itt_suppress_push_ptr 0
561 #endif /* INTEL_NO_MACRO_BODY */
562 /** @endcond */
563
564 /**
565 * @brief Undo the effects of the matching call to __itt_suppress_push
566 */
567 void ITTAPI __itt_suppress_pop(void);
568
569 /** @cond exclude_from_documentation */
570 #ifndef INTEL_NO_MACRO_BODY
571 #ifndef INTEL_NO_ITTNOTIFY_API
572 ITT_STUBV(ITTAPI, void, suppress_pop, (void))
573 #define __itt_suppress_pop ITTNOTIFY_VOID(suppress_pop)
574 #define __itt_suppress_pop_ptr ITTNOTIFY_NAME(suppress_pop)
575 #else /* INTEL_NO_ITTNOTIFY_API */
576 #define __itt_suppress_pop()
577 #define __itt_suppress_pop_ptr 0
578 #endif /* INTEL_NO_ITTNOTIFY_API */
579 #else /* INTEL_NO_MACRO_BODY */
580 #define __itt_suppress_pop_ptr 0
581 #endif /* INTEL_NO_MACRO_BODY */
582 /** @endcond */
583
584 /**
585 * @enum __itt_model_disable
586 * @brief Enumerator for the disable methods
587 */
588 typedef enum __itt_suppress_mode {
589 __itt_unsuppress_range,
590 __itt_suppress_range
591 } __itt_suppress_mode_t;
592
593 /**
594 * @brief Mark a range of memory for error suppression or unsuppression for error types included in mask
595 */
596 void ITTAPI __itt_suppress_mark_range(__itt_suppress_mode_t mode, unsigned int mask, void * address, size_t size);
597
598 /** @cond exclude_from_documentation */
599 #ifndef INTEL_NO_MACRO_BODY
600 #ifndef INTEL_NO_ITTNOTIFY_API
601 ITT_STUBV(ITTAPI, void, suppress_mark_range, (__itt_suppress_mode_t mode, unsigned int mask, void * address, size_t size))
602 #define __itt_suppress_mark_range ITTNOTIFY_VOID(suppress_mark_range)
603 #define __itt_suppress_mark_range_ptr ITTNOTIFY_NAME(suppress_mark_range)
604 #else /* INTEL_NO_ITTNOTIFY_API */
605 #define __itt_suppress_mark_range(mask)
606 #define __itt_suppress_mark_range_ptr 0
607 #endif /* INTEL_NO_ITTNOTIFY_API */
608 #else /* INTEL_NO_MACRO_BODY */
609 #define __itt_suppress_mark_range_ptr 0
610 #endif /* INTEL_NO_MACRO_BODY */
611 /** @endcond */
612
613 /**
614 * @brief Undo the effect of a matching call to __itt_suppress_mark_range. If not matching
615 * call is found, nothing is changed.
616 */
617 void ITTAPI __itt_suppress_clear_range(__itt_suppress_mode_t mode, unsigned int mask, void * address, size_t size);
618
619 /** @cond exclude_from_documentation */
620 #ifndef INTEL_NO_MACRO_BODY
621 #ifndef INTEL_NO_ITTNOTIFY_API
622 ITT_STUBV(ITTAPI, void, suppress_clear_range, (__itt_suppress_mode_t mode, unsigned int mask, void * address, size_t size))
623 #define __itt_suppress_clear_range ITTNOTIFY_VOID(suppress_clear_range)
624 #define __itt_suppress_clear_range_ptr ITTNOTIFY_NAME(suppress_clear_range)
625 #else /* INTEL_NO_ITTNOTIFY_API */
626 #define __itt_suppress_clear_range(mask)
627 #define __itt_suppress_clear_range_ptr 0
628 #endif /* INTEL_NO_ITTNOTIFY_API */
629 #else /* INTEL_NO_MACRO_BODY */
630 #define __itt_suppress_clear_range_ptr 0
631 #endif /* INTEL_NO_MACRO_BODY */
632 /** @endcond */
633 /** @} */
634 /** @} suppress group */
635
636 /**
637 * @defgroup sync Synchronization
638 * @ingroup public
639 * Indicate user-written synchronization code
640 * @{
641 */
642 /**
643 * @hideinitializer
644 * @brief possible value of attribute argument for sync object type
645 */
646 #define __itt_attr_barrier 1
647
648 /**
649 * @hideinitializer
650 * @brief possible value of attribute argument for sync object type
651 */
652 #define __itt_attr_mutex 2
653
654 /**
655 @brief Name a synchronization object
656 @param[in] addr Handle for the synchronization object. You should
657 use a real address to uniquely identify the synchronization object.
658 @param[in] objtype null-terminated object type string. If NULL is
659 passed, the name will be "User Synchronization".
660 @param[in] objname null-terminated object name string. If NULL,
661 no name will be assigned to the object.
662 @param[in] attribute one of [#__itt_attr_barrier, #__itt_attr_mutex]
663 */
664
665 #if ITT_PLATFORM==ITT_PLATFORM_WIN
666 void ITTAPI __itt_sync_createA(void *addr, const char *objtype, const char *objname, int attribute);
667 void ITTAPI __itt_sync_createW(void *addr, const wchar_t *objtype, const wchar_t *objname, int attribute);
668 #if defined(UNICODE) || defined(_UNICODE)
669 # define __itt_sync_create __itt_sync_createW
670 # define __itt_sync_create_ptr __itt_sync_createW_ptr
671 #else /* UNICODE */
672 # define __itt_sync_create __itt_sync_createA
673 # define __itt_sync_create_ptr __itt_sync_createA_ptr
674 #endif /* UNICODE */
675 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
676 void ITTAPI __itt_sync_create (void *addr, const char *objtype, const char *objname, int attribute);
677 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
678
679 /** @cond exclude_from_documentation */
680 #ifndef INTEL_NO_MACRO_BODY
681 #ifndef INTEL_NO_ITTNOTIFY_API
682 #if ITT_PLATFORM==ITT_PLATFORM_WIN
683 ITT_STUBV(ITTAPI, void, sync_createA, (void *addr, const char *objtype, const char *objname, int attribute))
684 ITT_STUBV(ITTAPI, void, sync_createW, (void *addr, const wchar_t *objtype, const wchar_t *objname, int attribute))
685 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
686 ITT_STUBV(ITTAPI, void, sync_create, (void *addr, const char* objtype, const char* objname, int attribute))
687 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
688 #if ITT_PLATFORM==ITT_PLATFORM_WIN
689 #define __itt_sync_createA ITTNOTIFY_VOID(sync_createA)
690 #define __itt_sync_createA_ptr ITTNOTIFY_NAME(sync_createA)
691 #define __itt_sync_createW ITTNOTIFY_VOID(sync_createW)
692 #define __itt_sync_createW_ptr ITTNOTIFY_NAME(sync_createW)
693 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
694 #define __itt_sync_create ITTNOTIFY_VOID(sync_create)
695 #define __itt_sync_create_ptr ITTNOTIFY_NAME(sync_create)
696 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
697 #else /* INTEL_NO_ITTNOTIFY_API */
698 #if ITT_PLATFORM==ITT_PLATFORM_WIN
699 #define __itt_sync_createA(addr, objtype, objname, attribute)
700 #define __itt_sync_createA_ptr 0
701 #define __itt_sync_createW(addr, objtype, objname, attribute)
702 #define __itt_sync_createW_ptr 0
703 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
704 #define __itt_sync_create(addr, objtype, objname, attribute)
705 #define __itt_sync_create_ptr 0
706 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
707 #endif /* INTEL_NO_ITTNOTIFY_API */
708 #else /* INTEL_NO_MACRO_BODY */
709 #if ITT_PLATFORM==ITT_PLATFORM_WIN
710 #define __itt_sync_createA_ptr 0
711 #define __itt_sync_createW_ptr 0
712 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
713 #define __itt_sync_create_ptr 0
714 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
715 #endif /* INTEL_NO_MACRO_BODY */
716 /** @endcond */
717
718 /**
719 @brief Rename a synchronization object
720
721 You can use the rename call to assign or reassign a name to a given
722 synchronization object.
723 @param[in] addr handle for the synchronization object.
724 @param[in] name null-terminated object name string.
725 */
726 #if ITT_PLATFORM==ITT_PLATFORM_WIN
727 void ITTAPI __itt_sync_renameA(void *addr, const char *name);
728 void ITTAPI __itt_sync_renameW(void *addr, const wchar_t *name);
729 #if defined(UNICODE) || defined(_UNICODE)
730 # define __itt_sync_rename __itt_sync_renameW
731 # define __itt_sync_rename_ptr __itt_sync_renameW_ptr
732 #else /* UNICODE */
733 # define __itt_sync_rename __itt_sync_renameA
734 # define __itt_sync_rename_ptr __itt_sync_renameA_ptr
735 #endif /* UNICODE */
736 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
737 void ITTAPI __itt_sync_rename(void *addr, const char *name);
738 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
739
740 /** @cond exclude_from_documentation */
741 #ifndef INTEL_NO_MACRO_BODY
742 #ifndef INTEL_NO_ITTNOTIFY_API
743 #if ITT_PLATFORM==ITT_PLATFORM_WIN
744 ITT_STUBV(ITTAPI, void, sync_renameA, (void *addr, const char *name))
745 ITT_STUBV(ITTAPI, void, sync_renameW, (void *addr, const wchar_t *name))
746 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
747 ITT_STUBV(ITTAPI, void, sync_rename, (void *addr, const char *name))
748 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
749 #if ITT_PLATFORM==ITT_PLATFORM_WIN
750 #define __itt_sync_renameA ITTNOTIFY_VOID(sync_renameA)
751 #define __itt_sync_renameA_ptr ITTNOTIFY_NAME(sync_renameA)
752 #define __itt_sync_renameW ITTNOTIFY_VOID(sync_renameW)
753 #define __itt_sync_renameW_ptr ITTNOTIFY_NAME(sync_renameW)
754 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
755 #define __itt_sync_rename ITTNOTIFY_VOID(sync_rename)
756 #define __itt_sync_rename_ptr ITTNOTIFY_NAME(sync_rename)
757 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
758 #else /* INTEL_NO_ITTNOTIFY_API */
759 #if ITT_PLATFORM==ITT_PLATFORM_WIN
760 #define __itt_sync_renameA(addr, name)
761 #define __itt_sync_renameA_ptr 0
762 #define __itt_sync_renameW(addr, name)
763 #define __itt_sync_renameW_ptr 0
764 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
765 #define __itt_sync_rename(addr, name)
766 #define __itt_sync_rename_ptr 0
767 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
768 #endif /* INTEL_NO_ITTNOTIFY_API */
769 #else /* INTEL_NO_MACRO_BODY */
770 #if ITT_PLATFORM==ITT_PLATFORM_WIN
771 #define __itt_sync_renameA_ptr 0
772 #define __itt_sync_renameW_ptr 0
773 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
774 #define __itt_sync_rename_ptr 0
775 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
776 #endif /* INTEL_NO_MACRO_BODY */
777 /** @endcond */
778
779 /**
780 @brief Destroy a synchronization object.
781 @param addr Handle for the synchronization object.
782 */
783 void ITTAPI __itt_sync_destroy(void *addr);
784
785 /** @cond exclude_from_documentation */
786 #ifndef INTEL_NO_MACRO_BODY
787 #ifndef INTEL_NO_ITTNOTIFY_API
788 ITT_STUBV(ITTAPI, void, sync_destroy, (void *addr))
789 #define __itt_sync_destroy ITTNOTIFY_VOID(sync_destroy)
790 #define __itt_sync_destroy_ptr ITTNOTIFY_NAME(sync_destroy)
791 #else /* INTEL_NO_ITTNOTIFY_API */
792 #define __itt_sync_destroy(addr)
793 #define __itt_sync_destroy_ptr 0
794 #endif /* INTEL_NO_ITTNOTIFY_API */
795 #else /* INTEL_NO_MACRO_BODY */
796 #define __itt_sync_destroy_ptr 0
797 #endif /* INTEL_NO_MACRO_BODY */
798 /** @endcond */
799
800 /*****************************************************************//**
801 * @name group of functions is used for performance measurement tools
802 *********************************************************************/
803 /** @{ */
804 /**
805 * @brief Enter spin loop on user-defined sync object
806 */
807 void ITTAPI __itt_sync_prepare(void* addr);
808
809 /** @cond exclude_from_documentation */
810 #ifndef INTEL_NO_MACRO_BODY
811 #ifndef INTEL_NO_ITTNOTIFY_API
812 ITT_STUBV(ITTAPI, void, sync_prepare, (void *addr))
813 #define __itt_sync_prepare ITTNOTIFY_VOID(sync_prepare)
814 #define __itt_sync_prepare_ptr ITTNOTIFY_NAME(sync_prepare)
815 #else /* INTEL_NO_ITTNOTIFY_API */
816 #define __itt_sync_prepare(addr)
817 #define __itt_sync_prepare_ptr 0
818 #endif /* INTEL_NO_ITTNOTIFY_API */
819 #else /* INTEL_NO_MACRO_BODY */
820 #define __itt_sync_prepare_ptr 0
821 #endif /* INTEL_NO_MACRO_BODY */
822 /** @endcond */
823
824 /**
825 * @brief Quit spin loop without acquiring spin object
826 */
827 void ITTAPI __itt_sync_cancel(void *addr);
828
829 /** @cond exclude_from_documentation */
830 #ifndef INTEL_NO_MACRO_BODY
831 #ifndef INTEL_NO_ITTNOTIFY_API
832 ITT_STUBV(ITTAPI, void, sync_cancel, (void *addr))
833 #define __itt_sync_cancel ITTNOTIFY_VOID(sync_cancel)
834 #define __itt_sync_cancel_ptr ITTNOTIFY_NAME(sync_cancel)
835 #else /* INTEL_NO_ITTNOTIFY_API */
836 #define __itt_sync_cancel(addr)
837 #define __itt_sync_cancel_ptr 0
838 #endif /* INTEL_NO_ITTNOTIFY_API */
839 #else /* INTEL_NO_MACRO_BODY */
840 #define __itt_sync_cancel_ptr 0
841 #endif /* INTEL_NO_MACRO_BODY */
842 /** @endcond */
843
844 /**
845 * @brief Successful spin loop completion (sync object acquired)
846 */
847 void ITTAPI __itt_sync_acquired(void *addr);
848
849 /** @cond exclude_from_documentation */
850 #ifndef INTEL_NO_MACRO_BODY
851 #ifndef INTEL_NO_ITTNOTIFY_API
852 ITT_STUBV(ITTAPI, void, sync_acquired, (void *addr))
853 #define __itt_sync_acquired ITTNOTIFY_VOID(sync_acquired)
854 #define __itt_sync_acquired_ptr ITTNOTIFY_NAME(sync_acquired)
855 #else /* INTEL_NO_ITTNOTIFY_API */
856 #define __itt_sync_acquired(addr)
857 #define __itt_sync_acquired_ptr 0
858 #endif /* INTEL_NO_ITTNOTIFY_API */
859 #else /* INTEL_NO_MACRO_BODY */
860 #define __itt_sync_acquired_ptr 0
861 #endif /* INTEL_NO_MACRO_BODY */
862 /** @endcond */
863
864 /**
865 * @brief Start sync object releasing code. Is called before the lock release call.
866 */
867 void ITTAPI __itt_sync_releasing(void* addr);
868
869 /** @cond exclude_from_documentation */
870 #ifndef INTEL_NO_MACRO_BODY
871 #ifndef INTEL_NO_ITTNOTIFY_API
872 ITT_STUBV(ITTAPI, void, sync_releasing, (void *addr))
873 #define __itt_sync_releasing ITTNOTIFY_VOID(sync_releasing)
874 #define __itt_sync_releasing_ptr ITTNOTIFY_NAME(sync_releasing)
875 #else /* INTEL_NO_ITTNOTIFY_API */
876 #define __itt_sync_releasing(addr)
877 #define __itt_sync_releasing_ptr 0
878 #endif /* INTEL_NO_ITTNOTIFY_API */
879 #else /* INTEL_NO_MACRO_BODY */
880 #define __itt_sync_releasing_ptr 0
881 #endif /* INTEL_NO_MACRO_BODY */
882 /** @endcond */
883 /** @} */
884
885 /** @} sync group */
886
887 /**************************************************************//**
888 * @name group of functions is used for correctness checking tools
889 ******************************************************************/
890 /** @{ */
891 /**
892 * @ingroup legacy
893 * @deprecated Legacy API
894 * @brief Fast synchronization which does no require spinning.
895 * - This special function is to be used by TBB and OpenMP libraries only when they know
896 * there is no spin but they need to suppress TC warnings about shared variable modifications.
897 * - It only has corresponding pointers in static library and does not have corresponding function
898 * in dynamic library.
899 * @see void __itt_sync_prepare(void* addr);
900 */
901 void ITTAPI __itt_fsync_prepare(void* addr);
902
903 /** @cond exclude_from_documentation */
904 #ifndef INTEL_NO_MACRO_BODY
905 #ifndef INTEL_NO_ITTNOTIFY_API
906 ITT_STUBV(ITTAPI, void, fsync_prepare, (void *addr))
907 #define __itt_fsync_prepare ITTNOTIFY_VOID(fsync_prepare)
908 #define __itt_fsync_prepare_ptr ITTNOTIFY_NAME(fsync_prepare)
909 #else /* INTEL_NO_ITTNOTIFY_API */
910 #define __itt_fsync_prepare(addr)
911 #define __itt_fsync_prepare_ptr 0
912 #endif /* INTEL_NO_ITTNOTIFY_API */
913 #else /* INTEL_NO_MACRO_BODY */
914 #define __itt_fsync_prepare_ptr 0
915 #endif /* INTEL_NO_MACRO_BODY */
916 /** @endcond */
917
918 /**
919 * @ingroup legacy
920 * @deprecated Legacy API
921 * @brief Fast synchronization which does no require spinning.
922 * - This special function is to be used by TBB and OpenMP libraries only when they know
923 * there is no spin but they need to suppress TC warnings about shared variable modifications.
924 * - It only has corresponding pointers in static library and does not have corresponding function
925 * in dynamic library.
926 * @see void __itt_sync_cancel(void *addr);
927 */
928 void ITTAPI __itt_fsync_cancel(void *addr);
929
930 /** @cond exclude_from_documentation */
931 #ifndef INTEL_NO_MACRO_BODY
932 #ifndef INTEL_NO_ITTNOTIFY_API
933 ITT_STUBV(ITTAPI, void, fsync_cancel, (void *addr))
934 #define __itt_fsync_cancel ITTNOTIFY_VOID(fsync_cancel)
935 #define __itt_fsync_cancel_ptr ITTNOTIFY_NAME(fsync_cancel)
936 #else /* INTEL_NO_ITTNOTIFY_API */
937 #define __itt_fsync_cancel(addr)
938 #define __itt_fsync_cancel_ptr 0
939 #endif /* INTEL_NO_ITTNOTIFY_API */
940 #else /* INTEL_NO_MACRO_BODY */
941 #define __itt_fsync_cancel_ptr 0
942 #endif /* INTEL_NO_MACRO_BODY */
943 /** @endcond */
944
945 /**
946 * @ingroup legacy
947 * @deprecated Legacy API
948 * @brief Fast synchronization which does no require spinning.
949 * - This special function is to be used by TBB and OpenMP libraries only when they know
950 * there is no spin but they need to suppress TC warnings about shared variable modifications.
951 * - It only has corresponding pointers in static library and does not have corresponding function
952 * in dynamic library.
953 * @see void __itt_sync_acquired(void *addr);
954 */
955 void ITTAPI __itt_fsync_acquired(void *addr);
956
957 /** @cond exclude_from_documentation */
958 #ifndef INTEL_NO_MACRO_BODY
959 #ifndef INTEL_NO_ITTNOTIFY_API
960 ITT_STUBV(ITTAPI, void, fsync_acquired, (void *addr))
961 #define __itt_fsync_acquired ITTNOTIFY_VOID(fsync_acquired)
962 #define __itt_fsync_acquired_ptr ITTNOTIFY_NAME(fsync_acquired)
963 #else /* INTEL_NO_ITTNOTIFY_API */
964 #define __itt_fsync_acquired(addr)
965 #define __itt_fsync_acquired_ptr 0
966 #endif /* INTEL_NO_ITTNOTIFY_API */
967 #else /* INTEL_NO_MACRO_BODY */
968 #define __itt_fsync_acquired_ptr 0
969 #endif /* INTEL_NO_MACRO_BODY */
970 /** @endcond */
971
972 /**
973 * @ingroup legacy
974 * @deprecated Legacy API
975 * @brief Fast synchronization which does no require spinning.
976 * - This special function is to be used by TBB and OpenMP libraries only when they know
977 * there is no spin but they need to suppress TC warnings about shared variable modifications.
978 * - It only has corresponding pointers in static library and does not have corresponding function
979 * in dynamic library.
980 * @see void __itt_sync_releasing(void* addr);
981 */
982 void ITTAPI __itt_fsync_releasing(void* addr);
983
984 /** @cond exclude_from_documentation */
985 #ifndef INTEL_NO_MACRO_BODY
986 #ifndef INTEL_NO_ITTNOTIFY_API
987 ITT_STUBV(ITTAPI, void, fsync_releasing, (void *addr))
988 #define __itt_fsync_releasing ITTNOTIFY_VOID(fsync_releasing)
989 #define __itt_fsync_releasing_ptr ITTNOTIFY_NAME(fsync_releasing)
990 #else /* INTEL_NO_ITTNOTIFY_API */
991 #define __itt_fsync_releasing(addr)
992 #define __itt_fsync_releasing_ptr 0
993 #endif /* INTEL_NO_ITTNOTIFY_API */
994 #else /* INTEL_NO_MACRO_BODY */
995 #define __itt_fsync_releasing_ptr 0
996 #endif /* INTEL_NO_MACRO_BODY */
997 /** @endcond */
998 /** @} */
999
1000 /**
1001 * @defgroup model Modeling by Intel(R) Parallel Advisor
1002 * @ingroup public
1003 * This is the subset of itt used for modeling by Intel(R) Parallel Advisor.
1004 * This API is called ONLY using annotate.h, by "Annotation" macros
1005 * the user places in their sources during the parallelism modeling steps.
1006 *
1007 * site_begin/end and task_begin/end take the address of handle variables,
1008 * which are writeable by the API. Handles must be 0 initialized prior
1009 * to the first call to begin, or may cause a run-time failure.
1010 * The handles are initialized in a multi-thread safe way by the API if
1011 * the handle is 0. The commonly expected idiom is one static handle to
1012 * identify a site or task. If a site or task of the same name has already
1013 * been started during this collection, the same handle MAY be returned,
1014 * but is not required to be - it is unspecified if data merging is done
1015 * based on name. These routines also take an instance variable. Like
1016 * the lexical instance, these must be 0 initialized. Unlike the lexical
1017 * instance, this is used to track a single dynamic instance.
1018 *
1019 * API used by the Intel(R) Parallel Advisor to describe potential concurrency
1020 * and related activities. User-added source annotations expand to calls
1021 * to these procedures to enable modeling of a hypothetical concurrent
1022 * execution serially.
1023 * @{
1024 */
1025 #if !defined(_ADVISOR_ANNOTATE_H_) || defined(ANNOTATE_EXPAND_NULL)
1026
1027 typedef void* __itt_model_site; /*!< @brief handle for lexical site */
1028 typedef void* __itt_model_site_instance; /*!< @brief handle for dynamic instance */
1029 typedef void* __itt_model_task; /*!< @brief handle for lexical site */
1030 typedef void* __itt_model_task_instance; /*!< @brief handle for dynamic instance */
1031
1032 /**
1033 * @enum __itt_model_disable
1034 * @brief Enumerator for the disable methods
1035 */
1036 typedef enum {
1037 __itt_model_disable_observation,
1038 __itt_model_disable_collection
1039 } __itt_model_disable;
1040
1041 #endif /* !_ADVISOR_ANNOTATE_H_ || ANNOTATE_EXPAND_NULL */
1042
1043 /**
1044 * @brief ANNOTATE_SITE_BEGIN/ANNOTATE_SITE_END support.
1045 *
1046 * site_begin/end model a potential concurrency site.
1047 * site instances may be recursively nested with themselves.
1048 * site_end exits the most recently started but unended site for the current
1049 * thread. The handle passed to end may be used to validate structure.
1050 * Instances of a site encountered on different threads concurrently
1051 * are considered completely distinct. If the site name for two different
1052 * lexical sites match, it is unspecified whether they are treated as the
1053 * same or different for data presentation.
1054 */
1055 void ITTAPI __itt_model_site_begin(__itt_model_site *site, __itt_model_site_instance *instance, const char *name);
1056 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1057 void ITTAPI __itt_model_site_beginW(const wchar_t *name);
1058 #endif
1059 void ITTAPI __itt_model_site_beginA(const char *name);
1060 void ITTAPI __itt_model_site_beginAL(const char *name, size_t siteNameLen);
1061 void ITTAPI __itt_model_site_end (__itt_model_site *site, __itt_model_site_instance *instance);
1062 void ITTAPI __itt_model_site_end_2(void);
1063
1064 /** @cond exclude_from_documentation */
1065 #ifndef INTEL_NO_MACRO_BODY
1066 #ifndef INTEL_NO_ITTNOTIFY_API
1067 ITT_STUBV(ITTAPI, void, model_site_begin, (__itt_model_site *site, __itt_model_site_instance *instance, const char *name))
1068 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1069 ITT_STUBV(ITTAPI, void, model_site_beginW, (const wchar_t *name))
1070 #endif
1071 ITT_STUBV(ITTAPI, void, model_site_beginA, (const char *name))
1072 ITT_STUBV(ITTAPI, void, model_site_beginAL, (const char *name, size_t siteNameLen))
1073 ITT_STUBV(ITTAPI, void, model_site_end, (__itt_model_site *site, __itt_model_site_instance *instance))
1074 ITT_STUBV(ITTAPI, void, model_site_end_2, (void))
1075 #define __itt_model_site_begin ITTNOTIFY_VOID(model_site_begin)
1076 #define __itt_model_site_begin_ptr ITTNOTIFY_NAME(model_site_begin)
1077 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1078 #define __itt_model_site_beginW ITTNOTIFY_VOID(model_site_beginW)
1079 #define __itt_model_site_beginW_ptr ITTNOTIFY_NAME(model_site_beginW)
1080 #endif
1081 #define __itt_model_site_beginA ITTNOTIFY_VOID(model_site_beginA)
1082 #define __itt_model_site_beginA_ptr ITTNOTIFY_NAME(model_site_beginA)
1083 #define __itt_model_site_beginAL ITTNOTIFY_VOID(model_site_beginAL)
1084 #define __itt_model_site_beginAL_ptr ITTNOTIFY_NAME(model_site_beginAL)
1085 #define __itt_model_site_end ITTNOTIFY_VOID(model_site_end)
1086 #define __itt_model_site_end_ptr ITTNOTIFY_NAME(model_site_end)
1087 #define __itt_model_site_end_2 ITTNOTIFY_VOID(model_site_end_2)
1088 #define __itt_model_site_end_2_ptr ITTNOTIFY_NAME(model_site_end_2)
1089 #else /* INTEL_NO_ITTNOTIFY_API */
1090 #define __itt_model_site_begin(site, instance, name)
1091 #define __itt_model_site_begin_ptr 0
1092 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1093 #define __itt_model_site_beginW(name)
1094 #define __itt_model_site_beginW_ptr 0
1095 #endif
1096 #define __itt_model_site_beginA(name)
1097 #define __itt_model_site_beginA_ptr 0
1098 #define __itt_model_site_beginAL(name, siteNameLen)
1099 #define __itt_model_site_beginAL_ptr 0
1100 #define __itt_model_site_end(site, instance)
1101 #define __itt_model_site_end_ptr 0
1102 #define __itt_model_site_end_2()
1103 #define __itt_model_site_end_2_ptr 0
1104 #endif /* INTEL_NO_ITTNOTIFY_API */
1105 #else /* INTEL_NO_MACRO_BODY */
1106 #define __itt_model_site_begin_ptr 0
1107 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1108 #define __itt_model_site_beginW_ptr 0
1109 #endif
1110 #define __itt_model_site_beginA_ptr 0
1111 #define __itt_model_site_beginAL_ptr 0
1112 #define __itt_model_site_end_ptr 0
1113 #define __itt_model_site_end_2_ptr 0
1114 #endif /* INTEL_NO_MACRO_BODY */
1115 /** @endcond */
1116
1117 /**
1118 * @brief ANNOTATE_TASK_BEGIN/ANNOTATE_TASK_END support
1119 *
1120 * task_begin/end model a potential task, which is contained within the most
1121 * closely enclosing dynamic site. task_end exits the most recently started
1122 * but unended task. The handle passed to end may be used to validate
1123 * structure. It is unspecified if bad dynamic nesting is detected. If it
1124 * is, it should be encoded in the resulting data collection. The collector
1125 * should not fail due to construct nesting issues, nor attempt to directly
1126 * indicate the problem.
1127 */
1128 void ITTAPI __itt_model_task_begin(__itt_model_task *task, __itt_model_task_instance *instance, const char *name);
1129 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1130 void ITTAPI __itt_model_task_beginW(const wchar_t *name);
1131 void ITTAPI __itt_model_iteration_taskW(const wchar_t *name);
1132 #endif
1133 void ITTAPI __itt_model_task_beginA(const char *name);
1134 void ITTAPI __itt_model_task_beginAL(const char *name, size_t taskNameLen);
1135 void ITTAPI __itt_model_iteration_taskA(const char *name);
1136 void ITTAPI __itt_model_iteration_taskAL(const char *name, size_t taskNameLen);
1137 void ITTAPI __itt_model_task_end (__itt_model_task *task, __itt_model_task_instance *instance);
1138 void ITTAPI __itt_model_task_end_2(void);
1139
1140 /** @cond exclude_from_documentation */
1141 #ifndef INTEL_NO_MACRO_BODY
1142 #ifndef INTEL_NO_ITTNOTIFY_API
1143 ITT_STUBV(ITTAPI, void, model_task_begin, (__itt_model_task *task, __itt_model_task_instance *instance, const char *name))
1144 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1145 ITT_STUBV(ITTAPI, void, model_task_beginW, (const wchar_t *name))
1146 ITT_STUBV(ITTAPI, void, model_iteration_taskW, (const wchar_t *name))
1147 #endif
1148 ITT_STUBV(ITTAPI, void, model_task_beginA, (const char *name))
1149 ITT_STUBV(ITTAPI, void, model_task_beginAL, (const char *name, size_t taskNameLen))
1150 ITT_STUBV(ITTAPI, void, model_iteration_taskA, (const char *name))
1151 ITT_STUBV(ITTAPI, void, model_iteration_taskAL, (const char *name, size_t taskNameLen))
1152 ITT_STUBV(ITTAPI, void, model_task_end, (__itt_model_task *task, __itt_model_task_instance *instance))
1153 ITT_STUBV(ITTAPI, void, model_task_end_2, (void))
1154 #define __itt_model_task_begin ITTNOTIFY_VOID(model_task_begin)
1155 #define __itt_model_task_begin_ptr ITTNOTIFY_NAME(model_task_begin)
1156 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1157 #define __itt_model_task_beginW ITTNOTIFY_VOID(model_task_beginW)
1158 #define __itt_model_task_beginW_ptr ITTNOTIFY_NAME(model_task_beginW)
1159 #define __itt_model_iteration_taskW ITTNOTIFY_VOID(model_iteration_taskW)
1160 #define __itt_model_iteration_taskW_ptr ITTNOTIFY_NAME(model_iteration_taskW)
1161 #endif
1162 #define __itt_model_task_beginA ITTNOTIFY_VOID(model_task_beginA)
1163 #define __itt_model_task_beginA_ptr ITTNOTIFY_NAME(model_task_beginA)
1164 #define __itt_model_task_beginAL ITTNOTIFY_VOID(model_task_beginAL)
1165 #define __itt_model_task_beginAL_ptr ITTNOTIFY_NAME(model_task_beginAL)
1166 #define __itt_model_iteration_taskA ITTNOTIFY_VOID(model_iteration_taskA)
1167 #define __itt_model_iteration_taskA_ptr ITTNOTIFY_NAME(model_iteration_taskA)
1168 #define __itt_model_iteration_taskAL ITTNOTIFY_VOID(model_iteration_taskAL)
1169 #define __itt_model_iteration_taskAL_ptr ITTNOTIFY_NAME(model_iteration_taskAL)
1170 #define __itt_model_task_end ITTNOTIFY_VOID(model_task_end)
1171 #define __itt_model_task_end_ptr ITTNOTIFY_NAME(model_task_end)
1172 #define __itt_model_task_end_2 ITTNOTIFY_VOID(model_task_end_2)
1173 #define __itt_model_task_end_2_ptr ITTNOTIFY_NAME(model_task_end_2)
1174 #else /* INTEL_NO_ITTNOTIFY_API */
1175 #define __itt_model_task_begin(task, instance, name)
1176 #define __itt_model_task_begin_ptr 0
1177 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1178 #define __itt_model_task_beginW(name)
1179 #define __itt_model_task_beginW_ptr 0
1180 #endif
1181 #define __itt_model_task_beginA(name)
1182 #define __itt_model_task_beginA_ptr 0
1183 #define __itt_model_task_beginAL(name, siteNameLen)
1184 #define __itt_model_task_beginAL_ptr 0
1185 #define __itt_model_iteration_taskA(name)
1186 #define __itt_model_iteration_taskA_ptr 0
1187 #define __itt_model_iteration_taskAL(name, siteNameLen)
1188 #define __itt_model_iteration_taskAL_ptr 0
1189 #define __itt_model_task_end(task, instance)
1190 #define __itt_model_task_end_ptr 0
1191 #define __itt_model_task_end_2()
1192 #define __itt_model_task_end_2_ptr 0
1193 #endif /* INTEL_NO_ITTNOTIFY_API */
1194 #else /* INTEL_NO_MACRO_BODY */
1195 #define __itt_model_task_begin_ptr 0
1196 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1197 #define __itt_model_task_beginW_ptr 0
1198 #endif
1199 #define __itt_model_task_beginA_ptr 0
1200 #define __itt_model_task_beginAL_ptr 0
1201 #define __itt_model_iteration_taskA_ptr 0
1202 #define __itt_model_iteration_taskAL_ptr 0
1203 #define __itt_model_task_end_ptr 0
1204 #define __itt_model_task_end_2_ptr 0
1205 #endif /* INTEL_NO_MACRO_BODY */
1206 /** @endcond */
1207
1208 /**
1209 * @brief ANNOTATE_LOCK_ACQUIRE/ANNOTATE_LOCK_RELEASE support
1210 *
1211 * lock_acquire/release model a potential lock for both lockset and
1212 * performance modeling. Each unique address is modeled as a separate
1213 * lock, with invalid addresses being valid lock IDs. Specifically:
1214 * no storage is accessed by the API at the specified address - it is only
1215 * used for lock identification. Lock acquires may be self-nested and are
1216 * unlocked by a corresponding number of releases.
1217 * (These closely correspond to __itt_sync_acquired/__itt_sync_releasing,
1218 * but may not have identical semantics.)
1219 */
1220 void ITTAPI __itt_model_lock_acquire(void *lock);
1221 void ITTAPI __itt_model_lock_acquire_2(void *lock);
1222 void ITTAPI __itt_model_lock_release(void *lock);
1223 void ITTAPI __itt_model_lock_release_2(void *lock);
1224
1225 /** @cond exclude_from_documentation */
1226 #ifndef INTEL_NO_MACRO_BODY
1227 #ifndef INTEL_NO_ITTNOTIFY_API
1228 ITT_STUBV(ITTAPI, void, model_lock_acquire, (void *lock))
1229 ITT_STUBV(ITTAPI, void, model_lock_acquire_2, (void *lock))
1230 ITT_STUBV(ITTAPI, void, model_lock_release, (void *lock))
1231 ITT_STUBV(ITTAPI, void, model_lock_release_2, (void *lock))
1232 #define __itt_model_lock_acquire ITTNOTIFY_VOID(model_lock_acquire)
1233 #define __itt_model_lock_acquire_ptr ITTNOTIFY_NAME(model_lock_acquire)
1234 #define __itt_model_lock_acquire_2 ITTNOTIFY_VOID(model_lock_acquire_2)
1235 #define __itt_model_lock_acquire_2_ptr ITTNOTIFY_NAME(model_lock_acquire_2)
1236 #define __itt_model_lock_release ITTNOTIFY_VOID(model_lock_release)
1237 #define __itt_model_lock_release_ptr ITTNOTIFY_NAME(model_lock_release)
1238 #define __itt_model_lock_release_2 ITTNOTIFY_VOID(model_lock_release_2)
1239 #define __itt_model_lock_release_2_ptr ITTNOTIFY_NAME(model_lock_release_2)
1240 #else /* INTEL_NO_ITTNOTIFY_API */
1241 #define __itt_model_lock_acquire(lock)
1242 #define __itt_model_lock_acquire_ptr 0
1243 #define __itt_model_lock_acquire_2(lock)
1244 #define __itt_model_lock_acquire_2_ptr 0
1245 #define __itt_model_lock_release(lock)
1246 #define __itt_model_lock_release_ptr 0
1247 #define __itt_model_lock_release_2(lock)
1248 #define __itt_model_lock_release_2_ptr 0
1249 #endif /* INTEL_NO_ITTNOTIFY_API */
1250 #else /* INTEL_NO_MACRO_BODY */
1251 #define __itt_model_lock_acquire_ptr 0
1252 #define __itt_model_lock_acquire_2_ptr 0
1253 #define __itt_model_lock_release_ptr 0
1254 #define __itt_model_lock_release_2_ptr 0
1255 #endif /* INTEL_NO_MACRO_BODY */
1256 /** @endcond */
1257
1258 /**
1259 * @brief ANNOTATE_RECORD_ALLOCATION/ANNOTATE_RECORD_DEALLOCATION support
1260 *
1261 * record_allocation/deallocation describe user-defined memory allocator
1262 * behavior, which may be required for correctness modeling to understand
1263 * when storage is not expected to be actually reused across threads.
1264 */
1265 void ITTAPI __itt_model_record_allocation (void *addr, size_t size);
1266 void ITTAPI __itt_model_record_deallocation(void *addr);
1267
1268 /** @cond exclude_from_documentation */
1269 #ifndef INTEL_NO_MACRO_BODY
1270 #ifndef INTEL_NO_ITTNOTIFY_API
1271 ITT_STUBV(ITTAPI, void, model_record_allocation, (void *addr, size_t size))
1272 ITT_STUBV(ITTAPI, void, model_record_deallocation, (void *addr))
1273 #define __itt_model_record_allocation ITTNOTIFY_VOID(model_record_allocation)
1274 #define __itt_model_record_allocation_ptr ITTNOTIFY_NAME(model_record_allocation)
1275 #define __itt_model_record_deallocation ITTNOTIFY_VOID(model_record_deallocation)
1276 #define __itt_model_record_deallocation_ptr ITTNOTIFY_NAME(model_record_deallocation)
1277 #else /* INTEL_NO_ITTNOTIFY_API */
1278 #define __itt_model_record_allocation(addr, size)
1279 #define __itt_model_record_allocation_ptr 0
1280 #define __itt_model_record_deallocation(addr)
1281 #define __itt_model_record_deallocation_ptr 0
1282 #endif /* INTEL_NO_ITTNOTIFY_API */
1283 #else /* INTEL_NO_MACRO_BODY */
1284 #define __itt_model_record_allocation_ptr 0
1285 #define __itt_model_record_deallocation_ptr 0
1286 #endif /* INTEL_NO_MACRO_BODY */
1287 /** @endcond */
1288
1289 /**
1290 * @brief ANNOTATE_INDUCTION_USES support
1291 *
1292 * Note particular storage is inductive through the end of the current site
1293 */
1294 void ITTAPI __itt_model_induction_uses(void* addr, size_t size);
1295
1296 /** @cond exclude_from_documentation */
1297 #ifndef INTEL_NO_MACRO_BODY
1298 #ifndef INTEL_NO_ITTNOTIFY_API
1299 ITT_STUBV(ITTAPI, void, model_induction_uses, (void *addr, size_t size))
1300 #define __itt_model_induction_uses ITTNOTIFY_VOID(model_induction_uses)
1301 #define __itt_model_induction_uses_ptr ITTNOTIFY_NAME(model_induction_uses)
1302 #else /* INTEL_NO_ITTNOTIFY_API */
1303 #define __itt_model_induction_uses(addr, size)
1304 #define __itt_model_induction_uses_ptr 0
1305 #endif /* INTEL_NO_ITTNOTIFY_API */
1306 #else /* INTEL_NO_MACRO_BODY */
1307 #define __itt_model_induction_uses_ptr 0
1308 #endif /* INTEL_NO_MACRO_BODY */
1309 /** @endcond */
1310
1311 /**
1312 * @brief ANNOTATE_REDUCTION_USES support
1313 *
1314 * Note particular storage is used for reduction through the end
1315 * of the current site
1316 */
1317 void ITTAPI __itt_model_reduction_uses(void* addr, size_t size);
1318
1319 /** @cond exclude_from_documentation */
1320 #ifndef INTEL_NO_MACRO_BODY
1321 #ifndef INTEL_NO_ITTNOTIFY_API
1322 ITT_STUBV(ITTAPI, void, model_reduction_uses, (void *addr, size_t size))
1323 #define __itt_model_reduction_uses ITTNOTIFY_VOID(model_reduction_uses)
1324 #define __itt_model_reduction_uses_ptr ITTNOTIFY_NAME(model_reduction_uses)
1325 #else /* INTEL_NO_ITTNOTIFY_API */
1326 #define __itt_model_reduction_uses(addr, size)
1327 #define __itt_model_reduction_uses_ptr 0
1328 #endif /* INTEL_NO_ITTNOTIFY_API */
1329 #else /* INTEL_NO_MACRO_BODY */
1330 #define __itt_model_reduction_uses_ptr 0
1331 #endif /* INTEL_NO_MACRO_BODY */
1332 /** @endcond */
1333
1334 /**
1335 * @brief ANNOTATE_OBSERVE_USES support
1336 *
1337 * Have correctness modeling record observations about uses of storage
1338 * through the end of the current site
1339 */
1340 void ITTAPI __itt_model_observe_uses(void* addr, size_t size);
1341
1342 /** @cond exclude_from_documentation */
1343 #ifndef INTEL_NO_MACRO_BODY
1344 #ifndef INTEL_NO_ITTNOTIFY_API
1345 ITT_STUBV(ITTAPI, void, model_observe_uses, (void *addr, size_t size))
1346 #define __itt_model_observe_uses ITTNOTIFY_VOID(model_observe_uses)
1347 #define __itt_model_observe_uses_ptr ITTNOTIFY_NAME(model_observe_uses)
1348 #else /* INTEL_NO_ITTNOTIFY_API */
1349 #define __itt_model_observe_uses(addr, size)
1350 #define __itt_model_observe_uses_ptr 0
1351 #endif /* INTEL_NO_ITTNOTIFY_API */
1352 #else /* INTEL_NO_MACRO_BODY */
1353 #define __itt_model_observe_uses_ptr 0
1354 #endif /* INTEL_NO_MACRO_BODY */
1355 /** @endcond */
1356
1357 /**
1358 * @brief ANNOTATE_CLEAR_USES support
1359 *
1360 * Clear the special handling of a piece of storage related to induction,
1361 * reduction or observe_uses
1362 */
1363 void ITTAPI __itt_model_clear_uses(void* addr);
1364
1365 /** @cond exclude_from_documentation */
1366 #ifndef INTEL_NO_MACRO_BODY
1367 #ifndef INTEL_NO_ITTNOTIFY_API
1368 ITT_STUBV(ITTAPI, void, model_clear_uses, (void *addr))
1369 #define __itt_model_clear_uses ITTNOTIFY_VOID(model_clear_uses)
1370 #define __itt_model_clear_uses_ptr ITTNOTIFY_NAME(model_clear_uses)
1371 #else /* INTEL_NO_ITTNOTIFY_API */
1372 #define __itt_model_clear_uses(addr)
1373 #define __itt_model_clear_uses_ptr 0
1374 #endif /* INTEL_NO_ITTNOTIFY_API */
1375 #else /* INTEL_NO_MACRO_BODY */
1376 #define __itt_model_clear_uses_ptr 0
1377 #endif /* INTEL_NO_MACRO_BODY */
1378 /** @endcond */
1379
1380 /**
1381 * @brief ANNOTATE_DISABLE_*_PUSH/ANNOTATE_DISABLE_*_POP support
1382 *
1383 * disable_push/disable_pop push and pop disabling based on a parameter.
1384 * Disabling observations stops processing of memory references during
1385 * correctness modeling, and all annotations that occur in the disabled
1386 * region. This allows description of code that is expected to be handled
1387 * specially during conversion to parallelism or that is not recognized
1388 * by tools (e.g. some kinds of synchronization operations.)
1389 * This mechanism causes all annotations in the disabled region, other
1390 * than disable_push and disable_pop, to be ignored. (For example, this
1391 * might validly be used to disable an entire parallel site and the contained
1392 * tasks and locking in it for data collection purposes.)
1393 * The disable for collection is a more expensive operation, but reduces
1394 * collector overhead significantly. This applies to BOTH correctness data
1395 * collection and performance data collection. For example, a site
1396 * containing a task might only enable data collection for the first 10
1397 * iterations. Both performance and correctness data should reflect this,
1398 * and the program should run as close to full speed as possible when
1399 * collection is disabled.
1400 */
1401 void ITTAPI __itt_model_disable_push(__itt_model_disable x);
1402 void ITTAPI __itt_model_disable_pop(void);
1403 void ITTAPI __itt_model_aggregate_task(size_t x);
1404
1405 /** @cond exclude_from_documentation */
1406 #ifndef INTEL_NO_MACRO_BODY
1407 #ifndef INTEL_NO_ITTNOTIFY_API
1408 ITT_STUBV(ITTAPI, void, model_disable_push, (__itt_model_disable x))
1409 ITT_STUBV(ITTAPI, void, model_disable_pop, (void))
1410 ITT_STUBV(ITTAPI, void, model_aggregate_task, (size_t x))
1411 #define __itt_model_disable_push ITTNOTIFY_VOID(model_disable_push)
1412 #define __itt_model_disable_push_ptr ITTNOTIFY_NAME(model_disable_push)
1413 #define __itt_model_disable_pop ITTNOTIFY_VOID(model_disable_pop)
1414 #define __itt_model_disable_pop_ptr ITTNOTIFY_NAME(model_disable_pop)
1415 #define __itt_model_aggregate_task ITTNOTIFY_VOID(model_aggregate_task)
1416 #define __itt_model_aggregate_task_ptr ITTNOTIFY_NAME(model_aggregate_task)
1417 #else /* INTEL_NO_ITTNOTIFY_API */
1418 #define __itt_model_disable_push(x)
1419 #define __itt_model_disable_push_ptr 0
1420 #define __itt_model_disable_pop()
1421 #define __itt_model_disable_pop_ptr 0
1422 #define __itt_model_aggregate_task(x)
1423 #define __itt_model_aggregate_task_ptr 0
1424 #endif /* INTEL_NO_ITTNOTIFY_API */
1425 #else /* INTEL_NO_MACRO_BODY */
1426 #define __itt_model_disable_push_ptr 0
1427 #define __itt_model_disable_pop_ptr 0
1428 #define __itt_model_aggregate_task_ptr 0
1429 #endif /* INTEL_NO_MACRO_BODY */
1430 /** @endcond */
1431 /** @} model group */
1432
1433 /**
1434 * @defgroup heap Heap
1435 * @ingroup public
1436 * Heap group
1437 * @{
1438 */
1439
1440 typedef void* __itt_heap_function;
1441
1442 /**
1443 * @brief Create an identification for heap function
1444 * @return non-zero identifier or NULL
1445 */
1446 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1447 __itt_heap_function ITTAPI __itt_heap_function_createA(const char* name, const char* domain);
1448 __itt_heap_function ITTAPI __itt_heap_function_createW(const wchar_t* name, const wchar_t* domain);
1449 #if defined(UNICODE) || defined(_UNICODE)
1450 # define __itt_heap_function_create __itt_heap_function_createW
1451 # define __itt_heap_function_create_ptr __itt_heap_function_createW_ptr
1452 #else
1453 # define __itt_heap_function_create __itt_heap_function_createA
1454 # define __itt_heap_function_create_ptr __itt_heap_function_createA_ptr
1455 #endif /* UNICODE */
1456 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1457 __itt_heap_function ITTAPI __itt_heap_function_create(const char* name, const char* domain);
1458 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1459
1460 /** @cond exclude_from_documentation */
1461 #ifndef INTEL_NO_MACRO_BODY
1462 #ifndef INTEL_NO_ITTNOTIFY_API
1463 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1464 ITT_STUB(ITTAPI, __itt_heap_function, heap_function_createA, (const char* name, const char* domain))
1465 ITT_STUB(ITTAPI, __itt_heap_function, heap_function_createW, (const wchar_t* name, const wchar_t* domain))
1466 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1467 ITT_STUB(ITTAPI, __itt_heap_function, heap_function_create, (const char* name, const char* domain))
1468 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1469 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1470 #define __itt_heap_function_createA ITTNOTIFY_DATA(heap_function_createA)
1471 #define __itt_heap_function_createA_ptr ITTNOTIFY_NAME(heap_function_createA)
1472 #define __itt_heap_function_createW ITTNOTIFY_DATA(heap_function_createW)
1473 #define __itt_heap_function_createW_ptr ITTNOTIFY_NAME(heap_function_createW)
1474 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1475 #define __itt_heap_function_create ITTNOTIFY_DATA(heap_function_create)
1476 #define __itt_heap_function_create_ptr ITTNOTIFY_NAME(heap_function_create)
1477 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1478 #else /* INTEL_NO_ITTNOTIFY_API */
1479 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1480 #define __itt_heap_function_createA(name, domain) (__itt_heap_function)0
1481 #define __itt_heap_function_createA_ptr 0
1482 #define __itt_heap_function_createW(name, domain) (__itt_heap_function)0
1483 #define __itt_heap_function_createW_ptr 0
1484 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1485 #define __itt_heap_function_create(name, domain) (__itt_heap_function)0
1486 #define __itt_heap_function_create_ptr 0
1487 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1488 #endif /* INTEL_NO_ITTNOTIFY_API */
1489 #else /* INTEL_NO_MACRO_BODY */
1490 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1491 #define __itt_heap_function_createA_ptr 0
1492 #define __itt_heap_function_createW_ptr 0
1493 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1494 #define __itt_heap_function_create_ptr 0
1495 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1496 #endif /* INTEL_NO_MACRO_BODY */
1497 /** @endcond */
1498
1499 /**
1500 * @brief Record an allocation begin occurrence.
1501 */
1502 void ITTAPI __itt_heap_allocate_begin(__itt_heap_function h, size_t size, int initialized);
1503
1504 /** @cond exclude_from_documentation */
1505 #ifndef INTEL_NO_MACRO_BODY
1506 #ifndef INTEL_NO_ITTNOTIFY_API
1507 ITT_STUBV(ITTAPI, void, heap_allocate_begin, (__itt_heap_function h, size_t size, int initialized))
1508 #define __itt_heap_allocate_begin ITTNOTIFY_VOID(heap_allocate_begin)
1509 #define __itt_heap_allocate_begin_ptr ITTNOTIFY_NAME(heap_allocate_begin)
1510 #else /* INTEL_NO_ITTNOTIFY_API */
1511 #define __itt_heap_allocate_begin(h, size, initialized)
1512 #define __itt_heap_allocate_begin_ptr 0
1513 #endif /* INTEL_NO_ITTNOTIFY_API */
1514 #else /* INTEL_NO_MACRO_BODY */
1515 #define __itt_heap_allocate_begin_ptr 0
1516 #endif /* INTEL_NO_MACRO_BODY */
1517 /** @endcond */
1518
1519 /**
1520 * @brief Record an allocation end occurrence.
1521 */
1522 void ITTAPI __itt_heap_allocate_end(__itt_heap_function h, void** addr, size_t size, int initialized);
1523
1524 /** @cond exclude_from_documentation */
1525 #ifndef INTEL_NO_MACRO_BODY
1526 #ifndef INTEL_NO_ITTNOTIFY_API
1527 ITT_STUBV(ITTAPI, void, heap_allocate_end, (__itt_heap_function h, void** addr, size_t size, int initialized))
1528 #define __itt_heap_allocate_end ITTNOTIFY_VOID(heap_allocate_end)
1529 #define __itt_heap_allocate_end_ptr ITTNOTIFY_NAME(heap_allocate_end)
1530 #else /* INTEL_NO_ITTNOTIFY_API */
1531 #define __itt_heap_allocate_end(h, addr, size, initialized)
1532 #define __itt_heap_allocate_end_ptr 0
1533 #endif /* INTEL_NO_ITTNOTIFY_API */
1534 #else /* INTEL_NO_MACRO_BODY */
1535 #define __itt_heap_allocate_end_ptr 0
1536 #endif /* INTEL_NO_MACRO_BODY */
1537 /** @endcond */
1538
1539 /**
1540 * @brief Record a free begin occurrence.
1541 */
1542 void ITTAPI __itt_heap_free_begin(__itt_heap_function h, void* addr);
1543
1544 /** @cond exclude_from_documentation */
1545 #ifndef INTEL_NO_MACRO_BODY
1546 #ifndef INTEL_NO_ITTNOTIFY_API
1547 ITT_STUBV(ITTAPI, void, heap_free_begin, (__itt_heap_function h, void* addr))
1548 #define __itt_heap_free_begin ITTNOTIFY_VOID(heap_free_begin)
1549 #define __itt_heap_free_begin_ptr ITTNOTIFY_NAME(heap_free_begin)
1550 #else /* INTEL_NO_ITTNOTIFY_API */
1551 #define __itt_heap_free_begin(h, addr)
1552 #define __itt_heap_free_begin_ptr 0
1553 #endif /* INTEL_NO_ITTNOTIFY_API */
1554 #else /* INTEL_NO_MACRO_BODY */
1555 #define __itt_heap_free_begin_ptr 0
1556 #endif /* INTEL_NO_MACRO_BODY */
1557 /** @endcond */
1558
1559 /**
1560 * @brief Record a free end occurrence.
1561 */
1562 void ITTAPI __itt_heap_free_end(__itt_heap_function h, void* addr);
1563
1564 /** @cond exclude_from_documentation */
1565 #ifndef INTEL_NO_MACRO_BODY
1566 #ifndef INTEL_NO_ITTNOTIFY_API
1567 ITT_STUBV(ITTAPI, void, heap_free_end, (__itt_heap_function h, void* addr))
1568 #define __itt_heap_free_end ITTNOTIFY_VOID(heap_free_end)
1569 #define __itt_heap_free_end_ptr ITTNOTIFY_NAME(heap_free_end)
1570 #else /* INTEL_NO_ITTNOTIFY_API */
1571 #define __itt_heap_free_end(h, addr)
1572 #define __itt_heap_free_end_ptr 0
1573 #endif /* INTEL_NO_ITTNOTIFY_API */
1574 #else /* INTEL_NO_MACRO_BODY */
1575 #define __itt_heap_free_end_ptr 0
1576 #endif /* INTEL_NO_MACRO_BODY */
1577 /** @endcond */
1578
1579 /**
1580 * @brief Record a reallocation begin occurrence.
1581 */
1582 void ITTAPI __itt_heap_reallocate_begin(__itt_heap_function h, void* addr, size_t new_size, int initialized);
1583
1584 /** @cond exclude_from_documentation */
1585 #ifndef INTEL_NO_MACRO_BODY
1586 #ifndef INTEL_NO_ITTNOTIFY_API
1587 ITT_STUBV(ITTAPI, void, heap_reallocate_begin, (__itt_heap_function h, void* addr, size_t new_size, int initialized))
1588 #define __itt_heap_reallocate_begin ITTNOTIFY_VOID(heap_reallocate_begin)
1589 #define __itt_heap_reallocate_begin_ptr ITTNOTIFY_NAME(heap_reallocate_begin)
1590 #else /* INTEL_NO_ITTNOTIFY_API */
1591 #define __itt_heap_reallocate_begin(h, addr, new_size, initialized)
1592 #define __itt_heap_reallocate_begin_ptr 0
1593 #endif /* INTEL_NO_ITTNOTIFY_API */
1594 #else /* INTEL_NO_MACRO_BODY */
1595 #define __itt_heap_reallocate_begin_ptr 0
1596 #endif /* INTEL_NO_MACRO_BODY */
1597 /** @endcond */
1598
1599 /**
1600 * @brief Record a reallocation end occurrence.
1601 */
1602 void ITTAPI __itt_heap_reallocate_end(__itt_heap_function h, void* addr, void** new_addr, size_t new_size, int initialized);
1603
1604 /** @cond exclude_from_documentation */
1605 #ifndef INTEL_NO_MACRO_BODY
1606 #ifndef INTEL_NO_ITTNOTIFY_API
1607 ITT_STUBV(ITTAPI, void, heap_reallocate_end, (__itt_heap_function h, void* addr, void** new_addr, size_t new_size, int initialized))
1608 #define __itt_heap_reallocate_end ITTNOTIFY_VOID(heap_reallocate_end)
1609 #define __itt_heap_reallocate_end_ptr ITTNOTIFY_NAME(heap_reallocate_end)
1610 #else /* INTEL_NO_ITTNOTIFY_API */
1611 #define __itt_heap_reallocate_end(h, addr, new_addr, new_size, initialized)
1612 #define __itt_heap_reallocate_end_ptr 0
1613 #endif /* INTEL_NO_ITTNOTIFY_API */
1614 #else /* INTEL_NO_MACRO_BODY */
1615 #define __itt_heap_reallocate_end_ptr 0
1616 #endif /* INTEL_NO_MACRO_BODY */
1617 /** @endcond */
1618
1619 /** @brief internal access begin */
1620 void ITTAPI __itt_heap_internal_access_begin(void);
1621
1622 /** @cond exclude_from_documentation */
1623 #ifndef INTEL_NO_MACRO_BODY
1624 #ifndef INTEL_NO_ITTNOTIFY_API
1625 ITT_STUBV(ITTAPI, void, heap_internal_access_begin, (void))
1626 #define __itt_heap_internal_access_begin ITTNOTIFY_VOID(heap_internal_access_begin)
1627 #define __itt_heap_internal_access_begin_ptr ITTNOTIFY_NAME(heap_internal_access_begin)
1628 #else /* INTEL_NO_ITTNOTIFY_API */
1629 #define __itt_heap_internal_access_begin()
1630 #define __itt_heap_internal_access_begin_ptr 0
1631 #endif /* INTEL_NO_ITTNOTIFY_API */
1632 #else /* INTEL_NO_MACRO_BODY */
1633 #define __itt_heap_internal_access_begin_ptr 0
1634 #endif /* INTEL_NO_MACRO_BODY */
1635 /** @endcond */
1636
1637 /** @brief internal access end */
1638 void ITTAPI __itt_heap_internal_access_end(void);
1639
1640 /** @cond exclude_from_documentation */
1641 #ifndef INTEL_NO_MACRO_BODY
1642 #ifndef INTEL_NO_ITTNOTIFY_API
1643 ITT_STUBV(ITTAPI, void, heap_internal_access_end, (void))
1644 #define __itt_heap_internal_access_end ITTNOTIFY_VOID(heap_internal_access_end)
1645 #define __itt_heap_internal_access_end_ptr ITTNOTIFY_NAME(heap_internal_access_end)
1646 #else /* INTEL_NO_ITTNOTIFY_API */
1647 #define __itt_heap_internal_access_end()
1648 #define __itt_heap_internal_access_end_ptr 0
1649 #endif /* INTEL_NO_ITTNOTIFY_API */
1650 #else /* INTEL_NO_MACRO_BODY */
1651 #define __itt_heap_internal_access_end_ptr 0
1652 #endif /* INTEL_NO_MACRO_BODY */
1653 /** @endcond */
1654
1655 /** @brief record memory growth begin */
1656 void ITTAPI __itt_heap_record_memory_growth_begin(void);
1657
1658 /** @cond exclude_from_documentation */
1659 #ifndef INTEL_NO_MACRO_BODY
1660 #ifndef INTEL_NO_ITTNOTIFY_API
1661 ITT_STUBV(ITTAPI, void, heap_record_memory_growth_begin, (void))
1662 #define __itt_heap_record_memory_growth_begin ITTNOTIFY_VOID(heap_record_memory_growth_begin)
1663 #define __itt_heap_record_memory_growth_begin_ptr ITTNOTIFY_NAME(heap_record_memory_growth_begin)
1664 #else /* INTEL_NO_ITTNOTIFY_API */
1665 #define __itt_heap_record_memory_growth_begin()
1666 #define __itt_heap_record_memory_growth_begin_ptr 0
1667 #endif /* INTEL_NO_ITTNOTIFY_API */
1668 #else /* INTEL_NO_MACRO_BODY */
1669 #define __itt_heap_record_memory_growth_begin_ptr 0
1670 #endif /* INTEL_NO_MACRO_BODY */
1671 /** @endcond */
1672
1673 /** @brief record memory growth end */
1674 void ITTAPI __itt_heap_record_memory_growth_end(void);
1675
1676 /** @cond exclude_from_documentation */
1677 #ifndef INTEL_NO_MACRO_BODY
1678 #ifndef INTEL_NO_ITTNOTIFY_API
1679 ITT_STUBV(ITTAPI, void, heap_record_memory_growth_end, (void))
1680 #define __itt_heap_record_memory_growth_end ITTNOTIFY_VOID(heap_record_memory_growth_end)
1681 #define __itt_heap_record_memory_growth_end_ptr ITTNOTIFY_NAME(heap_record_memory_growth_end)
1682 #else /* INTEL_NO_ITTNOTIFY_API */
1683 #define __itt_heap_record_memory_growth_end()
1684 #define __itt_heap_record_memory_growth_end_ptr 0
1685 #endif /* INTEL_NO_ITTNOTIFY_API */
1686 #else /* INTEL_NO_MACRO_BODY */
1687 #define __itt_heap_record_memory_growth_end_ptr 0
1688 #endif /* INTEL_NO_MACRO_BODY */
1689 /** @endcond */
1690
1691 /**
1692 * @brief Specify the type of heap detection/reporting to modify.
1693 */
1694 /**
1695 * @hideinitializer
1696 * @brief Report on memory leaks.
1697 */
1698 #define __itt_heap_leaks 0x00000001
1699
1700 /**
1701 * @hideinitializer
1702 * @brief Report on memory growth.
1703 */
1704 #define __itt_heap_growth 0x00000002
1705
1706
1707 /** @brief heap reset detection */
1708 void ITTAPI __itt_heap_reset_detection(unsigned int reset_mask);
1709
1710 /** @cond exclude_from_documentation */
1711 #ifndef INTEL_NO_MACRO_BODY
1712 #ifndef INTEL_NO_ITTNOTIFY_API
1713 ITT_STUBV(ITTAPI, void, heap_reset_detection, (unsigned int reset_mask))
1714 #define __itt_heap_reset_detection ITTNOTIFY_VOID(heap_reset_detection)
1715 #define __itt_heap_reset_detection_ptr ITTNOTIFY_NAME(heap_reset_detection)
1716 #else /* INTEL_NO_ITTNOTIFY_API */
1717 #define __itt_heap_reset_detection()
1718 #define __itt_heap_reset_detection_ptr 0
1719 #endif /* INTEL_NO_ITTNOTIFY_API */
1720 #else /* INTEL_NO_MACRO_BODY */
1721 #define __itt_heap_reset_detection_ptr 0
1722 #endif /* INTEL_NO_MACRO_BODY */
1723 /** @endcond */
1724
1725 /** @brief report */
1726 void ITTAPI __itt_heap_record(unsigned int record_mask);
1727
1728 /** @cond exclude_from_documentation */
1729 #ifndef INTEL_NO_MACRO_BODY
1730 #ifndef INTEL_NO_ITTNOTIFY_API
1731 ITT_STUBV(ITTAPI, void, heap_record, (unsigned int record_mask))
1732 #define __itt_heap_record ITTNOTIFY_VOID(heap_record)
1733 #define __itt_heap_record_ptr ITTNOTIFY_NAME(heap_record)
1734 #else /* INTEL_NO_ITTNOTIFY_API */
1735 #define __itt_heap_record()
1736 #define __itt_heap_record_ptr 0
1737 #endif /* INTEL_NO_ITTNOTIFY_API */
1738 #else /* INTEL_NO_MACRO_BODY */
1739 #define __itt_heap_record_ptr 0
1740 #endif /* INTEL_NO_MACRO_BODY */
1741 /** @endcond */
1742
1743 /** @} heap group */
1744 /** @endcond */
1745 /* ========================================================================== */
1746
1747 /**
1748 * @defgroup domains Domains
1749 * @ingroup public
1750 * Domains group
1751 * @{
1752 */
1753
1754 /** @cond exclude_from_documentation */
1755 #pragma pack(push, 8)
1756
1757 typedef struct ___itt_domain
1758 {
1759 volatile int flags; /*!< Zero if disabled, non-zero if enabled. The meaning of different non-zero values is reserved to the runtime */
1760 const char* nameA; /*!< Copy of original name in ASCII. */
1761 #if defined(UNICODE) || defined(_UNICODE)
1762 const wchar_t* nameW; /*!< Copy of original name in UNICODE. */
1763 #else /* UNICODE || _UNICODE */
1764 void* nameW;
1765 #endif /* UNICODE || _UNICODE */
1766 int extra1; /*!< Reserved to the runtime */
1767 void* extra2; /*!< Reserved to the runtime */
1768 struct ___itt_domain* next;
1769 } __itt_domain;
1770
1771 #pragma pack(pop)
1772 /** @endcond */
1773
1774 /**
1775 * @ingroup domains
1776 * @brief Create a domain.
1777 * Create domain using some domain name: the URI naming style is recommended.
1778 * Because the set of domains is expected to be static over the application's
1779 * execution time, there is no mechanism to destroy a domain.
1780 * Any domain can be accessed by any thread in the process, regardless of
1781 * which thread created the domain. This call is thread-safe.
1782 * @param[in] name name of domain
1783 */
1784 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1785 __itt_domain* ITTAPI __itt_domain_createA(const char *name);
1786 __itt_domain* ITTAPI __itt_domain_createW(const wchar_t *name);
1787 #if defined(UNICODE) || defined(_UNICODE)
1788 # define __itt_domain_create __itt_domain_createW
1789 # define __itt_domain_create_ptr __itt_domain_createW_ptr
1790 #else /* UNICODE */
1791 # define __itt_domain_create __itt_domain_createA
1792 # define __itt_domain_create_ptr __itt_domain_createA_ptr
1793 #endif /* UNICODE */
1794 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1795 __itt_domain* ITTAPI __itt_domain_create(const char *name);
1796 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1797
1798 /** @cond exclude_from_documentation */
1799 #ifndef INTEL_NO_MACRO_BODY
1800 #ifndef INTEL_NO_ITTNOTIFY_API
1801 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1802 ITT_STUB(ITTAPI, __itt_domain*, domain_createA, (const char *name))
1803 ITT_STUB(ITTAPI, __itt_domain*, domain_createW, (const wchar_t *name))
1804 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1805 ITT_STUB(ITTAPI, __itt_domain*, domain_create, (const char *name))
1806 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1807 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1808 #define __itt_domain_createA ITTNOTIFY_DATA(domain_createA)
1809 #define __itt_domain_createA_ptr ITTNOTIFY_NAME(domain_createA)
1810 #define __itt_domain_createW ITTNOTIFY_DATA(domain_createW)
1811 #define __itt_domain_createW_ptr ITTNOTIFY_NAME(domain_createW)
1812 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1813 #define __itt_domain_create ITTNOTIFY_DATA(domain_create)
1814 #define __itt_domain_create_ptr ITTNOTIFY_NAME(domain_create)
1815 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1816 #else /* INTEL_NO_ITTNOTIFY_API */
1817 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1818 #define __itt_domain_createA(name) (__itt_domain*)0
1819 #define __itt_domain_createA_ptr 0
1820 #define __itt_domain_createW(name) (__itt_domain*)0
1821 #define __itt_domain_createW_ptr 0
1822 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1823 #define __itt_domain_create(name) (__itt_domain*)0
1824 #define __itt_domain_create_ptr 0
1825 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1826 #endif /* INTEL_NO_ITTNOTIFY_API */
1827 #else /* INTEL_NO_MACRO_BODY */
1828 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1829 #define __itt_domain_createA_ptr 0
1830 #define __itt_domain_createW_ptr 0
1831 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1832 #define __itt_domain_create_ptr 0
1833 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1834 #endif /* INTEL_NO_MACRO_BODY */
1835 /** @endcond */
1836 /** @} domains group */
1837
1838 /**
1839 * @defgroup ids IDs
1840 * @ingroup public
1841 * IDs group
1842 * @{
1843 */
1844
1845 /** @cond exclude_from_documentation */
1846 #pragma pack(push, 8)
1847
1848 typedef struct ___itt_id
1849 {
1850 unsigned long long d1, d2, d3;
1851 } __itt_id;
1852
1853 #pragma pack(pop)
1854 /** @endcond */
1855
1856 static const __itt_id __itt_null = { 0, 0, 0 };
1857
1858 /**
1859 * @ingroup ids
1860 * @brief A convenience function is provided to create an ID without domain control.
1861 * @brief This is a convenience function to initialize an __itt_id structure. This function
1862 * does not affect the collector runtime in any way. After you make the ID with this
1863 * function, you still must create it with the __itt_id_create function before using the ID
1864 * to identify a named entity.
1865 * @param[in] addr The address of object; high QWORD of the ID value.
1866 * @param[in] extra The extra data to unique identify object; low QWORD of the ID value.
1867 */
1868
1869 ITT_INLINE __itt_id ITTAPI __itt_id_make(void* addr, unsigned long long extra) ITT_INLINE_ATTRIBUTE;
__itt_id_make(void * addr,unsigned long long extra)1870 ITT_INLINE __itt_id ITTAPI __itt_id_make(void* addr, unsigned long long extra)
1871 {
1872 __itt_id id = __itt_null;
1873 id.d1 = (unsigned long long)((uintptr_t)addr);
1874 id.d2 = (unsigned long long)extra;
1875 id.d3 = (unsigned long long)0; /* Reserved. Must be zero */
1876 return id;
1877 }
1878
1879 /**
1880 * @ingroup ids
1881 * @brief Create an instance of identifier.
1882 * This establishes the beginning of the lifetime of an instance of
1883 * the given ID in the trace. Once this lifetime starts, the ID
1884 * can be used to tag named entity instances in calls such as
1885 * __itt_task_begin, and to specify relationships among
1886 * identified named entity instances, using the \ref relations APIs.
1887 * Instance IDs are not domain specific!
1888 * @param[in] domain The domain controlling the execution of this call.
1889 * @param[in] id The ID to create.
1890 */
1891 void ITTAPI __itt_id_create(const __itt_domain *domain, __itt_id id);
1892
1893 /** @cond exclude_from_documentation */
1894 #ifndef INTEL_NO_MACRO_BODY
1895 #ifndef INTEL_NO_ITTNOTIFY_API
1896 ITT_STUBV(ITTAPI, void, id_create, (const __itt_domain *domain, __itt_id id))
1897 #define __itt_id_create(d,x) ITTNOTIFY_VOID_D1(id_create,d,x)
1898 #define __itt_id_create_ptr ITTNOTIFY_NAME(id_create)
1899 #else /* INTEL_NO_ITTNOTIFY_API */
1900 #define __itt_id_create(domain,id)
1901 #define __itt_id_create_ptr 0
1902 #endif /* INTEL_NO_ITTNOTIFY_API */
1903 #else /* INTEL_NO_MACRO_BODY */
1904 #define __itt_id_create_ptr 0
1905 #endif /* INTEL_NO_MACRO_BODY */
1906 /** @endcond */
1907
1908 /**
1909 * @ingroup ids
1910 * @brief Destroy an instance of identifier.
1911 * This ends the lifetime of the current instance of the given ID value in the trace.
1912 * Any relationships that are established after this lifetime ends are invalid.
1913 * This call must be performed before the given ID value can be reused for a different
1914 * named entity instance.
1915 * @param[in] domain The domain controlling the execution of this call.
1916 * @param[in] id The ID to destroy.
1917 */
1918 void ITTAPI __itt_id_destroy(const __itt_domain *domain, __itt_id id);
1919
1920 /** @cond exclude_from_documentation */
1921 #ifndef INTEL_NO_MACRO_BODY
1922 #ifndef INTEL_NO_ITTNOTIFY_API
1923 ITT_STUBV(ITTAPI, void, id_destroy, (const __itt_domain *domain, __itt_id id))
1924 #define __itt_id_destroy(d,x) ITTNOTIFY_VOID_D1(id_destroy,d,x)
1925 #define __itt_id_destroy_ptr ITTNOTIFY_NAME(id_destroy)
1926 #else /* INTEL_NO_ITTNOTIFY_API */
1927 #define __itt_id_destroy(domain,id)
1928 #define __itt_id_destroy_ptr 0
1929 #endif /* INTEL_NO_ITTNOTIFY_API */
1930 #else /* INTEL_NO_MACRO_BODY */
1931 #define __itt_id_destroy_ptr 0
1932 #endif /* INTEL_NO_MACRO_BODY */
1933 /** @endcond */
1934 /** @} ids group */
1935
1936 /**
1937 * @defgroup handless String Handles
1938 * @ingroup public
1939 * String Handles group
1940 * @{
1941 */
1942
1943 /** @cond exclude_from_documentation */
1944 #pragma pack(push, 8)
1945
1946 typedef struct ___itt_string_handle
1947 {
1948 const char* strA; /*!< Copy of original string in ASCII. */
1949 #if defined(UNICODE) || defined(_UNICODE)
1950 const wchar_t* strW; /*!< Copy of original string in UNICODE. */
1951 #else /* UNICODE || _UNICODE */
1952 void* strW;
1953 #endif /* UNICODE || _UNICODE */
1954 int extra1; /*!< Reserved. Must be zero */
1955 void* extra2; /*!< Reserved. Must be zero */
1956 struct ___itt_string_handle* next;
1957 } __itt_string_handle;
1958
1959 #pragma pack(pop)
1960 /** @endcond */
1961
1962 /**
1963 * @ingroup handles
1964 * @brief Create a string handle.
1965 * Create and return handle value that can be associated with a string.
1966 * Consecutive calls to __itt_string_handle_create with the same name
1967 * return the same value. Because the set of string handles is expected to remain
1968 * static during the application's execution time, there is no mechanism to destroy a string handle.
1969 * Any string handle can be accessed by any thread in the process, regardless of which thread created
1970 * the string handle. This call is thread-safe.
1971 * @param[in] name The input string
1972 */
1973 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1974 __itt_string_handle* ITTAPI __itt_string_handle_createA(const char *name);
1975 __itt_string_handle* ITTAPI __itt_string_handle_createW(const wchar_t *name);
1976 #if defined(UNICODE) || defined(_UNICODE)
1977 # define __itt_string_handle_create __itt_string_handle_createW
1978 # define __itt_string_handle_create_ptr __itt_string_handle_createW_ptr
1979 #else /* UNICODE */
1980 # define __itt_string_handle_create __itt_string_handle_createA
1981 # define __itt_string_handle_create_ptr __itt_string_handle_createA_ptr
1982 #endif /* UNICODE */
1983 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1984 __itt_string_handle* ITTAPI __itt_string_handle_create(const char *name);
1985 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1986
1987 /** @cond exclude_from_documentation */
1988 #ifndef INTEL_NO_MACRO_BODY
1989 #ifndef INTEL_NO_ITTNOTIFY_API
1990 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1991 ITT_STUB(ITTAPI, __itt_string_handle*, string_handle_createA, (const char *name))
1992 ITT_STUB(ITTAPI, __itt_string_handle*, string_handle_createW, (const wchar_t *name))
1993 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1994 ITT_STUB(ITTAPI, __itt_string_handle*, string_handle_create, (const char *name))
1995 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
1996 #if ITT_PLATFORM==ITT_PLATFORM_WIN
1997 #define __itt_string_handle_createA ITTNOTIFY_DATA(string_handle_createA)
1998 #define __itt_string_handle_createA_ptr ITTNOTIFY_NAME(string_handle_createA)
1999 #define __itt_string_handle_createW ITTNOTIFY_DATA(string_handle_createW)
2000 #define __itt_string_handle_createW_ptr ITTNOTIFY_NAME(string_handle_createW)
2001 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2002 #define __itt_string_handle_create ITTNOTIFY_DATA(string_handle_create)
2003 #define __itt_string_handle_create_ptr ITTNOTIFY_NAME(string_handle_create)
2004 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2005 #else /* INTEL_NO_ITTNOTIFY_API */
2006 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2007 #define __itt_string_handle_createA(name) (__itt_string_handle*)0
2008 #define __itt_string_handle_createA_ptr 0
2009 #define __itt_string_handle_createW(name) (__itt_string_handle*)0
2010 #define __itt_string_handle_createW_ptr 0
2011 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2012 #define __itt_string_handle_create(name) (__itt_string_handle*)0
2013 #define __itt_string_handle_create_ptr 0
2014 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2015 #endif /* INTEL_NO_ITTNOTIFY_API */
2016 #else /* INTEL_NO_MACRO_BODY */
2017 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2018 #define __itt_string_handle_createA_ptr 0
2019 #define __itt_string_handle_createW_ptr 0
2020 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2021 #define __itt_string_handle_create_ptr 0
2022 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2023 #endif /* INTEL_NO_MACRO_BODY */
2024 /** @endcond */
2025 /** @} handles group */
2026
2027 /** @cond exclude_from_documentation */
2028 typedef unsigned long long __itt_timestamp;
2029 /** @endcond */
2030
2031 #define __itt_timestamp_none ((__itt_timestamp)-1LL)
2032
2033 /** @cond exclude_from_gpa_documentation */
2034
2035 /**
2036 * @ingroup timestamps
2037 * @brief Return timestamp corresponding to the current moment.
2038 * This returns the timestamp in the format that is the most relevant for the current
2039 * host or platform (RDTSC, QPC, and others). You can use the "<" operator to
2040 * compare __itt_timestamp values.
2041 */
2042 __itt_timestamp ITTAPI __itt_get_timestamp(void);
2043
2044 /** @cond exclude_from_documentation */
2045 #ifndef INTEL_NO_MACRO_BODY
2046 #ifndef INTEL_NO_ITTNOTIFY_API
2047 ITT_STUB(ITTAPI, __itt_timestamp, get_timestamp, (void))
2048 #define __itt_get_timestamp ITTNOTIFY_DATA(get_timestamp)
2049 #define __itt_get_timestamp_ptr ITTNOTIFY_NAME(get_timestamp)
2050 #else /* INTEL_NO_ITTNOTIFY_API */
2051 #define __itt_get_timestamp()
2052 #define __itt_get_timestamp_ptr 0
2053 #endif /* INTEL_NO_ITTNOTIFY_API */
2054 #else /* INTEL_NO_MACRO_BODY */
2055 #define __itt_get_timestamp_ptr 0
2056 #endif /* INTEL_NO_MACRO_BODY */
2057 /** @endcond */
2058 /** @} timestamps */
2059 /** @endcond */
2060
2061 /** @cond exclude_from_gpa_documentation */
2062
2063 /**
2064 * @defgroup regions Regions
2065 * @ingroup public
2066 * Regions group
2067 * @{
2068 */
2069 /**
2070 * @ingroup regions
2071 * @brief Begin of region instance.
2072 * Successive calls to __itt_region_begin with the same ID are ignored
2073 * until a call to __itt_region_end with the same ID
2074 * @param[in] domain The domain for this region instance
2075 * @param[in] id The instance ID for this region instance. Must not be __itt_null
2076 * @param[in] parentid The instance ID for the parent of this region instance, or __itt_null
2077 * @param[in] name The name of this region
2078 */
2079 void ITTAPI __itt_region_begin(const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name);
2080
2081 /**
2082 * @ingroup regions
2083 * @brief End of region instance.
2084 * The first call to __itt_region_end with a given ID ends the
2085 * region. Successive calls with the same ID are ignored, as are
2086 * calls that do not have a matching __itt_region_begin call.
2087 * @param[in] domain The domain for this region instance
2088 * @param[in] id The instance ID for this region instance
2089 */
2090 void ITTAPI __itt_region_end(const __itt_domain *domain, __itt_id id);
2091
2092 /** @cond exclude_from_documentation */
2093 #ifndef INTEL_NO_MACRO_BODY
2094 #ifndef INTEL_NO_ITTNOTIFY_API
2095 ITT_STUBV(ITTAPI, void, region_begin, (const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name))
2096 ITT_STUBV(ITTAPI, void, region_end, (const __itt_domain *domain, __itt_id id))
2097 #define __itt_region_begin(d,x,y,z) ITTNOTIFY_VOID_D3(region_begin,d,x,y,z)
2098 #define __itt_region_begin_ptr ITTNOTIFY_NAME(region_begin)
2099 #define __itt_region_end(d,x) ITTNOTIFY_VOID_D1(region_end,d,x)
2100 #define __itt_region_end_ptr ITTNOTIFY_NAME(region_end)
2101 #else /* INTEL_NO_ITTNOTIFY_API */
2102 #define __itt_region_begin(d,x,y,z)
2103 #define __itt_region_begin_ptr 0
2104 #define __itt_region_end(d,x)
2105 #define __itt_region_end_ptr 0
2106 #endif /* INTEL_NO_ITTNOTIFY_API */
2107 #else /* INTEL_NO_MACRO_BODY */
2108 #define __itt_region_begin_ptr 0
2109 #define __itt_region_end_ptr 0
2110 #endif /* INTEL_NO_MACRO_BODY */
2111 /** @endcond */
2112 /** @} regions group */
2113
2114 /**
2115 * @defgroup frames Frames
2116 * @ingroup public
2117 * Frames are similar to regions, but are intended to be easier to use and to implement.
2118 * In particular:
2119 * - Frames always represent periods of elapsed time
2120 * - By default, frames have no nesting relationships
2121 * @{
2122 */
2123
2124 /**
2125 * @ingroup frames
2126 * @brief Begin a frame instance.
2127 * Successive calls to __itt_frame_begin with the
2128 * same ID are ignored until a call to __itt_frame_end with the same ID.
2129 * @param[in] domain The domain for this frame instance
2130 * @param[in] id The instance ID for this frame instance or NULL
2131 */
2132 void ITTAPI __itt_frame_begin_v3(const __itt_domain *domain, __itt_id *id);
2133
2134 /**
2135 * @ingroup frames
2136 * @brief End a frame instance.
2137 * The first call to __itt_frame_end with a given ID
2138 * ends the frame. Successive calls with the same ID are ignored, as are
2139 * calls that do not have a matching __itt_frame_begin call.
2140 * @param[in] domain The domain for this frame instance
2141 * @param[in] id The instance ID for this frame instance or NULL for current
2142 */
2143 void ITTAPI __itt_frame_end_v3(const __itt_domain *domain, __itt_id *id);
2144
2145 /**
2146 * @ingroup frames
2147 * @brief Submits a frame instance.
2148 * Successive calls to __itt_frame_begin or __itt_frame_submit with the
2149 * same ID are ignored until a call to __itt_frame_end or __itt_frame_submit
2150 * with the same ID.
2151 * Passing special __itt_timestamp_none value as "end" argument means
2152 * take the current timestamp as the end timestamp.
2153 * @param[in] domain The domain for this frame instance
2154 * @param[in] id The instance ID for this frame instance or NULL
2155 * @param[in] begin Timestamp of the beginning of the frame
2156 * @param[in] end Timestamp of the end of the frame
2157 */
2158 void ITTAPI __itt_frame_submit_v3(const __itt_domain *domain, __itt_id *id,
2159 __itt_timestamp begin, __itt_timestamp end);
2160
2161 /** @cond exclude_from_documentation */
2162 #ifndef INTEL_NO_MACRO_BODY
2163 #ifndef INTEL_NO_ITTNOTIFY_API
2164 ITT_STUBV(ITTAPI, void, frame_begin_v3, (const __itt_domain *domain, __itt_id *id))
2165 ITT_STUBV(ITTAPI, void, frame_end_v3, (const __itt_domain *domain, __itt_id *id))
2166 ITT_STUBV(ITTAPI, void, frame_submit_v3, (const __itt_domain *domain, __itt_id *id, __itt_timestamp begin, __itt_timestamp end))
2167 #define __itt_frame_begin_v3(d,x) ITTNOTIFY_VOID_D1(frame_begin_v3,d,x)
2168 #define __itt_frame_begin_v3_ptr ITTNOTIFY_NAME(frame_begin_v3)
2169 #define __itt_frame_end_v3(d,x) ITTNOTIFY_VOID_D1(frame_end_v3,d,x)
2170 #define __itt_frame_end_v3_ptr ITTNOTIFY_NAME(frame_end_v3)
2171 #define __itt_frame_submit_v3(d,x,b,e) ITTNOTIFY_VOID_D3(frame_submit_v3,d,x,b,e)
2172 #define __itt_frame_submit_v3_ptr ITTNOTIFY_NAME(frame_submit_v3)
2173 #else /* INTEL_NO_ITTNOTIFY_API */
2174 #define __itt_frame_begin_v3(domain,id)
2175 #define __itt_frame_begin_v3_ptr 0
2176 #define __itt_frame_end_v3(domain,id)
2177 #define __itt_frame_end_v3_ptr 0
2178 #define __itt_frame_submit_v3(domain,id,begin,end)
2179 #define __itt_frame_submit_v3_ptr 0
2180 #endif /* INTEL_NO_ITTNOTIFY_API */
2181 #else /* INTEL_NO_MACRO_BODY */
2182 #define __itt_frame_begin_v3_ptr 0
2183 #define __itt_frame_end_v3_ptr 0
2184 #define __itt_frame_submit_v3_ptr 0
2185 #endif /* INTEL_NO_MACRO_BODY */
2186 /** @endcond */
2187 /** @} frames group */
2188 /** @endcond */
2189
2190 /**
2191 * @defgroup taskgroup Task Group
2192 * @ingroup public
2193 * Task Group
2194 * @{
2195 */
2196 /**
2197 * @ingroup task_groups
2198 * @brief Denotes a task_group instance.
2199 * Successive calls to __itt_task_group with the same ID are ignored.
2200 * @param[in] domain The domain for this task_group instance
2201 * @param[in] id The instance ID for this task_group instance. Must not be __itt_null.
2202 * @param[in] parentid The instance ID for the parent of this task_group instance, or __itt_null.
2203 * @param[in] name The name of this task_group
2204 */
2205 void ITTAPI __itt_task_group(const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name);
2206
2207 /** @cond exclude_from_documentation */
2208 #ifndef INTEL_NO_MACRO_BODY
2209 #ifndef INTEL_NO_ITTNOTIFY_API
2210 ITT_STUBV(ITTAPI, void, task_group, (const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name))
2211 #define __itt_task_group(d,x,y,z) ITTNOTIFY_VOID_D3(task_group,d,x,y,z)
2212 #define __itt_task_group_ptr ITTNOTIFY_NAME(task_group)
2213 #else /* INTEL_NO_ITTNOTIFY_API */
2214 #define __itt_task_group(d,x,y,z)
2215 #define __itt_task_group_ptr 0
2216 #endif /* INTEL_NO_ITTNOTIFY_API */
2217 #else /* INTEL_NO_MACRO_BODY */
2218 #define __itt_task_group_ptr 0
2219 #endif /* INTEL_NO_MACRO_BODY */
2220 /** @endcond */
2221 /** @} taskgroup group */
2222
2223 /**
2224 * @defgroup tasks Tasks
2225 * @ingroup public
2226 * A task instance represents a piece of work performed by a particular
2227 * thread for a period of time. A call to __itt_task_begin creates a
2228 * task instance. This becomes the current instance for that task on that
2229 * thread. A following call to __itt_task_end on the same thread ends the
2230 * instance. There may be multiple simultaneous instances of tasks with the
2231 * same name on different threads. If an ID is specified, the task instance
2232 * receives that ID. Nested tasks are allowed.
2233 *
2234 * Note: The task is defined by the bracketing of __itt_task_begin and
2235 * __itt_task_end on the same thread. If some scheduling mechanism causes
2236 * task switching (the thread executes a different user task) or task
2237 * switching (the user task switches to a different thread) then this breaks
2238 * the notion of current instance. Additional API calls are required to
2239 * deal with that possibility.
2240 * @{
2241 */
2242
2243 /**
2244 * @ingroup tasks
2245 * @brief Begin a task instance.
2246 * @param[in] domain The domain for this task
2247 * @param[in] taskid The instance ID for this task instance, or __itt_null
2248 * @param[in] parentid The parent instance to which this task instance belongs, or __itt_null
2249 * @param[in] name The name of this task
2250 */
2251 void ITTAPI __itt_task_begin(const __itt_domain *domain, __itt_id taskid, __itt_id parentid, __itt_string_handle *name);
2252
2253 /**
2254 * @ingroup tasks
2255 * @brief Begin a task instance.
2256 * @param[in] domain The domain for this task
2257 * @param[in] taskid The identifier for this task instance (may be 0)
2258 * @param[in] parentid The parent of this task (may be 0)
2259 * @param[in] fn The pointer to the function you are tracing
2260 */
2261 void ITTAPI __itt_task_begin_fn(const __itt_domain *domain, __itt_id taskid, __itt_id parentid, void* fn);
2262
2263 /**
2264 * @ingroup tasks
2265 * @brief End the current task instance.
2266 * @param[in] domain The domain for this task
2267 */
2268 void ITTAPI __itt_task_end(const __itt_domain *domain);
2269
2270 /**
2271 * @ingroup tasks
2272 * @brief Begin an overlapped task instance.
2273 * @param[in] domain The domain for this task.
2274 * @param[in] taskid The identifier for this task instance, *cannot* be __itt_null.
2275 * @param[in] parentid The parent of this task, or __itt_null.
2276 * @param[in] name The name of this task.
2277 */
2278 void ITTAPI __itt_task_begin_overlapped(const __itt_domain* domain, __itt_id taskid, __itt_id parentid, __itt_string_handle* name);
2279
2280 /**
2281 * @ingroup tasks
2282 * @brief End an overlapped task instance.
2283 * @param[in] domain The domain for this task
2284 * @param[in] taskid Explicit ID of finished task
2285 */
2286 void ITTAPI __itt_task_end_overlapped(const __itt_domain *domain, __itt_id taskid);
2287
2288 /** @cond exclude_from_documentation */
2289 #ifndef INTEL_NO_MACRO_BODY
2290 #ifndef INTEL_NO_ITTNOTIFY_API
2291 ITT_STUBV(ITTAPI, void, task_begin, (const __itt_domain *domain, __itt_id id, __itt_id parentid, __itt_string_handle *name))
2292 ITT_STUBV(ITTAPI, void, task_begin_fn, (const __itt_domain *domain, __itt_id id, __itt_id parentid, void* fn))
2293 ITT_STUBV(ITTAPI, void, task_end, (const __itt_domain *domain))
2294 ITT_STUBV(ITTAPI, void, task_begin_overlapped, (const __itt_domain *domain, __itt_id taskid, __itt_id parentid, __itt_string_handle *name))
2295 ITT_STUBV(ITTAPI, void, task_end_overlapped, (const __itt_domain *domain, __itt_id taskid))
2296 #define __itt_task_begin(d,x,y,z) ITTNOTIFY_VOID_D3(task_begin,d,x,y,z)
2297 #define __itt_task_begin_ptr ITTNOTIFY_NAME(task_begin)
2298 #define __itt_task_begin_fn(d,x,y,z) ITTNOTIFY_VOID_D3(task_begin_fn,d,x,y,z)
2299 #define __itt_task_begin_fn_ptr ITTNOTIFY_NAME(task_begin_fn)
2300 #define __itt_task_end(d) ITTNOTIFY_VOID_D0(task_end,d)
2301 #define __itt_task_end_ptr ITTNOTIFY_NAME(task_end)
2302 #define __itt_task_begin_overlapped(d,x,y,z) ITTNOTIFY_VOID_D3(task_begin_overlapped,d,x,y,z)
2303 #define __itt_task_begin_overlapped_ptr ITTNOTIFY_NAME(task_begin_overlapped)
2304 #define __itt_task_end_overlapped(d,x) ITTNOTIFY_VOID_D1(task_end_overlapped,d,x)
2305 #define __itt_task_end_overlapped_ptr ITTNOTIFY_NAME(task_end_overlapped)
2306 #else /* INTEL_NO_ITTNOTIFY_API */
2307 #define __itt_task_begin(domain,id,parentid,name)
2308 #define __itt_task_begin_ptr 0
2309 #define __itt_task_begin_fn(domain,id,parentid,fn)
2310 #define __itt_task_begin_fn_ptr 0
2311 #define __itt_task_end(domain)
2312 #define __itt_task_end_ptr 0
2313 #define __itt_task_begin_overlapped(domain,taskid,parentid,name)
2314 #define __itt_task_begin_overlapped_ptr 0
2315 #define __itt_task_end_overlapped(domain,taskid)
2316 #define __itt_task_end_overlapped_ptr 0
2317 #endif /* INTEL_NO_ITTNOTIFY_API */
2318 #else /* INTEL_NO_MACRO_BODY */
2319 #define __itt_task_begin_ptr 0
2320 #define __itt_task_begin_fn_ptr 0
2321 #define __itt_task_end_ptr 0
2322 #define __itt_task_begin_overlapped_ptr 0
2323 #define __itt_task_end_overlapped_ptr 0
2324 #endif /* INTEL_NO_MACRO_BODY */
2325 /** @endcond */
2326 /** @} tasks group */
2327
2328
2329 /**
2330 * @defgroup markers Markers
2331 * Markers represent a single discreet event in time. Markers have a scope,
2332 * described by an enumerated type __itt_scope. Markers are created by
2333 * the API call __itt_marker. A marker instance can be given an ID for use in
2334 * adding metadata.
2335 * @{
2336 */
2337
2338 /**
2339 * @brief Describes the scope of an event object in the trace.
2340 */
2341 typedef enum
2342 {
2343 __itt_scope_unknown = 0,
2344 __itt_scope_global,
2345 __itt_scope_track_group,
2346 __itt_scope_track,
2347 __itt_scope_task,
2348 __itt_scope_marker
2349 } __itt_scope;
2350
2351 /** @cond exclude_from_documentation */
2352 #define __itt_marker_scope_unknown __itt_scope_unknown
2353 #define __itt_marker_scope_global __itt_scope_global
2354 #define __itt_marker_scope_process __itt_scope_track_group
2355 #define __itt_marker_scope_thread __itt_scope_track
2356 #define __itt_marker_scope_task __itt_scope_task
2357 /** @endcond */
2358
2359 /**
2360 * @ingroup markers
2361 * @brief Create a marker instance
2362 * @param[in] domain The domain for this marker
2363 * @param[in] id The instance ID for this marker or __itt_null
2364 * @param[in] name The name for this marker
2365 * @param[in] scope The scope for this marker
2366 */
2367 void ITTAPI __itt_marker(const __itt_domain *domain, __itt_id id, __itt_string_handle *name, __itt_scope scope);
2368
2369 /** @cond exclude_from_documentation */
2370 #ifndef INTEL_NO_MACRO_BODY
2371 #ifndef INTEL_NO_ITTNOTIFY_API
2372 ITT_STUBV(ITTAPI, void, marker, (const __itt_domain *domain, __itt_id id, __itt_string_handle *name, __itt_scope scope))
2373 #define __itt_marker(d,x,y,z) ITTNOTIFY_VOID_D3(marker,d,x,y,z)
2374 #define __itt_marker_ptr ITTNOTIFY_NAME(marker)
2375 #else /* INTEL_NO_ITTNOTIFY_API */
2376 #define __itt_marker(domain,id,name,scope)
2377 #define __itt_marker_ptr 0
2378 #endif /* INTEL_NO_ITTNOTIFY_API */
2379 #else /* INTEL_NO_MACRO_BODY */
2380 #define __itt_marker_ptr 0
2381 #endif /* INTEL_NO_MACRO_BODY */
2382 /** @endcond */
2383 /** @} markers group */
2384
2385 /**
2386 * @defgroup metadata Metadata
2387 * The metadata API is used to attach extra information to named
2388 * entities. Metadata can be attached to an identified named entity by ID,
2389 * or to the current entity (which is always a task).
2390 *
2391 * Conceptually metadata has a type (what kind of metadata), a key (the
2392 * name of the metadata), and a value (the actual data). The encoding of
2393 * the value depends on the type of the metadata.
2394 *
2395 * The type of metadata is specified by an enumerated type __itt_metdata_type.
2396 * @{
2397 */
2398
2399 /**
2400 * @ingroup parameters
2401 * @brief describes the type of metadata
2402 */
2403 typedef enum {
2404 __itt_metadata_unknown = 0,
2405 __itt_metadata_u64, /**< Unsigned 64-bit integer */
2406 __itt_metadata_s64, /**< Signed 64-bit integer */
2407 __itt_metadata_u32, /**< Unsigned 32-bit integer */
2408 __itt_metadata_s32, /**< Signed 32-bit integer */
2409 __itt_metadata_u16, /**< Unsigned 16-bit integer */
2410 __itt_metadata_s16, /**< Signed 16-bit integer */
2411 __itt_metadata_float, /**< Signed 32-bit floating-point */
2412 __itt_metadata_double /**< SIgned 64-bit floating-point */
2413 } __itt_metadata_type;
2414
2415 /**
2416 * @ingroup parameters
2417 * @brief Add metadata to an instance of a named entity.
2418 * @param[in] domain The domain controlling the call
2419 * @param[in] id The identifier of the instance to which the metadata is to be added, or __itt_null to add to the current task
2420 * @param[in] key The name of the metadata
2421 * @param[in] type The type of the metadata
2422 * @param[in] count The number of elements of the given type. If count == 0, no metadata will be added.
2423 * @param[in] data The metadata itself
2424 */
2425 void ITTAPI __itt_metadata_add(const __itt_domain *domain, __itt_id id, __itt_string_handle *key, __itt_metadata_type type, size_t count, void *data);
2426
2427 /** @cond exclude_from_documentation */
2428 #ifndef INTEL_NO_MACRO_BODY
2429 #ifndef INTEL_NO_ITTNOTIFY_API
2430 ITT_STUBV(ITTAPI, void, metadata_add, (const __itt_domain *domain, __itt_id id, __itt_string_handle *key, __itt_metadata_type type, size_t count, void *data))
2431 #define __itt_metadata_add(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(metadata_add,d,x,y,z,a,b)
2432 #define __itt_metadata_add_ptr ITTNOTIFY_NAME(metadata_add)
2433 #else /* INTEL_NO_ITTNOTIFY_API */
2434 #define __itt_metadata_add(d,x,y,z,a,b)
2435 #define __itt_metadata_add_ptr 0
2436 #endif /* INTEL_NO_ITTNOTIFY_API */
2437 #else /* INTEL_NO_MACRO_BODY */
2438 #define __itt_metadata_add_ptr 0
2439 #endif /* INTEL_NO_MACRO_BODY */
2440 /** @endcond */
2441
2442 /**
2443 * @ingroup parameters
2444 * @brief Add string metadata to an instance of a named entity.
2445 * @param[in] domain The domain controlling the call
2446 * @param[in] id The identifier of the instance to which the metadata is to be added, or __itt_null to add to the current task
2447 * @param[in] key The name of the metadata
2448 * @param[in] data The metadata itself
2449 * @param[in] length The number of characters in the string, or -1 if the length is unknown but the string is null-terminated
2450 */
2451 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2452 void ITTAPI __itt_metadata_str_addA(const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const char *data, size_t length);
2453 void ITTAPI __itt_metadata_str_addW(const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const wchar_t *data, size_t length);
2454 #if defined(UNICODE) || defined(_UNICODE)
2455 # define __itt_metadata_str_add __itt_metadata_str_addW
2456 # define __itt_metadata_str_add_ptr __itt_metadata_str_addW_ptr
2457 #else /* UNICODE */
2458 # define __itt_metadata_str_add __itt_metadata_str_addA
2459 # define __itt_metadata_str_add_ptr __itt_metadata_str_addA_ptr
2460 #endif /* UNICODE */
2461 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2462 void ITTAPI __itt_metadata_str_add(const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const char *data, size_t length);
2463 #endif
2464
2465 /** @cond exclude_from_documentation */
2466 #ifndef INTEL_NO_MACRO_BODY
2467 #ifndef INTEL_NO_ITTNOTIFY_API
2468 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2469 ITT_STUBV(ITTAPI, void, metadata_str_addA, (const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const char *data, size_t length))
2470 ITT_STUBV(ITTAPI, void, metadata_str_addW, (const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const wchar_t *data, size_t length))
2471 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2472 ITT_STUBV(ITTAPI, void, metadata_str_add, (const __itt_domain *domain, __itt_id id, __itt_string_handle *key, const char *data, size_t length))
2473 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2474 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2475 #define __itt_metadata_str_addA(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_addA,d,x,y,z,a)
2476 #define __itt_metadata_str_addA_ptr ITTNOTIFY_NAME(metadata_str_addA)
2477 #define __itt_metadata_str_addW(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_addW,d,x,y,z,a)
2478 #define __itt_metadata_str_addW_ptr ITTNOTIFY_NAME(metadata_str_addW)
2479 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2480 #define __itt_metadata_str_add(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_add,d,x,y,z,a)
2481 #define __itt_metadata_str_add_ptr ITTNOTIFY_NAME(metadata_str_add)
2482 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2483 #else /* INTEL_NO_ITTNOTIFY_API */
2484 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2485 #define __itt_metadata_str_addA(d,x,y,z,a)
2486 #define __itt_metadata_str_addA_ptr 0
2487 #define __itt_metadata_str_addW(d,x,y,z,a)
2488 #define __itt_metadata_str_addW_ptr 0
2489 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2490 #define __itt_metadata_str_add(d,x,y,z,a)
2491 #define __itt_metadata_str_add_ptr 0
2492 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2493 #endif /* INTEL_NO_ITTNOTIFY_API */
2494 #else /* INTEL_NO_MACRO_BODY */
2495 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2496 #define __itt_metadata_str_addA_ptr 0
2497 #define __itt_metadata_str_addW_ptr 0
2498 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2499 #define __itt_metadata_str_add_ptr 0
2500 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2501 #endif /* INTEL_NO_MACRO_BODY */
2502 /** @endcond */
2503
2504 /**
2505 * @ingroup parameters
2506 * @brief Add metadata to an instance of a named entity.
2507 * @param[in] domain The domain controlling the call
2508 * @param[in] scope The scope of the instance to which the metadata is to be added
2509
2510 * @param[in] id The identifier of the instance to which the metadata is to be added, or __itt_null to add to the current task
2511
2512 * @param[in] key The name of the metadata
2513 * @param[in] type The type of the metadata
2514 * @param[in] count The number of elements of the given type. If count == 0, no metadata will be added.
2515 * @param[in] data The metadata itself
2516 */
2517 void ITTAPI __itt_metadata_add_with_scope(const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, __itt_metadata_type type, size_t count, void *data);
2518
2519 /** @cond exclude_from_documentation */
2520 #ifndef INTEL_NO_MACRO_BODY
2521 #ifndef INTEL_NO_ITTNOTIFY_API
2522 ITT_STUBV(ITTAPI, void, metadata_add_with_scope, (const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, __itt_metadata_type type, size_t count, void *data))
2523 #define __itt_metadata_add_with_scope(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(metadata_add_with_scope,d,x,y,z,a,b)
2524 #define __itt_metadata_add_with_scope_ptr ITTNOTIFY_NAME(metadata_add_with_scope)
2525 #else /* INTEL_NO_ITTNOTIFY_API */
2526 #define __itt_metadata_add_with_scope(d,x,y,z,a,b)
2527 #define __itt_metadata_add_with_scope_ptr 0
2528 #endif /* INTEL_NO_ITTNOTIFY_API */
2529 #else /* INTEL_NO_MACRO_BODY */
2530 #define __itt_metadata_add_with_scope_ptr 0
2531 #endif /* INTEL_NO_MACRO_BODY */
2532 /** @endcond */
2533
2534 /**
2535 * @ingroup parameters
2536 * @brief Add string metadata to an instance of a named entity.
2537 * @param[in] domain The domain controlling the call
2538 * @param[in] scope The scope of the instance to which the metadata is to be added
2539
2540 * @param[in] id The identifier of the instance to which the metadata is to be added, or __itt_null to add to the current task
2541
2542 * @param[in] key The name of the metadata
2543 * @param[in] data The metadata itself
2544 * @param[in] length The number of characters in the string, or -1 if the length is unknown but the string is null-terminated
2545 */
2546 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2547 void ITTAPI __itt_metadata_str_add_with_scopeA(const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const char *data, size_t length);
2548 void ITTAPI __itt_metadata_str_add_with_scopeW(const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const wchar_t *data, size_t length);
2549 #if defined(UNICODE) || defined(_UNICODE)
2550 # define __itt_metadata_str_add_with_scope __itt_metadata_str_add_with_scopeW
2551 # define __itt_metadata_str_add_with_scope_ptr __itt_metadata_str_add_with_scopeW_ptr
2552 #else /* UNICODE */
2553 # define __itt_metadata_str_add_with_scope __itt_metadata_str_add_with_scopeA
2554 # define __itt_metadata_str_add_with_scope_ptr __itt_metadata_str_add_with_scopeA_ptr
2555 #endif /* UNICODE */
2556 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2557 void ITTAPI __itt_metadata_str_add_with_scope(const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const char *data, size_t length);
2558 #endif
2559
2560 /** @cond exclude_from_documentation */
2561 #ifndef INTEL_NO_MACRO_BODY
2562 #ifndef INTEL_NO_ITTNOTIFY_API
2563 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2564 ITT_STUBV(ITTAPI, void, metadata_str_add_with_scopeA, (const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const char *data, size_t length))
2565 ITT_STUBV(ITTAPI, void, metadata_str_add_with_scopeW, (const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const wchar_t *data, size_t length))
2566 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2567 ITT_STUBV(ITTAPI, void, metadata_str_add_with_scope, (const __itt_domain *domain, __itt_scope scope, __itt_string_handle *key, const char *data, size_t length))
2568 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2569 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2570 #define __itt_metadata_str_add_with_scopeA(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_add_with_scopeA,d,x,y,z,a)
2571 #define __itt_metadata_str_add_with_scopeA_ptr ITTNOTIFY_NAME(metadata_str_add_with_scopeA)
2572 #define __itt_metadata_str_add_with_scopeW(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_add_with_scopeW,d,x,y,z,a)
2573 #define __itt_metadata_str_add_with_scopeW_ptr ITTNOTIFY_NAME(metadata_str_add_with_scopeW)
2574 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2575 #define __itt_metadata_str_add_with_scope(d,x,y,z,a) ITTNOTIFY_VOID_D4(metadata_str_add_with_scope,d,x,y,z,a)
2576 #define __itt_metadata_str_add_with_scope_ptr ITTNOTIFY_NAME(metadata_str_add_with_scope)
2577 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2578 #else /* INTEL_NO_ITTNOTIFY_API */
2579 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2580 #define __itt_metadata_str_add_with_scopeA(d,x,y,z,a)
2581 #define __itt_metadata_str_add_with_scopeA_ptr 0
2582 #define __itt_metadata_str_add_with_scopeW(d,x,y,z,a)
2583 #define __itt_metadata_str_add_with_scopeW_ptr 0
2584 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2585 #define __itt_metadata_str_add_with_scope(d,x,y,z,a)
2586 #define __itt_metadata_str_add_with_scope_ptr 0
2587 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2588 #endif /* INTEL_NO_ITTNOTIFY_API */
2589 #else /* INTEL_NO_MACRO_BODY */
2590 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2591 #define __itt_metadata_str_add_with_scopeA_ptr 0
2592 #define __itt_metadata_str_add_with_scopeW_ptr 0
2593 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2594 #define __itt_metadata_str_add_with_scope_ptr 0
2595 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2596 #endif /* INTEL_NO_MACRO_BODY */
2597 /** @endcond */
2598
2599 /** @} metadata group */
2600
2601 /**
2602 * @defgroup relations Relations
2603 * Instances of named entities can be explicitly associated with other
2604 * instances using instance IDs and the relationship API calls.
2605 *
2606 * @{
2607 */
2608
2609 /**
2610 * @ingroup relations
2611 * @brief The kind of relation between two instances is specified by the enumerated type __itt_relation.
2612 * Relations between instances can be added with an API call. The relation
2613 * API uses instance IDs. Relations can be added before or after the actual
2614 * instances are created and persist independently of the instances. This
2615 * is the motivation for having different lifetimes for instance IDs and
2616 * the actual instances.
2617 */
2618 typedef enum
2619 {
2620 __itt_relation_is_unknown = 0,
2621 __itt_relation_is_dependent_on, /**< "A is dependent on B" means that A cannot start until B completes */
2622 __itt_relation_is_sibling_of, /**< "A is sibling of B" means that A and B were created as a group */
2623 __itt_relation_is_parent_of, /**< "A is parent of B" means that A created B */
2624 __itt_relation_is_continuation_of, /**< "A is continuation of B" means that A assumes the dependencies of B */
2625 __itt_relation_is_child_of, /**< "A is child of B" means that A was created by B (inverse of is_parent_of) */
2626 __itt_relation_is_continued_by, /**< "A is continued by B" means that B assumes the dependencies of A (inverse of is_continuation_of) */
2627 __itt_relation_is_predecessor_to /**< "A is predecessor to B" means that B cannot start until A completes (inverse of is_dependent_on) */
2628 } __itt_relation;
2629
2630 /**
2631 * @ingroup relations
2632 * @brief Add a relation to the current task instance.
2633 * The current task instance is the head of the relation.
2634 * @param[in] domain The domain controlling this call
2635 * @param[in] relation The kind of relation
2636 * @param[in] tail The ID for the tail of the relation
2637 */
2638 void ITTAPI __itt_relation_add_to_current(const __itt_domain *domain, __itt_relation relation, __itt_id tail);
2639
2640 /**
2641 * @ingroup relations
2642 * @brief Add a relation between two instance identifiers.
2643 * @param[in] domain The domain controlling this call
2644 * @param[in] head The ID for the head of the relation
2645 * @param[in] relation The kind of relation
2646 * @param[in] tail The ID for the tail of the relation
2647 */
2648 void ITTAPI __itt_relation_add(const __itt_domain *domain, __itt_id head, __itt_relation relation, __itt_id tail);
2649
2650 /** @cond exclude_from_documentation */
2651 #ifndef INTEL_NO_MACRO_BODY
2652 #ifndef INTEL_NO_ITTNOTIFY_API
2653 ITT_STUBV(ITTAPI, void, relation_add_to_current, (const __itt_domain *domain, __itt_relation relation, __itt_id tail))
2654 ITT_STUBV(ITTAPI, void, relation_add, (const __itt_domain *domain, __itt_id head, __itt_relation relation, __itt_id tail))
2655 #define __itt_relation_add_to_current(d,x,y) ITTNOTIFY_VOID_D2(relation_add_to_current,d,x,y)
2656 #define __itt_relation_add_to_current_ptr ITTNOTIFY_NAME(relation_add_to_current)
2657 #define __itt_relation_add(d,x,y,z) ITTNOTIFY_VOID_D3(relation_add,d,x,y,z)
2658 #define __itt_relation_add_ptr ITTNOTIFY_NAME(relation_add)
2659 #else /* INTEL_NO_ITTNOTIFY_API */
2660 #define __itt_relation_add_to_current(d,x,y)
2661 #define __itt_relation_add_to_current_ptr 0
2662 #define __itt_relation_add(d,x,y,z)
2663 #define __itt_relation_add_ptr 0
2664 #endif /* INTEL_NO_ITTNOTIFY_API */
2665 #else /* INTEL_NO_MACRO_BODY */
2666 #define __itt_relation_add_to_current_ptr 0
2667 #define __itt_relation_add_ptr 0
2668 #endif /* INTEL_NO_MACRO_BODY */
2669 /** @endcond */
2670 /** @} relations group */
2671
2672 /** @cond exclude_from_documentation */
2673 #pragma pack(push, 8)
2674
2675 typedef struct ___itt_clock_info
2676 {
2677 unsigned long long clock_freq; /*!< Clock domain frequency */
2678 unsigned long long clock_base; /*!< Clock domain base timestamp */
2679 } __itt_clock_info;
2680
2681 #pragma pack(pop)
2682 /** @endcond */
2683
2684 /** @cond exclude_from_documentation */
2685 typedef void (ITTAPI *__itt_get_clock_info_fn)(__itt_clock_info* clock_info, void* data);
2686 /** @endcond */
2687
2688 /** @cond exclude_from_documentation */
2689 #pragma pack(push, 8)
2690
2691 typedef struct ___itt_clock_domain
2692 {
2693 __itt_clock_info info; /*!< Most recent clock domain info */
2694 __itt_get_clock_info_fn fn; /*!< Callback function pointer */
2695 void* fn_data; /*!< Input argument for the callback function */
2696 int extra1; /*!< Reserved. Must be zero */
2697 void* extra2; /*!< Reserved. Must be zero */
2698 struct ___itt_clock_domain* next;
2699 } __itt_clock_domain;
2700
2701 #pragma pack(pop)
2702 /** @endcond */
2703
2704 /**
2705 * @ingroup clockdomains
2706 * @brief Create a clock domain.
2707 * Certain applications require the capability to trace their application using
2708 * a clock domain different than the CPU, for instance the instrumentation of events
2709 * that occur on a GPU.
2710 * Because the set of domains is expected to be static over the application's execution time,
2711 * there is no mechanism to destroy a domain.
2712 * Any domain can be accessed by any thread in the process, regardless of which thread created
2713 * the domain. This call is thread-safe.
2714 * @param[in] fn A pointer to a callback function which retrieves alternative CPU timestamps
2715 * @param[in] fn_data Argument for a callback function; may be NULL
2716 */
2717 __itt_clock_domain* ITTAPI __itt_clock_domain_create(__itt_get_clock_info_fn fn, void* fn_data);
2718
2719 /** @cond exclude_from_documentation */
2720 #ifndef INTEL_NO_MACRO_BODY
2721 #ifndef INTEL_NO_ITTNOTIFY_API
2722 ITT_STUB(ITTAPI, __itt_clock_domain*, clock_domain_create, (__itt_get_clock_info_fn fn, void* fn_data))
2723 #define __itt_clock_domain_create ITTNOTIFY_DATA(clock_domain_create)
2724 #define __itt_clock_domain_create_ptr ITTNOTIFY_NAME(clock_domain_create)
2725 #else /* INTEL_NO_ITTNOTIFY_API */
2726 #define __itt_clock_domain_create(fn,fn_data) (__itt_clock_domain*)0
2727 #define __itt_clock_domain_create_ptr 0
2728 #endif /* INTEL_NO_ITTNOTIFY_API */
2729 #else /* INTEL_NO_MACRO_BODY */
2730 #define __itt_clock_domain_create_ptr 0
2731 #endif /* INTEL_NO_MACRO_BODY */
2732 /** @endcond */
2733
2734 /**
2735 * @ingroup clockdomains
2736 * @brief Recalculate clock domains frequencies and clock base timestamps.
2737 */
2738 void ITTAPI __itt_clock_domain_reset(void);
2739
2740 /** @cond exclude_from_documentation */
2741 #ifndef INTEL_NO_MACRO_BODY
2742 #ifndef INTEL_NO_ITTNOTIFY_API
2743 ITT_STUBV(ITTAPI, void, clock_domain_reset, (void))
2744 #define __itt_clock_domain_reset ITTNOTIFY_VOID(clock_domain_reset)
2745 #define __itt_clock_domain_reset_ptr ITTNOTIFY_NAME(clock_domain_reset)
2746 #else /* INTEL_NO_ITTNOTIFY_API */
2747 #define __itt_clock_domain_reset()
2748 #define __itt_clock_domain_reset_ptr 0
2749 #endif /* INTEL_NO_ITTNOTIFY_API */
2750 #else /* INTEL_NO_MACRO_BODY */
2751 #define __itt_clock_domain_reset_ptr 0
2752 #endif /* INTEL_NO_MACRO_BODY */
2753 /** @endcond */
2754
2755 /**
2756 * @ingroup clockdomain
2757 * @brief Create an instance of identifier. This establishes the beginning of the lifetime of
2758 * an instance of the given ID in the trace. Once this lifetime starts, the ID can be used to
2759 * tag named entity instances in calls such as __itt_task_begin, and to specify relationships among
2760 * identified named entity instances, using the \ref relations APIs.
2761 * @param[in] domain The domain controlling the execution of this call.
2762 * @param[in] clock_domain The clock domain controlling the execution of this call.
2763 * @param[in] timestamp The user defined timestamp.
2764 * @param[in] id The ID to create.
2765 */
2766 void ITTAPI __itt_id_create_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id);
2767
2768 /**
2769 * @ingroup clockdomain
2770 * @brief Destroy an instance of identifier. This ends the lifetime of the current instance of the
2771 * given ID value in the trace. Any relationships that are established after this lifetime ends are
2772 * invalid. This call must be performed before the given ID value can be reused for a different
2773 * named entity instance.
2774 * @param[in] domain The domain controlling the execution of this call.
2775 * @param[in] clock_domain The clock domain controlling the execution of this call.
2776 * @param[in] timestamp The user defined timestamp.
2777 * @param[in] id The ID to destroy.
2778 */
2779 void ITTAPI __itt_id_destroy_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id);
2780
2781 /** @cond exclude_from_documentation */
2782 #ifndef INTEL_NO_MACRO_BODY
2783 #ifndef INTEL_NO_ITTNOTIFY_API
2784 ITT_STUBV(ITTAPI, void, id_create_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id))
2785 ITT_STUBV(ITTAPI, void, id_destroy_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id))
2786 #define __itt_id_create_ex(d,x,y,z) ITTNOTIFY_VOID_D3(id_create_ex,d,x,y,z)
2787 #define __itt_id_create_ex_ptr ITTNOTIFY_NAME(id_create_ex)
2788 #define __itt_id_destroy_ex(d,x,y,z) ITTNOTIFY_VOID_D3(id_destroy_ex,d,x,y,z)
2789 #define __itt_id_destroy_ex_ptr ITTNOTIFY_NAME(id_destroy_ex)
2790 #else /* INTEL_NO_ITTNOTIFY_API */
2791 #define __itt_id_create_ex(domain,clock_domain,timestamp,id)
2792 #define __itt_id_create_ex_ptr 0
2793 #define __itt_id_destroy_ex(domain,clock_domain,timestamp,id)
2794 #define __itt_id_destroy_ex_ptr 0
2795 #endif /* INTEL_NO_ITTNOTIFY_API */
2796 #else /* INTEL_NO_MACRO_BODY */
2797 #define __itt_id_create_ex_ptr 0
2798 #define __itt_id_destroy_ex_ptr 0
2799 #endif /* INTEL_NO_MACRO_BODY */
2800 /** @endcond */
2801
2802 /**
2803 * @ingroup clockdomain
2804 * @brief Begin a task instance.
2805 * @param[in] domain The domain for this task
2806 * @param[in] clock_domain The clock domain controlling the execution of this call.
2807 * @param[in] timestamp The user defined timestamp.
2808 * @param[in] taskid The instance ID for this task instance, or __itt_null
2809 * @param[in] parentid The parent instance to which this task instance belongs, or __itt_null
2810 * @param[in] name The name of this task
2811 */
2812 void ITTAPI __itt_task_begin_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name);
2813
2814 /**
2815 * @ingroup clockdomain
2816 * @brief Begin a task instance.
2817 * @param[in] domain The domain for this task
2818 * @param[in] clock_domain The clock domain controlling the execution of this call.
2819 * @param[in] timestamp The user defined timestamp.
2820 * @param[in] taskid The identifier for this task instance, or __itt_null
2821 * @param[in] parentid The parent of this task, or __itt_null
2822 * @param[in] fn The pointer to the function you are tracing
2823 */
2824 void ITTAPI __itt_task_begin_fn_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, void* fn);
2825
2826 /**
2827 * @ingroup clockdomain
2828 * @brief End the current task instance.
2829 * @param[in] domain The domain for this task
2830 * @param[in] clock_domain The clock domain controlling the execution of this call.
2831 * @param[in] timestamp The user defined timestamp.
2832 */
2833 void ITTAPI __itt_task_end_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp);
2834
2835 /** @cond exclude_from_documentation */
2836 #ifndef INTEL_NO_MACRO_BODY
2837 #ifndef INTEL_NO_ITTNOTIFY_API
2838 ITT_STUBV(ITTAPI, void, task_begin_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id, __itt_id parentid, __itt_string_handle *name))
2839 ITT_STUBV(ITTAPI, void, task_begin_fn_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id, __itt_id parentid, void* fn))
2840 ITT_STUBV(ITTAPI, void, task_end_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp))
2841 #define __itt_task_begin_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(task_begin_ex,d,x,y,z,a,b)
2842 #define __itt_task_begin_ex_ptr ITTNOTIFY_NAME(task_begin_ex)
2843 #define __itt_task_begin_fn_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(task_begin_fn_ex,d,x,y,z,a,b)
2844 #define __itt_task_begin_fn_ex_ptr ITTNOTIFY_NAME(task_begin_fn_ex)
2845 #define __itt_task_end_ex(d,x,y) ITTNOTIFY_VOID_D2(task_end_ex,d,x,y)
2846 #define __itt_task_end_ex_ptr ITTNOTIFY_NAME(task_end_ex)
2847 #else /* INTEL_NO_ITTNOTIFY_API */
2848 #define __itt_task_begin_ex(domain,clock_domain,timestamp,id,parentid,name)
2849 #define __itt_task_begin_ex_ptr 0
2850 #define __itt_task_begin_fn_ex(domain,clock_domain,timestamp,id,parentid,fn)
2851 #define __itt_task_begin_fn_ex_ptr 0
2852 #define __itt_task_end_ex(domain,clock_domain,timestamp)
2853 #define __itt_task_end_ex_ptr 0
2854 #endif /* INTEL_NO_ITTNOTIFY_API */
2855 #else /* INTEL_NO_MACRO_BODY */
2856 #define __itt_task_begin_ex_ptr 0
2857 #define __itt_task_begin_fn_ex_ptr 0
2858 #define __itt_task_end_ex_ptr 0
2859 #endif /* INTEL_NO_MACRO_BODY */
2860 /** @endcond */
2861
2862 /**
2863 * @defgroup counters Counters
2864 * @ingroup public
2865 * Counters are user-defined objects with a monotonically increasing
2866 * value. Counter values are 64-bit unsigned integers.
2867 * Counters have names that can be displayed in
2868 * the tools.
2869 * @{
2870 */
2871
2872 /**
2873 * @brief opaque structure for counter identification
2874 */
2875 /** @cond exclude_from_documentation */
2876
2877 typedef struct ___itt_counter* __itt_counter;
2878
2879 /**
2880 * @brief Create an unsigned 64 bits integer counter with given name/domain
2881 *
2882 * After __itt_counter_create() is called, __itt_counter_inc(id), __itt_counter_inc_delta(id, delta),
2883 * __itt_counter_set_value(id, value_ptr) or __itt_counter_set_value_ex(id, clock_domain, timestamp, value_ptr)
2884 * can be used to change the value of the counter, where value_ptr is a pointer to an unsigned 64 bits integer
2885 *
2886 * The call is equal to __itt_counter_create_typed(name, domain, __itt_metadata_u64)
2887 */
2888 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2889 __itt_counter ITTAPI __itt_counter_createA(const char *name, const char *domain);
2890 __itt_counter ITTAPI __itt_counter_createW(const wchar_t *name, const wchar_t *domain);
2891 #if defined(UNICODE) || defined(_UNICODE)
2892 # define __itt_counter_create __itt_counter_createW
2893 # define __itt_counter_create_ptr __itt_counter_createW_ptr
2894 #else /* UNICODE */
2895 # define __itt_counter_create __itt_counter_createA
2896 # define __itt_counter_create_ptr __itt_counter_createA_ptr
2897 #endif /* UNICODE */
2898 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2899 __itt_counter ITTAPI __itt_counter_create(const char *name, const char *domain);
2900 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2901
2902 #ifndef INTEL_NO_MACRO_BODY
2903 #ifndef INTEL_NO_ITTNOTIFY_API
2904 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2905 ITT_STUB(ITTAPI, __itt_counter, counter_createA, (const char *name, const char *domain))
2906 ITT_STUB(ITTAPI, __itt_counter, counter_createW, (const wchar_t *name, const wchar_t *domain))
2907 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2908 ITT_STUB(ITTAPI, __itt_counter, counter_create, (const char *name, const char *domain))
2909 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2910 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2911 #define __itt_counter_createA ITTNOTIFY_DATA(counter_createA)
2912 #define __itt_counter_createA_ptr ITTNOTIFY_NAME(counter_createA)
2913 #define __itt_counter_createW ITTNOTIFY_DATA(counter_createW)
2914 #define __itt_counter_createW_ptr ITTNOTIFY_NAME(counter_createW)
2915 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2916 #define __itt_counter_create ITTNOTIFY_DATA(counter_create)
2917 #define __itt_counter_create_ptr ITTNOTIFY_NAME(counter_create)
2918 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2919 #else /* INTEL_NO_ITTNOTIFY_API */
2920 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2921 #define __itt_counter_createA(name, domain)
2922 #define __itt_counter_createA_ptr 0
2923 #define __itt_counter_createW(name, domain)
2924 #define __itt_counter_createW_ptr 0
2925 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2926 #define __itt_counter_create(name, domain)
2927 #define __itt_counter_create_ptr 0
2928 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2929 #endif /* INTEL_NO_ITTNOTIFY_API */
2930 #else /* INTEL_NO_MACRO_BODY */
2931 #if ITT_PLATFORM==ITT_PLATFORM_WIN
2932 #define __itt_counter_createA_ptr 0
2933 #define __itt_counter_createW_ptr 0
2934 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2935 #define __itt_counter_create_ptr 0
2936 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
2937 #endif /* INTEL_NO_MACRO_BODY */
2938 /** @endcond */
2939
2940 /**
2941 * @brief Increment the unsigned 64 bits integer counter value
2942 *
2943 * Calling this function to non-unsigned 64 bits integer counters has no effect
2944 */
2945 void ITTAPI __itt_counter_inc(__itt_counter id);
2946
2947 #ifndef INTEL_NO_MACRO_BODY
2948 #ifndef INTEL_NO_ITTNOTIFY_API
2949 ITT_STUBV(ITTAPI, void, counter_inc, (__itt_counter id))
2950 #define __itt_counter_inc ITTNOTIFY_VOID(counter_inc)
2951 #define __itt_counter_inc_ptr ITTNOTIFY_NAME(counter_inc)
2952 #else /* INTEL_NO_ITTNOTIFY_API */
2953 #define __itt_counter_inc(id)
2954 #define __itt_counter_inc_ptr 0
2955 #endif /* INTEL_NO_ITTNOTIFY_API */
2956 #else /* INTEL_NO_MACRO_BODY */
2957 #define __itt_counter_inc_ptr 0
2958 #endif /* INTEL_NO_MACRO_BODY */
2959 /** @endcond */
2960 /**
2961 * @brief Increment the unsigned 64 bits integer counter value with x
2962 *
2963 * Calling this function to non-unsigned 64 bits integer counters has no effect
2964 */
2965 void ITTAPI __itt_counter_inc_delta(__itt_counter id, unsigned long long value);
2966
2967 #ifndef INTEL_NO_MACRO_BODY
2968 #ifndef INTEL_NO_ITTNOTIFY_API
2969 ITT_STUBV(ITTAPI, void, counter_inc_delta, (__itt_counter id, unsigned long long value))
2970 #define __itt_counter_inc_delta ITTNOTIFY_VOID(counter_inc_delta)
2971 #define __itt_counter_inc_delta_ptr ITTNOTIFY_NAME(counter_inc_delta)
2972 #else /* INTEL_NO_ITTNOTIFY_API */
2973 #define __itt_counter_inc_delta(id, value)
2974 #define __itt_counter_inc_delta_ptr 0
2975 #endif /* INTEL_NO_ITTNOTIFY_API */
2976 #else /* INTEL_NO_MACRO_BODY */
2977 #define __itt_counter_inc_delta_ptr 0
2978 #endif /* INTEL_NO_MACRO_BODY */
2979 /** @endcond */
2980
2981 /**
2982 * @brief Decrement the unsigned 64 bits integer counter value
2983 *
2984 * Calling this function to non-unsigned 64 bits integer counters has no effect
2985 */
2986 void ITTAPI __itt_counter_dec(__itt_counter id);
2987
2988 #ifndef INTEL_NO_MACRO_BODY
2989 #ifndef INTEL_NO_ITTNOTIFY_API
2990 ITT_STUBV(ITTAPI, void, counter_dec, (__itt_counter id))
2991 #define __itt_counter_dec ITTNOTIFY_VOID(counter_dec)
2992 #define __itt_counter_dec_ptr ITTNOTIFY_NAME(counter_dec)
2993 #else /* INTEL_NO_ITTNOTIFY_API */
2994 #define __itt_counter_dec(id)
2995 #define __itt_counter_dec_ptr 0
2996 #endif /* INTEL_NO_ITTNOTIFY_API */
2997 #else /* INTEL_NO_MACRO_BODY */
2998 #define __itt_counter_dec_ptr 0
2999 #endif /* INTEL_NO_MACRO_BODY */
3000 /** @endcond */
3001 /**
3002 * @brief Decrement the unsigned 64 bits integer counter value with x
3003 *
3004 * Calling this function to non-unsigned 64 bits integer counters has no effect
3005 */
3006 void ITTAPI __itt_counter_dec_delta(__itt_counter id, unsigned long long value);
3007
3008 #ifndef INTEL_NO_MACRO_BODY
3009 #ifndef INTEL_NO_ITTNOTIFY_API
3010 ITT_STUBV(ITTAPI, void, counter_dec_delta, (__itt_counter id, unsigned long long value))
3011 #define __itt_counter_dec_delta ITTNOTIFY_VOID(counter_dec_delta)
3012 #define __itt_counter_dec_delta_ptr ITTNOTIFY_NAME(counter_dec_delta)
3013 #else /* INTEL_NO_ITTNOTIFY_API */
3014 #define __itt_counter_dec_delta(id, value)
3015 #define __itt_counter_dec_delta_ptr 0
3016 #endif /* INTEL_NO_ITTNOTIFY_API */
3017 #else /* INTEL_NO_MACRO_BODY */
3018 #define __itt_counter_dec_delta_ptr 0
3019 #endif /* INTEL_NO_MACRO_BODY */
3020 /** @endcond */
3021
3022 /**
3023 * @ingroup counters
3024 * @brief Increment a counter by one.
3025 * The first call with a given name creates a counter by that name and sets its
3026 * value to zero. Successive calls increment the counter value.
3027 * @param[in] domain The domain controlling the call. Counter names are not domain specific.
3028 * The domain argument is used only to enable or disable the API calls.
3029 * @param[in] name The name of the counter
3030 */
3031 void ITTAPI __itt_counter_inc_v3(const __itt_domain *domain, __itt_string_handle *name);
3032
3033 /**
3034 * @ingroup counters
3035 * @brief Increment a counter by the value specified in delta.
3036 * @param[in] domain The domain controlling the call. Counter names are not domain specific.
3037 * The domain argument is used only to enable or disable the API calls.
3038 * @param[in] name The name of the counter
3039 * @param[in] delta The amount by which to increment the counter
3040 */
3041 void ITTAPI __itt_counter_inc_delta_v3(const __itt_domain *domain, __itt_string_handle *name, unsigned long long delta);
3042
3043 #ifndef INTEL_NO_MACRO_BODY
3044 #ifndef INTEL_NO_ITTNOTIFY_API
3045 ITT_STUBV(ITTAPI, void, counter_inc_v3, (const __itt_domain *domain, __itt_string_handle *name))
3046 ITT_STUBV(ITTAPI, void, counter_inc_delta_v3, (const __itt_domain *domain, __itt_string_handle *name, unsigned long long delta))
3047 #define __itt_counter_inc_v3(d,x) ITTNOTIFY_VOID_D1(counter_inc_v3,d,x)
3048 #define __itt_counter_inc_v3_ptr ITTNOTIFY_NAME(counter_inc_v3)
3049 #define __itt_counter_inc_delta_v3(d,x,y) ITTNOTIFY_VOID_D2(counter_inc_delta_v3,d,x,y)
3050 #define __itt_counter_inc_delta_v3_ptr ITTNOTIFY_NAME(counter_inc_delta_v3)
3051 #else /* INTEL_NO_ITTNOTIFY_API */
3052 #define __itt_counter_inc_v3(domain,name)
3053 #define __itt_counter_inc_v3_ptr 0
3054 #define __itt_counter_inc_delta_v3(domain,name,delta)
3055 #define __itt_counter_inc_delta_v3_ptr 0
3056 #endif /* INTEL_NO_ITTNOTIFY_API */
3057 #else /* INTEL_NO_MACRO_BODY */
3058 #define __itt_counter_inc_v3_ptr 0
3059 #define __itt_counter_inc_delta_v3_ptr 0
3060 #endif /* INTEL_NO_MACRO_BODY */
3061 /** @endcond */
3062
3063
3064 /**
3065 * @ingroup counters
3066 * @brief Decrement a counter by one.
3067 * The first call with a given name creates a counter by that name and sets its
3068 * value to zero. Successive calls decrement the counter value.
3069 * @param[in] domain The domain controlling the call. Counter names are not domain specific.
3070 * The domain argument is used only to enable or disable the API calls.
3071 * @param[in] name The name of the counter
3072 */
3073 void ITTAPI __itt_counter_dec_v3(const __itt_domain *domain, __itt_string_handle *name);
3074
3075 /**
3076 * @ingroup counters
3077 * @brief Decrement a counter by the value specified in delta.
3078 * @param[in] domain The domain controlling the call. Counter names are not domain specific.
3079 * The domain argument is used only to enable or disable the API calls.
3080 * @param[in] name The name of the counter
3081 * @param[in] delta The amount by which to decrement the counter
3082 */
3083 void ITTAPI __itt_counter_dec_delta_v3(const __itt_domain *domain, __itt_string_handle *name, unsigned long long delta);
3084
3085 #ifndef INTEL_NO_MACRO_BODY
3086 #ifndef INTEL_NO_ITTNOTIFY_API
3087 ITT_STUBV(ITTAPI, void, counter_dec_v3, (const __itt_domain *domain, __itt_string_handle *name))
3088 ITT_STUBV(ITTAPI, void, counter_dec_delta_v3, (const __itt_domain *domain, __itt_string_handle *name, unsigned long long delta))
3089 #define __itt_counter_dec_v3(d,x) ITTNOTIFY_VOID_D1(counter_dec_v3,d,x)
3090 #define __itt_counter_dec_v3_ptr ITTNOTIFY_NAME(counter_dec_v3)
3091 #define __itt_counter_dec_delta_v3(d,x,y) ITTNOTIFY_VOID_D2(counter_dec_delta_v3,d,x,y)
3092 #define __itt_counter_dec_delta_v3_ptr ITTNOTIFY_NAME(counter_dec_delta_v3)
3093 #else /* INTEL_NO_ITTNOTIFY_API */
3094 #define __itt_counter_dec_v3(domain,name)
3095 #define __itt_counter_dec_v3_ptr 0
3096 #define __itt_counter_dec_delta_v3(domain,name,delta)
3097 #define __itt_counter_dec_delta_v3_ptr 0
3098 #endif /* INTEL_NO_ITTNOTIFY_API */
3099 #else /* INTEL_NO_MACRO_BODY */
3100 #define __itt_counter_dec_v3_ptr 0
3101 #define __itt_counter_dec_delta_v3_ptr 0
3102 #endif /* INTEL_NO_MACRO_BODY */
3103 /** @endcond */
3104
3105 /** @} counters group */
3106
3107
3108 /**
3109 * @brief Set the counter value
3110 */
3111 void ITTAPI __itt_counter_set_value(__itt_counter id, void *value_ptr);
3112
3113 #ifndef INTEL_NO_MACRO_BODY
3114 #ifndef INTEL_NO_ITTNOTIFY_API
3115 ITT_STUBV(ITTAPI, void, counter_set_value, (__itt_counter id, void *value_ptr))
3116 #define __itt_counter_set_value ITTNOTIFY_VOID(counter_set_value)
3117 #define __itt_counter_set_value_ptr ITTNOTIFY_NAME(counter_set_value)
3118 #else /* INTEL_NO_ITTNOTIFY_API */
3119 #define __itt_counter_set_value(id, value_ptr)
3120 #define __itt_counter_set_value_ptr 0
3121 #endif /* INTEL_NO_ITTNOTIFY_API */
3122 #else /* INTEL_NO_MACRO_BODY */
3123 #define __itt_counter_set_value_ptr 0
3124 #endif /* INTEL_NO_MACRO_BODY */
3125 /** @endcond */
3126
3127 /**
3128 * @brief Set the counter value
3129 */
3130 void ITTAPI __itt_counter_set_value_ex(__itt_counter id, __itt_clock_domain *clock_domain, unsigned long long timestamp, void *value_ptr);
3131
3132 /** @cond exclude_from_documentation */
3133 #ifndef INTEL_NO_MACRO_BODY
3134 #ifndef INTEL_NO_ITTNOTIFY_API
3135 ITT_STUBV(ITTAPI, void, counter_set_value_ex, (__itt_counter id, __itt_clock_domain *clock_domain, unsigned long long timestamp, void *value_ptr))
3136 #define __itt_counter_set_value_ex ITTNOTIFY_VOID(counter_set_value_ex)
3137 #define __itt_counter_set_value_ex_ptr ITTNOTIFY_NAME(counter_set_value_ex)
3138 #else /* INTEL_NO_ITTNOTIFY_API */
3139 #define __itt_counter_set_value_ex(id, clock_domain, timestamp, value_ptr)
3140 #define __itt_counter_set_value_ex_ptr 0
3141 #endif /* INTEL_NO_ITTNOTIFY_API */
3142 #else /* INTEL_NO_MACRO_BODY */
3143 #define __itt_counter_set_value_ex_ptr 0
3144 #endif /* INTEL_NO_MACRO_BODY */
3145 /** @endcond */
3146
3147 /**
3148 * @brief Create a typed counter with given name/domain
3149 *
3150 * After __itt_counter_create_typed() is called, __itt_counter_inc(id), __itt_counter_inc_delta(id, delta),
3151 * __itt_counter_set_value(id, value_ptr) or __itt_counter_set_value_ex(id, clock_domain, timestamp, value_ptr)
3152 * can be used to change the value of the counter
3153 */
3154 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3155 __itt_counter ITTAPI __itt_counter_create_typedA(const char *name, const char *domain, __itt_metadata_type type);
3156 __itt_counter ITTAPI __itt_counter_create_typedW(const wchar_t *name, const wchar_t *domain, __itt_metadata_type type);
3157 #if defined(UNICODE) || defined(_UNICODE)
3158 # define __itt_counter_create_typed __itt_counter_create_typedW
3159 # define __itt_counter_create_typed_ptr __itt_counter_create_typedW_ptr
3160 #else /* UNICODE */
3161 # define __itt_counter_create_typed __itt_counter_create_typedA
3162 # define __itt_counter_create_typed_ptr __itt_counter_create_typedA_ptr
3163 #endif /* UNICODE */
3164 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3165 __itt_counter ITTAPI __itt_counter_create_typed(const char *name, const char *domain, __itt_metadata_type type);
3166 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3167
3168 #ifndef INTEL_NO_MACRO_BODY
3169 #ifndef INTEL_NO_ITTNOTIFY_API
3170 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3171 ITT_STUB(ITTAPI, __itt_counter, counter_create_typedA, (const char *name, const char *domain, __itt_metadata_type type))
3172 ITT_STUB(ITTAPI, __itt_counter, counter_create_typedW, (const wchar_t *name, const wchar_t *domain, __itt_metadata_type type))
3173 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3174 ITT_STUB(ITTAPI, __itt_counter, counter_create_typed, (const char *name, const char *domain, __itt_metadata_type type))
3175 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3176 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3177 #define __itt_counter_create_typedA ITTNOTIFY_DATA(counter_create_typedA)
3178 #define __itt_counter_create_typedA_ptr ITTNOTIFY_NAME(counter_create_typedA)
3179 #define __itt_counter_create_typedW ITTNOTIFY_DATA(counter_create_typedW)
3180 #define __itt_counter_create_typedW_ptr ITTNOTIFY_NAME(counter_create_typedW)
3181 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3182 #define __itt_counter_create_typed ITTNOTIFY_DATA(counter_create_typed)
3183 #define __itt_counter_create_typed_ptr ITTNOTIFY_NAME(counter_create_typed)
3184 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3185 #else /* INTEL_NO_ITTNOTIFY_API */
3186 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3187 #define __itt_counter_create_typedA(name, domain, type)
3188 #define __itt_counter_create_typedA_ptr 0
3189 #define __itt_counter_create_typedW(name, domain, type)
3190 #define __itt_counter_create_typedW_ptr 0
3191 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3192 #define __itt_counter_create_typed(name, domain, type)
3193 #define __itt_counter_create_typed_ptr 0
3194 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3195 #endif /* INTEL_NO_ITTNOTIFY_API */
3196 #else /* INTEL_NO_MACRO_BODY */
3197 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3198 #define __itt_counter_create_typedA_ptr 0
3199 #define __itt_counter_create_typedW_ptr 0
3200 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3201 #define __itt_counter_create_typed_ptr 0
3202 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3203 #endif /* INTEL_NO_MACRO_BODY */
3204 /** @endcond */
3205
3206 /**
3207 * @brief Destroy the counter identified by the pointer previously returned by __itt_counter_create() or
3208 * __itt_counter_create_typed()
3209 */
3210 void ITTAPI __itt_counter_destroy(__itt_counter id);
3211
3212 #ifndef INTEL_NO_MACRO_BODY
3213 #ifndef INTEL_NO_ITTNOTIFY_API
3214 ITT_STUBV(ITTAPI, void, counter_destroy, (__itt_counter id))
3215 #define __itt_counter_destroy ITTNOTIFY_VOID(counter_destroy)
3216 #define __itt_counter_destroy_ptr ITTNOTIFY_NAME(counter_destroy)
3217 #else /* INTEL_NO_ITTNOTIFY_API */
3218 #define __itt_counter_destroy(id)
3219 #define __itt_counter_destroy_ptr 0
3220 #endif /* INTEL_NO_ITTNOTIFY_API */
3221 #else /* INTEL_NO_MACRO_BODY */
3222 #define __itt_counter_destroy_ptr 0
3223 #endif /* INTEL_NO_MACRO_BODY */
3224 /** @endcond */
3225 /** @} counters group */
3226
3227 /**
3228 * @ingroup markers
3229 * @brief Create a marker instance.
3230 * @param[in] domain The domain for this marker
3231 * @param[in] clock_domain The clock domain controlling the execution of this call.
3232 * @param[in] timestamp The user defined timestamp.
3233 * @param[in] id The instance ID for this marker, or __itt_null
3234 * @param[in] name The name for this marker
3235 * @param[in] scope The scope for this marker
3236 */
3237 void ITTAPI __itt_marker_ex(const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id, __itt_string_handle *name, __itt_scope scope);
3238
3239 /** @cond exclude_from_documentation */
3240 #ifndef INTEL_NO_MACRO_BODY
3241 #ifndef INTEL_NO_ITTNOTIFY_API
3242 ITT_STUBV(ITTAPI, void, marker_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id id, __itt_string_handle *name, __itt_scope scope))
3243 #define __itt_marker_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(marker_ex,d,x,y,z,a,b)
3244 #define __itt_marker_ex_ptr ITTNOTIFY_NAME(marker_ex)
3245 #else /* INTEL_NO_ITTNOTIFY_API */
3246 #define __itt_marker_ex(domain,clock_domain,timestamp,id,name,scope)
3247 #define __itt_marker_ex_ptr 0
3248 #endif /* INTEL_NO_ITTNOTIFY_API */
3249 #else /* INTEL_NO_MACRO_BODY */
3250 #define __itt_marker_ex_ptr 0
3251 #endif /* INTEL_NO_MACRO_BODY */
3252 /** @endcond */
3253
3254 /**
3255 * @ingroup clockdomain
3256 * @brief Add a relation to the current task instance.
3257 * The current task instance is the head of the relation.
3258 * @param[in] domain The domain controlling this call
3259 * @param[in] clock_domain The clock domain controlling the execution of this call.
3260 * @param[in] timestamp The user defined timestamp.
3261 * @param[in] relation The kind of relation
3262 * @param[in] tail The ID for the tail of the relation
3263 */
3264 void ITTAPI __itt_relation_add_to_current_ex(const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_relation relation, __itt_id tail);
3265
3266 /**
3267 * @ingroup clockdomain
3268 * @brief Add a relation between two instance identifiers.
3269 * @param[in] domain The domain controlling this call
3270 * @param[in] clock_domain The clock domain controlling the execution of this call.
3271 * @param[in] timestamp The user defined timestamp.
3272 * @param[in] head The ID for the head of the relation
3273 * @param[in] relation The kind of relation
3274 * @param[in] tail The ID for the tail of the relation
3275 */
3276 void ITTAPI __itt_relation_add_ex(const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id head, __itt_relation relation, __itt_id tail);
3277
3278 /** @cond exclude_from_documentation */
3279 #ifndef INTEL_NO_MACRO_BODY
3280 #ifndef INTEL_NO_ITTNOTIFY_API
3281 ITT_STUBV(ITTAPI, void, relation_add_to_current_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_relation relation, __itt_id tail))
3282 ITT_STUBV(ITTAPI, void, relation_add_ex, (const __itt_domain *domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id head, __itt_relation relation, __itt_id tail))
3283 #define __itt_relation_add_to_current_ex(d,x,y,z,a) ITTNOTIFY_VOID_D4(relation_add_to_current_ex,d,x,y,z,a)
3284 #define __itt_relation_add_to_current_ex_ptr ITTNOTIFY_NAME(relation_add_to_current_ex)
3285 #define __itt_relation_add_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(relation_add_ex,d,x,y,z,a,b)
3286 #define __itt_relation_add_ex_ptr ITTNOTIFY_NAME(relation_add_ex)
3287 #else /* INTEL_NO_ITTNOTIFY_API */
3288 #define __itt_relation_add_to_current_ex(domain,clock_domain,timestame,relation,tail)
3289 #define __itt_relation_add_to_current_ex_ptr 0
3290 #define __itt_relation_add_ex(domain,clock_domain,timestamp,head,relation,tail)
3291 #define __itt_relation_add_ex_ptr 0
3292 #endif /* INTEL_NO_ITTNOTIFY_API */
3293 #else /* INTEL_NO_MACRO_BODY */
3294 #define __itt_relation_add_to_current_ex_ptr 0
3295 #define __itt_relation_add_ex_ptr 0
3296 #endif /* INTEL_NO_MACRO_BODY */
3297 /** @endcond */
3298
3299 /** @cond exclude_from_documentation */
3300 typedef enum ___itt_track_group_type
3301 {
3302 __itt_track_group_type_normal = 0
3303 } __itt_track_group_type;
3304 /** @endcond */
3305
3306 /** @cond exclude_from_documentation */
3307 #pragma pack(push, 8)
3308
3309 typedef struct ___itt_track_group
3310 {
3311 __itt_string_handle* name; /*!< Name of the track group */
3312 struct ___itt_track* track; /*!< List of child tracks */
3313 __itt_track_group_type tgtype; /*!< Type of the track group */
3314 int extra1; /*!< Reserved. Must be zero */
3315 void* extra2; /*!< Reserved. Must be zero */
3316 struct ___itt_track_group* next;
3317 } __itt_track_group;
3318
3319 #pragma pack(pop)
3320 /** @endcond */
3321
3322 /**
3323 * @brief Placeholder for custom track types. Currently, "normal" custom track
3324 * is the only available track type.
3325 */
3326 typedef enum ___itt_track_type
3327 {
3328 __itt_track_type_normal = 0
3329 #ifdef INTEL_ITTNOTIFY_API_PRIVATE
3330 , __itt_track_type_queue
3331 #endif /* INTEL_ITTNOTIFY_API_PRIVATE */
3332 } __itt_track_type;
3333
3334 /** @cond exclude_from_documentation */
3335 #pragma pack(push, 8)
3336
3337 typedef struct ___itt_track
3338 {
3339 __itt_string_handle* name; /*!< Name of the track group */
3340 __itt_track_group* group; /*!< Parent group to a track */
3341 __itt_track_type ttype; /*!< Type of the track */
3342 int extra1; /*!< Reserved. Must be zero */
3343 void* extra2; /*!< Reserved. Must be zero */
3344 struct ___itt_track* next;
3345 } __itt_track;
3346
3347 #pragma pack(pop)
3348 /** @endcond */
3349
3350 /**
3351 * @brief Create logical track group.
3352 */
3353 __itt_track_group* ITTAPI __itt_track_group_create(__itt_string_handle* name, __itt_track_group_type track_group_type);
3354
3355 /** @cond exclude_from_documentation */
3356 #ifndef INTEL_NO_MACRO_BODY
3357 #ifndef INTEL_NO_ITTNOTIFY_API
3358 ITT_STUB(ITTAPI, __itt_track_group*, track_group_create, (__itt_string_handle* name, __itt_track_group_type track_group_type))
3359 #define __itt_track_group_create ITTNOTIFY_DATA(track_group_create)
3360 #define __itt_track_group_create_ptr ITTNOTIFY_NAME(track_group_create)
3361 #else /* INTEL_NO_ITTNOTIFY_API */
3362 #define __itt_track_group_create(name) (__itt_track_group*)0
3363 #define __itt_track_group_create_ptr 0
3364 #endif /* INTEL_NO_ITTNOTIFY_API */
3365 #else /* INTEL_NO_MACRO_BODY */
3366 #define __itt_track_group_create_ptr 0
3367 #endif /* INTEL_NO_MACRO_BODY */
3368 /** @endcond */
3369
3370 /**
3371 * @brief Create logical track.
3372 */
3373 __itt_track* ITTAPI __itt_track_create(__itt_track_group* track_group, __itt_string_handle* name, __itt_track_type track_type);
3374
3375 /** @cond exclude_from_documentation */
3376 #ifndef INTEL_NO_MACRO_BODY
3377 #ifndef INTEL_NO_ITTNOTIFY_API
3378 ITT_STUB(ITTAPI, __itt_track*, track_create, (__itt_track_group* track_group,__itt_string_handle* name, __itt_track_type track_type))
3379 #define __itt_track_create ITTNOTIFY_DATA(track_create)
3380 #define __itt_track_create_ptr ITTNOTIFY_NAME(track_create)
3381 #else /* INTEL_NO_ITTNOTIFY_API */
3382 #define __itt_track_create(track_group,name,track_type) (__itt_track*)0
3383 #define __itt_track_create_ptr 0
3384 #endif /* INTEL_NO_ITTNOTIFY_API */
3385 #else /* INTEL_NO_MACRO_BODY */
3386 #define __itt_track_create_ptr 0
3387 #endif /* INTEL_NO_MACRO_BODY */
3388 /** @endcond */
3389
3390 /**
3391 * @brief Set the logical track.
3392 */
3393 void ITTAPI __itt_set_track(__itt_track* track);
3394
3395 /** @cond exclude_from_documentation */
3396 #ifndef INTEL_NO_MACRO_BODY
3397 #ifndef INTEL_NO_ITTNOTIFY_API
3398 ITT_STUBV(ITTAPI, void, set_track, (__itt_track *track))
3399 #define __itt_set_track ITTNOTIFY_VOID(set_track)
3400 #define __itt_set_track_ptr ITTNOTIFY_NAME(set_track)
3401 #else /* INTEL_NO_ITTNOTIFY_API */
3402 #define __itt_set_track(track)
3403 #define __itt_set_track_ptr 0
3404 #endif /* INTEL_NO_ITTNOTIFY_API */
3405 #else /* INTEL_NO_MACRO_BODY */
3406 #define __itt_set_track_ptr 0
3407 #endif /* INTEL_NO_MACRO_BODY */
3408 /** @endcond */
3409
3410 /* ========================================================================== */
3411 /** @cond exclude_from_gpa_documentation */
3412 /**
3413 * @defgroup events Events
3414 * @ingroup public
3415 * Events group
3416 * @{
3417 */
3418 /** @brief user event type */
3419 typedef int __itt_event;
3420
3421 /**
3422 * @brief Create an event notification
3423 * @note name or namelen being null/name and namelen not matching, user event feature not enabled
3424 * @return non-zero event identifier upon success and __itt_err otherwise
3425 */
3426 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3427 __itt_event LIBITTAPI __itt_event_createA(const char *name, int namelen);
3428 __itt_event LIBITTAPI __itt_event_createW(const wchar_t *name, int namelen);
3429 #if defined(UNICODE) || defined(_UNICODE)
3430 # define __itt_event_create __itt_event_createW
3431 # define __itt_event_create_ptr __itt_event_createW_ptr
3432 #else
3433 # define __itt_event_create __itt_event_createA
3434 # define __itt_event_create_ptr __itt_event_createA_ptr
3435 #endif /* UNICODE */
3436 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3437 __itt_event LIBITTAPI __itt_event_create(const char *name, int namelen);
3438 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3439
3440 /** @cond exclude_from_documentation */
3441 #ifndef INTEL_NO_MACRO_BODY
3442 #ifndef INTEL_NO_ITTNOTIFY_API
3443 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3444 ITT_STUB(LIBITTAPI, __itt_event, event_createA, (const char *name, int namelen))
3445 ITT_STUB(LIBITTAPI, __itt_event, event_createW, (const wchar_t *name, int namelen))
3446 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3447 ITT_STUB(LIBITTAPI, __itt_event, event_create, (const char *name, int namelen))
3448 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3449 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3450 #define __itt_event_createA ITTNOTIFY_DATA(event_createA)
3451 #define __itt_event_createA_ptr ITTNOTIFY_NAME(event_createA)
3452 #define __itt_event_createW ITTNOTIFY_DATA(event_createW)
3453 #define __itt_event_createW_ptr ITTNOTIFY_NAME(event_createW)
3454 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3455 #define __itt_event_create ITTNOTIFY_DATA(event_create)
3456 #define __itt_event_create_ptr ITTNOTIFY_NAME(event_create)
3457 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3458 #else /* INTEL_NO_ITTNOTIFY_API */
3459 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3460 #define __itt_event_createA(name, namelen) (__itt_event)0
3461 #define __itt_event_createA_ptr 0
3462 #define __itt_event_createW(name, namelen) (__itt_event)0
3463 #define __itt_event_createW_ptr 0
3464 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3465 #define __itt_event_create(name, namelen) (__itt_event)0
3466 #define __itt_event_create_ptr 0
3467 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3468 #endif /* INTEL_NO_ITTNOTIFY_API */
3469 #else /* INTEL_NO_MACRO_BODY */
3470 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3471 #define __itt_event_createA_ptr 0
3472 #define __itt_event_createW_ptr 0
3473 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3474 #define __itt_event_create_ptr 0
3475 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3476 #endif /* INTEL_NO_MACRO_BODY */
3477 /** @endcond */
3478
3479 /**
3480 * @brief Record an event occurrence.
3481 * @return __itt_err upon failure (invalid event id/user event feature not enabled)
3482 */
3483 int LIBITTAPI __itt_event_start(__itt_event event);
3484
3485 /** @cond exclude_from_documentation */
3486 #ifndef INTEL_NO_MACRO_BODY
3487 #ifndef INTEL_NO_ITTNOTIFY_API
3488 ITT_STUB(LIBITTAPI, int, event_start, (__itt_event event))
3489 #define __itt_event_start ITTNOTIFY_DATA(event_start)
3490 #define __itt_event_start_ptr ITTNOTIFY_NAME(event_start)
3491 #else /* INTEL_NO_ITTNOTIFY_API */
3492 #define __itt_event_start(event) (int)0
3493 #define __itt_event_start_ptr 0
3494 #endif /* INTEL_NO_ITTNOTIFY_API */
3495 #else /* INTEL_NO_MACRO_BODY */
3496 #define __itt_event_start_ptr 0
3497 #endif /* INTEL_NO_MACRO_BODY */
3498 /** @endcond */
3499
3500 /**
3501 * @brief Record an event end occurrence.
3502 * @note It is optional if events do not have durations.
3503 * @return __itt_err upon failure (invalid event id/user event feature not enabled)
3504 */
3505 int LIBITTAPI __itt_event_end(__itt_event event);
3506
3507 /** @cond exclude_from_documentation */
3508 #ifndef INTEL_NO_MACRO_BODY
3509 #ifndef INTEL_NO_ITTNOTIFY_API
3510 ITT_STUB(LIBITTAPI, int, event_end, (__itt_event event))
3511 #define __itt_event_end ITTNOTIFY_DATA(event_end)
3512 #define __itt_event_end_ptr ITTNOTIFY_NAME(event_end)
3513 #else /* INTEL_NO_ITTNOTIFY_API */
3514 #define __itt_event_end(event) (int)0
3515 #define __itt_event_end_ptr 0
3516 #endif /* INTEL_NO_ITTNOTIFY_API */
3517 #else /* INTEL_NO_MACRO_BODY */
3518 #define __itt_event_end_ptr 0
3519 #endif /* INTEL_NO_MACRO_BODY */
3520 /** @endcond */
3521 /** @} events group */
3522
3523
3524 /**
3525 * @defgroup arrays Arrays Visualizer
3526 * @ingroup public
3527 * Visualize arrays
3528 * @{
3529 */
3530
3531 /**
3532 * @enum __itt_av_data_type
3533 * @brief Defines types of arrays data (for C/C++ intrinsic types)
3534 */
3535 typedef enum
3536 {
3537 __itt_e_first = 0,
3538 __itt_e_char = 0, /* 1-byte integer */
3539 __itt_e_uchar, /* 1-byte unsigned integer */
3540 __itt_e_int16, /* 2-byte integer */
3541 __itt_e_uint16, /* 2-byte unsigned integer */
3542 __itt_e_int32, /* 4-byte integer */
3543 __itt_e_uint32, /* 4-byte unsigned integer */
3544 __itt_e_int64, /* 8-byte integer */
3545 __itt_e_uint64, /* 8-byte unsigned integer */
3546 __itt_e_float, /* 4-byte floating */
3547 __itt_e_double, /* 8-byte floating */
3548 __itt_e_last = __itt_e_double
3549 } __itt_av_data_type;
3550
3551 /**
3552 * @brief Save an array data to a file.
3553 * Output format is defined by the file extension. The csv and bmp formats are supported (bmp - for 2-dimensional array only).
3554 * @param[in] data - pointer to the array data
3555 * @param[in] rank - the rank of the array
3556 * @param[in] dimensions - pointer to an array of integers, which specifies the array dimensions.
3557 * The size of dimensions must be equal to the rank
3558 * @param[in] type - the type of the array, specified as one of the __itt_av_data_type values (for intrinsic types)
3559 * @param[in] filePath - the file path; the output format is defined by the file extension
3560 * @param[in] columnOrder - defines how the array is stored in the linear memory.
3561 * It should be 1 for column-major order (e.g. in FORTRAN) or 0 - for row-major order (e.g. in C).
3562 */
3563
3564 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3565 int ITTAPI __itt_av_saveA(void *data, int rank, const int *dimensions, int type, const char *filePath, int columnOrder);
3566 int ITTAPI __itt_av_saveW(void *data, int rank, const int *dimensions, int type, const wchar_t *filePath, int columnOrder);
3567 #if defined(UNICODE) || defined(_UNICODE)
3568 # define __itt_av_save __itt_av_saveW
3569 # define __itt_av_save_ptr __itt_av_saveW_ptr
3570 #else /* UNICODE */
3571 # define __itt_av_save __itt_av_saveA
3572 # define __itt_av_save_ptr __itt_av_saveA_ptr
3573 #endif /* UNICODE */
3574 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3575 int ITTAPI __itt_av_save(void *data, int rank, const int *dimensions, int type, const char *filePath, int columnOrder);
3576 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3577
3578 /** @cond exclude_from_documentation */
3579 #ifndef INTEL_NO_MACRO_BODY
3580 #ifndef INTEL_NO_ITTNOTIFY_API
3581 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3582 ITT_STUB(ITTAPI, int, av_saveA, (void *data, int rank, const int *dimensions, int type, const char *filePath, int columnOrder))
3583 ITT_STUB(ITTAPI, int, av_saveW, (void *data, int rank, const int *dimensions, int type, const wchar_t *filePath, int columnOrder))
3584 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3585 ITT_STUB(ITTAPI, int, av_save, (void *data, int rank, const int *dimensions, int type, const char *filePath, int columnOrder))
3586 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3587 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3588 #define __itt_av_saveA ITTNOTIFY_DATA(av_saveA)
3589 #define __itt_av_saveA_ptr ITTNOTIFY_NAME(av_saveA)
3590 #define __itt_av_saveW ITTNOTIFY_DATA(av_saveW)
3591 #define __itt_av_saveW_ptr ITTNOTIFY_NAME(av_saveW)
3592 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3593 #define __itt_av_save ITTNOTIFY_DATA(av_save)
3594 #define __itt_av_save_ptr ITTNOTIFY_NAME(av_save)
3595 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3596 #else /* INTEL_NO_ITTNOTIFY_API */
3597 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3598 #define __itt_av_saveA(name)
3599 #define __itt_av_saveA_ptr 0
3600 #define __itt_av_saveW(name)
3601 #define __itt_av_saveW_ptr 0
3602 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3603 #define __itt_av_save(name)
3604 #define __itt_av_save_ptr 0
3605 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3606 #endif /* INTEL_NO_ITTNOTIFY_API */
3607 #else /* INTEL_NO_MACRO_BODY */
3608 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3609 #define __itt_av_saveA_ptr 0
3610 #define __itt_av_saveW_ptr 0
3611 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3612 #define __itt_av_save_ptr 0
3613 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3614 #endif /* INTEL_NO_MACRO_BODY */
3615 /** @endcond */
3616
3617 void ITTAPI __itt_enable_attach(void);
3618
3619 /** @cond exclude_from_documentation */
3620 #ifndef INTEL_NO_MACRO_BODY
3621 #ifndef INTEL_NO_ITTNOTIFY_API
3622 ITT_STUBV(ITTAPI, void, enable_attach, (void))
3623 #define __itt_enable_attach ITTNOTIFY_VOID(enable_attach)
3624 #define __itt_enable_attach_ptr ITTNOTIFY_NAME(enable_attach)
3625 #else /* INTEL_NO_ITTNOTIFY_API */
3626 #define __itt_enable_attach()
3627 #define __itt_enable_attach_ptr 0
3628 #endif /* INTEL_NO_ITTNOTIFY_API */
3629 #else /* INTEL_NO_MACRO_BODY */
3630 #define __itt_enable_attach_ptr 0
3631 #endif /* INTEL_NO_MACRO_BODY */
3632 /** @endcond */
3633
3634 /** @cond exclude_from_gpa_documentation */
3635
3636 /** @} arrays group */
3637
3638 /** @endcond */
3639
3640 /**
3641 * @brief Module load notification
3642 * This API is used to report necessary information in case of bypassing default system loader.
3643 * Notification should be done immediately after this module is loaded to process memory.
3644 * @param[in] start_addr - module start address
3645 * @param[in] end_addr - module end address
3646 * @param[in] path - file system full path to the module
3647 */
3648 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3649 void ITTAPI __itt_module_loadA(void *start_addr, void *end_addr, const char *path);
3650 void ITTAPI __itt_module_loadW(void *start_addr, void *end_addr, const wchar_t *path);
3651 #if defined(UNICODE) || defined(_UNICODE)
3652 # define __itt_module_load __itt_module_loadW
3653 # define __itt_module_load_ptr __itt_module_loadW_ptr
3654 #else /* UNICODE */
3655 # define __itt_module_load __itt_module_loadA
3656 # define __itt_module_load_ptr __itt_module_loadA_ptr
3657 #endif /* UNICODE */
3658 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3659 void ITTAPI __itt_module_load(void *start_addr, void *end_addr, const char *path);
3660 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3661
3662 /** @cond exclude_from_documentation */
3663 #ifndef INTEL_NO_MACRO_BODY
3664 #ifndef INTEL_NO_ITTNOTIFY_API
3665 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3666 ITT_STUB(ITTAPI, void, module_loadA, (void *start_addr, void *end_addr, const char *path))
3667 ITT_STUB(ITTAPI, void, module_loadW, (void *start_addr, void *end_addr, const wchar_t *path))
3668 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3669 ITT_STUB(ITTAPI, void, module_load, (void *start_addr, void *end_addr, const char *path))
3670 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3671 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3672 #define __itt_module_loadA ITTNOTIFY_VOID(module_loadA)
3673 #define __itt_module_loadA_ptr ITTNOTIFY_NAME(module_loadA)
3674 #define __itt_module_loadW ITTNOTIFY_VOID(module_loadW)
3675 #define __itt_module_loadW_ptr ITTNOTIFY_NAME(module_loadW)
3676 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3677 #define __itt_module_load ITTNOTIFY_VOID(module_load)
3678 #define __itt_module_load_ptr ITTNOTIFY_NAME(module_load)
3679 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3680 #else /* INTEL_NO_ITTNOTIFY_API */
3681 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3682 #define __itt_module_loadA(start_addr, end_addr, path)
3683 #define __itt_module_loadA_ptr 0
3684 #define __itt_module_loadW(start_addr, end_addr, path)
3685 #define __itt_module_loadW_ptr 0
3686 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3687 #define __itt_module_load(start_addr, end_addr, path)
3688 #define __itt_module_load_ptr 0
3689 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3690 #endif /* INTEL_NO_ITTNOTIFY_API */
3691 #else /* INTEL_NO_MACRO_BODY */
3692 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3693 #define __itt_module_loadA_ptr 0
3694 #define __itt_module_loadW_ptr 0
3695 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3696 #define __itt_module_load_ptr 0
3697 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3698 #endif /* INTEL_NO_MACRO_BODY */
3699 /** @endcond */
3700
3701 /**
3702 * @brief Report module unload
3703 * This API is used to report necessary information in case of bypassing default system loader.
3704 * Notification should be done just before the module is unloaded from process memory.
3705 * @param[in] addr - base address of loaded module
3706 */
3707 void ITTAPI __itt_module_unload(void *addr);
3708
3709 /** @cond exclude_from_documentation */
3710 #ifndef INTEL_NO_MACRO_BODY
3711 #ifndef INTEL_NO_ITTNOTIFY_API
3712 ITT_STUBV(ITTAPI, void, module_unload, (void *addr))
3713 #define __itt_module_unload ITTNOTIFY_VOID(module_unload)
3714 #define __itt_module_unload_ptr ITTNOTIFY_NAME(module_unload)
3715 #else /* INTEL_NO_ITTNOTIFY_API */
3716 #define __itt_module_unload(addr)
3717 #define __itt_module_unload_ptr 0
3718 #endif /* INTEL_NO_ITTNOTIFY_API */
3719 #else /* INTEL_NO_MACRO_BODY */
3720 #define __itt_module_unload_ptr 0
3721 #endif /* INTEL_NO_MACRO_BODY */
3722 /** @endcond */
3723
3724 /** @cond exclude_from_documentation */
3725 typedef enum
3726 {
3727 __itt_module_type_unknown = 0,
3728 __itt_module_type_elf,
3729 __itt_module_type_coff
3730 } __itt_module_type;
3731 /** @endcond */
3732
3733 /** @cond exclude_from_documentation */
3734 typedef enum
3735 {
3736 itt_section_type_unknown,
3737 itt_section_type_bss, /* notifies that the section contains uninitialized data. These are the relevant section types and the modules that contain them:
3738 * ELF module: SHT_NOBITS section type
3739 * COFF module: IMAGE_SCN_CNT_UNINITIALIZED_DATA section type
3740 */
3741 itt_section_type_data, /* notifies that section contains initialized data. These are the relevant section types and the modules that contain them:
3742 * ELF module: SHT_PROGBITS section type
3743 * COFF module: IMAGE_SCN_CNT_INITIALIZED_DATA section type
3744 */
3745 itt_section_type_text /* notifies that the section contains executable code. These are the relevant section types and the modules that contain them:
3746 * ELF module: SHT_PROGBITS section type
3747 * COFF module: IMAGE_SCN_CNT_CODE section type
3748 */
3749 } __itt_section_type;
3750 /** @endcond */
3751
3752 /**
3753 * @hideinitializer
3754 * @brief bit-mask, detects a section attribute that indicates whether a section can be executed as code:
3755 * These are the relevant section attributes and the modules that contain them:
3756 * ELF module: PF_X section attribute
3757 * COFF module: IMAGE_SCN_MEM_EXECUTE attribute
3758 */
3759 #define __itt_section_exec 0x20000000
3760
3761 /**
3762 * @hideinitializer
3763 * @brief bit-mask, detects a section attribute that indicates whether a section can be read.
3764 * These are the relevant section attributes and the modules that contain them:
3765 * ELF module: PF_R attribute
3766 * COFF module: IMAGE_SCN_MEM_READ attribute
3767 */
3768 #define __itt_section_read 0x40000000
3769
3770 /**
3771 * @hideinitializer
3772 * @brief bit-mask, detects a section attribute that indicates whether a section can be written to.
3773 * These are the relevant section attributes and the modules that contain them:
3774 * ELF module: PF_W attribute
3775 * COFF module: IMAGE_SCN_MEM_WRITE attribute
3776 */
3777 #define __itt_section_write 0x80000000
3778
3779 /** @cond exclude_from_documentation */
3780 #pragma pack(push, 8)
3781
3782 typedef struct ___itt_section_info
3783 {
3784 const char* name; /*!< Section name in UTF8 */
3785 __itt_section_type type; /*!< Section content and semantics description */
3786 size_t flags; /*!< Section bit flags that describe attributes using bit mask
3787 * Zero if disabled, non-zero if enabled
3788 */
3789 void* start_addr; /*!< Section load(relocated) start address */
3790 size_t size; /*!< Section file offset */
3791 size_t file_offset; /*!< Section size */
3792 } __itt_section_info;
3793
3794 #pragma pack(pop)
3795 /** @endcond */
3796
3797 /** @cond exclude_from_documentation */
3798 #pragma pack(push, 8)
3799
3800 typedef struct ___itt_module_object
3801 {
3802 unsigned int version; /*!< API version*/
3803 __itt_id module_id; /*!< Unique identifier. This is unchanged for sections that belong to the same module */
3804 __itt_module_type module_type; /*!< Binary module format */
3805 const char* module_name; /*!< Unique module name or path to module in UTF8
3806 * Contains module name when module_bufer and module_size exist
3807 * Contains module path when module_bufer and module_size absent
3808 * module_name remains the same for the certain module_id
3809 */
3810 void* module_buffer; /*!< Module buffer content */
3811 size_t module_size; /*!< Module buffer size */
3812 /*!< If module_buffer and module_size exist, the binary module is dumped onto the system.
3813 * If module_buffer and module_size do not exist,
3814 * the binary module exists on the system already.
3815 * The module_name parameter contains the path to the module.
3816 */
3817 __itt_section_info* section_array; /*!< Reference to section information */
3818 size_t section_number;
3819 } __itt_module_object;
3820
3821 #pragma pack(pop)
3822 /** @endcond */
3823
3824 /**
3825 * @brief Load module content and its loaded(relocated) sections.
3826 * This API is useful to save a module, or specify its location on the system and report information about loaded sections.
3827 * The target module is saved on the system if module buffer content and size are available.
3828 * If module buffer content and size are unavailable, the module name contains the path to the existing binary module.
3829 * @param[in] module_obj - provides module and section information, along with unique module identifiers (name,module ID)
3830 * which bind the binary module to particular sections.
3831 */
3832 void ITTAPI __itt_module_load_with_sections(__itt_module_object* module_obj);
3833
3834 /** @cond exclude_from_documentation */
3835 #ifndef INTEL_NO_MACRO_BODY
3836 #ifndef INTEL_NO_ITTNOTIFY_API
3837 ITT_STUBV(ITTAPI, void, module_load_with_sections, (__itt_module_object* module_obj))
3838 #define __itt_module_load_with_sections ITTNOTIFY_VOID(module_load_with_sections)
3839 #define __itt_module_load_with_sections_ptr ITTNOTIFY_NAME(module_load_with_sections)
3840 #else /* INTEL_NO_ITTNOTIFY_API */
3841 #define __itt_module_load_with_sections(module_obj)
3842 #define __itt_module_load_with_sections_ptr 0
3843 #endif /* INTEL_NO_ITTNOTIFY_API */
3844 #else /* INTEL_NO_MACRO_BODY */
3845 #define __itt_module_load_with_sections_ptr 0
3846 #endif /* INTEL_NO_MACRO_BODY */
3847 /** @endcond */
3848
3849 /**
3850 * @brief Unload a module and its loaded(relocated) sections.
3851 * This API notifies that the module and its sections were unloaded.
3852 * @param[in] module_obj - provides module and sections information, along with unique module identifiers (name,module ID)
3853 * which bind the binary module to particular sections.
3854 */
3855 void ITTAPI __itt_module_unload_with_sections(__itt_module_object* module_obj);
3856
3857 /** @cond exclude_from_documentation */
3858 #ifndef INTEL_NO_MACRO_BODY
3859 #ifndef INTEL_NO_ITTNOTIFY_API
3860 ITT_STUBV(ITTAPI, void, module_unload_with_sections, (__itt_module_object* module_obj))
3861 #define __itt_module_unload_with_sections ITTNOTIFY_VOID(module_unload_with_sections)
3862 #define __itt_module_unload_with_sections_ptr ITTNOTIFY_NAME(module_unload_with_sections)
3863 #else /* INTEL_NO_ITTNOTIFY_API */
3864 #define __itt_module_unload_with_sections(module_obj)
3865 #define __itt_module_unload_with_sections_ptr 0
3866 #endif /* INTEL_NO_ITTNOTIFY_API */
3867 #else /* INTEL_NO_MACRO_BODY */
3868 #define __itt_module_unload_with_sections_ptr 0
3869 #endif /* INTEL_NO_MACRO_BODY */
3870 /** @endcond */
3871
3872 #ifdef __cplusplus
3873 }
3874 #endif /* __cplusplus */
3875
3876 #endif /* _ITTNOTIFY_H_ */
3877
3878 #ifdef INTEL_ITTNOTIFY_API_PRIVATE
3879
3880 #ifndef _ITTNOTIFY_PRIVATE_
3881 #define _ITTNOTIFY_PRIVATE_
3882
3883 #ifdef __cplusplus
3884 extern "C" {
3885 #endif /* __cplusplus */
3886
3887 /**
3888 * @ingroup clockdomain
3889 * @brief Begin an overlapped task instance.
3890 * @param[in] domain The domain for this task
3891 * @param[in] clock_domain The clock domain controlling the execution of this call.
3892 * @param[in] timestamp The user defined timestamp.
3893 * @param[in] taskid The identifier for this task instance, *cannot* be __itt_null.
3894 * @param[in] parentid The parent of this task, or __itt_null.
3895 * @param[in] name The name of this task.
3896 */
3897 void ITTAPI __itt_task_begin_overlapped_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name);
3898
3899 /**
3900 * @ingroup clockdomain
3901 * @brief End an overlapped task instance.
3902 * @param[in] domain The domain for this task
3903 * @param[in] clock_domain The clock domain controlling the execution of this call.
3904 * @param[in] timestamp The user defined timestamp.
3905 * @param[in] taskid Explicit ID of finished task
3906 */
3907 void ITTAPI __itt_task_end_overlapped_ex(const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid);
3908
3909 /** @cond exclude_from_documentation */
3910 #ifndef INTEL_NO_MACRO_BODY
3911 #ifndef INTEL_NO_ITTNOTIFY_API
3912 ITT_STUBV(ITTAPI, void, task_begin_overlapped_ex, (const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid, __itt_id parentid, __itt_string_handle* name))
3913 ITT_STUBV(ITTAPI, void, task_end_overlapped_ex, (const __itt_domain* domain, __itt_clock_domain* clock_domain, unsigned long long timestamp, __itt_id taskid))
3914 #define __itt_task_begin_overlapped_ex(d,x,y,z,a,b) ITTNOTIFY_VOID_D5(task_begin_overlapped_ex,d,x,y,z,a,b)
3915 #define __itt_task_begin_overlapped_ex_ptr ITTNOTIFY_NAME(task_begin_overlapped_ex)
3916 #define __itt_task_end_overlapped_ex(d,x,y,z) ITTNOTIFY_VOID_D3(task_end_overlapped_ex,d,x,y,z)
3917 #define __itt_task_end_overlapped_ex_ptr ITTNOTIFY_NAME(task_end_overlapped_ex)
3918 #else /* INTEL_NO_ITTNOTIFY_API */
3919 #define __itt_task_begin_overlapped_ex(domain,clock_domain,timestamp,taskid,parentid,name)
3920 #define __itt_task_begin_overlapped_ex_ptr 0
3921 #define __itt_task_end_overlapped_ex(domain,clock_domain,timestamp,taskid)
3922 #define __itt_task_end_overlapped_ex_ptr 0
3923 #endif /* INTEL_NO_ITTNOTIFY_API */
3924 #else /* INTEL_NO_MACRO_BODY */
3925 #define __itt_task_begin_overlapped_ex_ptr 0
3926 #define __itt_task_end_overlapped_ptr 0
3927 #define __itt_task_end_overlapped_ex_ptr 0
3928 #endif /* INTEL_NO_MACRO_BODY */
3929 /** @endcond */
3930
3931 /**
3932 * @defgroup makrs_internal Marks
3933 * @ingroup internal
3934 * Marks group
3935 * @warning Internal API:
3936 * - It is not shipped to outside of Intel
3937 * - It is delivered to internal Intel teams using e-mail or SVN access only
3938 * @{
3939 */
3940 /** @brief user mark type */
3941 typedef int __itt_mark_type;
3942
3943 /**
3944 * @brief Creates a user mark type with the specified name using char or Unicode string.
3945 * @param[in] name - name of mark to create
3946 * @return Returns a handle to the mark type
3947 */
3948 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3949 __itt_mark_type ITTAPI __itt_mark_createA(const char *name);
3950 __itt_mark_type ITTAPI __itt_mark_createW(const wchar_t *name);
3951 #if defined(UNICODE) || defined(_UNICODE)
3952 # define __itt_mark_create __itt_mark_createW
3953 # define __itt_mark_create_ptr __itt_mark_createW_ptr
3954 #else /* UNICODE */
3955 # define __itt_mark_create __itt_mark_createA
3956 # define __itt_mark_create_ptr __itt_mark_createA_ptr
3957 #endif /* UNICODE */
3958 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3959 __itt_mark_type ITTAPI __itt_mark_create(const char *name);
3960 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3961
3962 /** @cond exclude_from_documentation */
3963 #ifndef INTEL_NO_MACRO_BODY
3964 #ifndef INTEL_NO_ITTNOTIFY_API
3965 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3966 ITT_STUB(ITTAPI, __itt_mark_type, mark_createA, (const char *name))
3967 ITT_STUB(ITTAPI, __itt_mark_type, mark_createW, (const wchar_t *name))
3968 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3969 ITT_STUB(ITTAPI, __itt_mark_type, mark_create, (const char *name))
3970 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3971 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3972 #define __itt_mark_createA ITTNOTIFY_DATA(mark_createA)
3973 #define __itt_mark_createA_ptr ITTNOTIFY_NAME(mark_createA)
3974 #define __itt_mark_createW ITTNOTIFY_DATA(mark_createW)
3975 #define __itt_mark_createW_ptr ITTNOTIFY_NAME(mark_createW)
3976 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3977 #define __itt_mark_create ITTNOTIFY_DATA(mark_create)
3978 #define __itt_mark_create_ptr ITTNOTIFY_NAME(mark_create)
3979 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3980 #else /* INTEL_NO_ITTNOTIFY_API */
3981 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3982 #define __itt_mark_createA(name) (__itt_mark_type)0
3983 #define __itt_mark_createA_ptr 0
3984 #define __itt_mark_createW(name) (__itt_mark_type)0
3985 #define __itt_mark_createW_ptr 0
3986 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3987 #define __itt_mark_create(name) (__itt_mark_type)0
3988 #define __itt_mark_create_ptr 0
3989 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3990 #endif /* INTEL_NO_ITTNOTIFY_API */
3991 #else /* INTEL_NO_MACRO_BODY */
3992 #if ITT_PLATFORM==ITT_PLATFORM_WIN
3993 #define __itt_mark_createA_ptr 0
3994 #define __itt_mark_createW_ptr 0
3995 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3996 #define __itt_mark_create_ptr 0
3997 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
3998 #endif /* INTEL_NO_MACRO_BODY */
3999 /** @endcond */
4000
4001 /**
4002 * @brief Creates a "discrete" user mark type of the specified type and an optional parameter using char or Unicode string.
4003 *
4004 * - The mark of "discrete" type is placed to collection results in case of success. It appears in overtime view(s) as a special tick sign.
4005 * - The call is "synchronous" - function returns after mark is actually added to results.
4006 * - This function is useful, for example, to mark different phases of application
4007 * (beginning of the next mark automatically meand end of current region).
4008 * - Can be used together with "continuous" marks (see below) at the same collection session
4009 * @param[in] mt - mark, created by __itt_mark_create(const char* name) function
4010 * @param[in] parameter - string parameter of mark
4011 * @return Returns zero value in case of success, non-zero value otherwise.
4012 */
4013 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4014 int ITTAPI __itt_markA(__itt_mark_type mt, const char *parameter);
4015 int ITTAPI __itt_markW(__itt_mark_type mt, const wchar_t *parameter);
4016 #if defined(UNICODE) || defined(_UNICODE)
4017 # define __itt_mark __itt_markW
4018 # define __itt_mark_ptr __itt_markW_ptr
4019 #else /* UNICODE */
4020 # define __itt_mark __itt_markA
4021 # define __itt_mark_ptr __itt_markA_ptr
4022 #endif /* UNICODE */
4023 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4024 int ITTAPI __itt_mark(__itt_mark_type mt, const char *parameter);
4025 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4026
4027 /** @cond exclude_from_documentation */
4028 #ifndef INTEL_NO_MACRO_BODY
4029 #ifndef INTEL_NO_ITTNOTIFY_API
4030 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4031 ITT_STUB(ITTAPI, int, markA, (__itt_mark_type mt, const char *parameter))
4032 ITT_STUB(ITTAPI, int, markW, (__itt_mark_type mt, const wchar_t *parameter))
4033 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4034 ITT_STUB(ITTAPI, int, mark, (__itt_mark_type mt, const char *parameter))
4035 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4036 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4037 #define __itt_markA ITTNOTIFY_DATA(markA)
4038 #define __itt_markA_ptr ITTNOTIFY_NAME(markA)
4039 #define __itt_markW ITTNOTIFY_DATA(markW)
4040 #define __itt_markW_ptr ITTNOTIFY_NAME(markW)
4041 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4042 #define __itt_mark ITTNOTIFY_DATA(mark)
4043 #define __itt_mark_ptr ITTNOTIFY_NAME(mark)
4044 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4045 #else /* INTEL_NO_ITTNOTIFY_API */
4046 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4047 #define __itt_markA(mt, parameter) (int)0
4048 #define __itt_markA_ptr 0
4049 #define __itt_markW(mt, parameter) (int)0
4050 #define __itt_markW_ptr 0
4051 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4052 #define __itt_mark(mt, parameter) (int)0
4053 #define __itt_mark_ptr 0
4054 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4055 #endif /* INTEL_NO_ITTNOTIFY_API */
4056 #else /* INTEL_NO_MACRO_BODY */
4057 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4058 #define __itt_markA_ptr 0
4059 #define __itt_markW_ptr 0
4060 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4061 #define __itt_mark_ptr 0
4062 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4063 #endif /* INTEL_NO_MACRO_BODY */
4064 /** @endcond */
4065
4066 /**
4067 * @brief Use this if necessary to create a "discrete" user event type (mark) for process
4068 * rather then for one thread
4069 * @see int __itt_mark(__itt_mark_type mt, const char* parameter);
4070 */
4071 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4072 int ITTAPI __itt_mark_globalA(__itt_mark_type mt, const char *parameter);
4073 int ITTAPI __itt_mark_globalW(__itt_mark_type mt, const wchar_t *parameter);
4074 #if defined(UNICODE) || defined(_UNICODE)
4075 # define __itt_mark_global __itt_mark_globalW
4076 # define __itt_mark_global_ptr __itt_mark_globalW_ptr
4077 #else /* UNICODE */
4078 # define __itt_mark_global __itt_mark_globalA
4079 # define __itt_mark_global_ptr __itt_mark_globalA_ptr
4080 #endif /* UNICODE */
4081 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4082 int ITTAPI __itt_mark_global(__itt_mark_type mt, const char *parameter);
4083 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4084
4085 /** @cond exclude_from_documentation */
4086 #ifndef INTEL_NO_MACRO_BODY
4087 #ifndef INTEL_NO_ITTNOTIFY_API
4088 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4089 ITT_STUB(ITTAPI, int, mark_globalA, (__itt_mark_type mt, const char *parameter))
4090 ITT_STUB(ITTAPI, int, mark_globalW, (__itt_mark_type mt, const wchar_t *parameter))
4091 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4092 ITT_STUB(ITTAPI, int, mark_global, (__itt_mark_type mt, const char *parameter))
4093 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4094 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4095 #define __itt_mark_globalA ITTNOTIFY_DATA(mark_globalA)
4096 #define __itt_mark_globalA_ptr ITTNOTIFY_NAME(mark_globalA)
4097 #define __itt_mark_globalW ITTNOTIFY_DATA(mark_globalW)
4098 #define __itt_mark_globalW_ptr ITTNOTIFY_NAME(mark_globalW)
4099 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4100 #define __itt_mark_global ITTNOTIFY_DATA(mark_global)
4101 #define __itt_mark_global_ptr ITTNOTIFY_NAME(mark_global)
4102 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4103 #else /* INTEL_NO_ITTNOTIFY_API */
4104 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4105 #define __itt_mark_globalA(mt, parameter) (int)0
4106 #define __itt_mark_globalA_ptr 0
4107 #define __itt_mark_globalW(mt, parameter) (int)0
4108 #define __itt_mark_globalW_ptr 0
4109 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4110 #define __itt_mark_global(mt, parameter) (int)0
4111 #define __itt_mark_global_ptr 0
4112 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4113 #endif /* INTEL_NO_ITTNOTIFY_API */
4114 #else /* INTEL_NO_MACRO_BODY */
4115 #if ITT_PLATFORM==ITT_PLATFORM_WIN
4116 #define __itt_mark_globalA_ptr 0
4117 #define __itt_mark_globalW_ptr 0
4118 #else /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4119 #define __itt_mark_global_ptr 0
4120 #endif /* ITT_PLATFORM==ITT_PLATFORM_WIN */
4121 #endif /* INTEL_NO_MACRO_BODY */
4122 /** @endcond */
4123
4124 /**
4125 * @brief Creates an "end" point for "continuous" mark with specified name.
4126 *
4127 * - Returns zero value in case of success, non-zero value otherwise.
4128 * Also returns non-zero value when preceding "begin" point for the
4129 * mark with the same name failed to be created or not created.
4130 * - The mark of "continuous" type is placed to collection results in
4131 * case of success. It appears in overtime view(s) as a special tick
4132 * sign (different from "discrete" mark) together with line from
4133 * corresponding "begin" mark to "end" mark.
4134 * @note Continuous marks can overlap and be nested inside each other.
4135 * Discrete mark can be nested inside marked region
4136 * @param[in] mt - mark, created by __itt_mark_create(const char* name) function
4137 * @return Returns zero value in case of success, non-zero value otherwise.
4138 */
4139 int ITTAPI __itt_mark_off(__itt_mark_type mt);
4140
4141 /** @cond exclude_from_documentation */
4142 #ifndef INTEL_NO_MACRO_BODY
4143 #ifndef INTEL_NO_ITTNOTIFY_API
4144 ITT_STUB(ITTAPI, int, mark_off, (__itt_mark_type mt))
4145 #define __itt_mark_off ITTNOTIFY_DATA(mark_off)
4146 #define __itt_mark_off_ptr ITTNOTIFY_NAME(mark_off)
4147 #else /* INTEL_NO_ITTNOTIFY_API */
4148 #define __itt_mark_off(mt) (int)0
4149 #define __itt_mark_off_ptr 0
4150 #endif /* INTEL_NO_ITTNOTIFY_API */
4151 #else /* INTEL_NO_MACRO_BODY */
4152 #define __itt_mark_off_ptr 0
4153 #endif /* INTEL_NO_MACRO_BODY */
4154 /** @endcond */
4155
4156 /**
4157 * @brief Use this if necessary to create an "end" point for mark of process
4158 * @see int __itt_mark_off(__itt_mark_type mt);
4159 */
4160 int ITTAPI __itt_mark_global_off(__itt_mark_type mt);
4161
4162 /** @cond exclude_from_documentation */
4163 #ifndef INTEL_NO_MACRO_BODY
4164 #ifndef INTEL_NO_ITTNOTIFY_API
4165 ITT_STUB(ITTAPI, int, mark_global_off, (__itt_mark_type mt))
4166 #define __itt_mark_global_off ITTNOTIFY_DATA(mark_global_off)
4167 #define __itt_mark_global_off_ptr ITTNOTIFY_NAME(mark_global_off)
4168 #else /* INTEL_NO_ITTNOTIFY_API */
4169 #define __itt_mark_global_off(mt) (int)0
4170 #define __itt_mark_global_off_ptr 0
4171 #endif /* INTEL_NO_ITTNOTIFY_API */
4172 #else /* INTEL_NO_MACRO_BODY */
4173 #define __itt_mark_global_off_ptr 0
4174 #endif /* INTEL_NO_MACRO_BODY */
4175 /** @endcond */
4176 /** @} marks group */
4177
4178 /**
4179 * @defgroup counters_internal Counters
4180 * @ingroup internal
4181 * Counters group
4182 * @{
4183 */
4184
4185
4186 /**
4187 * @defgroup stitch Stack Stitching
4188 * @ingroup internal
4189 * Stack Stitching group
4190 * @{
4191 */
4192 /**
4193 * @brief opaque structure for counter identification
4194 */
4195 typedef struct ___itt_caller *__itt_caller;
4196
4197 /**
4198 * @brief Create the stitch point e.g. a point in call stack where other stacks should be stitched to.
4199 * The function returns a unique identifier which is used to match the cut points with corresponding stitch points.
4200 */
4201 __itt_caller ITTAPI __itt_stack_caller_create(void);
4202
4203 /** @cond exclude_from_documentation */
4204 #ifndef INTEL_NO_MACRO_BODY
4205 #ifndef INTEL_NO_ITTNOTIFY_API
4206 ITT_STUB(ITTAPI, __itt_caller, stack_caller_create, (void))
4207 #define __itt_stack_caller_create ITTNOTIFY_DATA(stack_caller_create)
4208 #define __itt_stack_caller_create_ptr ITTNOTIFY_NAME(stack_caller_create)
4209 #else /* INTEL_NO_ITTNOTIFY_API */
4210 #define __itt_stack_caller_create() (__itt_caller)0
4211 #define __itt_stack_caller_create_ptr 0
4212 #endif /* INTEL_NO_ITTNOTIFY_API */
4213 #else /* INTEL_NO_MACRO_BODY */
4214 #define __itt_stack_caller_create_ptr 0
4215 #endif /* INTEL_NO_MACRO_BODY */
4216 /** @endcond */
4217
4218 /**
4219 * @brief Destroy the information about stitch point identified by the pointer previously returned by __itt_stack_caller_create()
4220 */
4221 void ITTAPI __itt_stack_caller_destroy(__itt_caller id);
4222
4223 /** @cond exclude_from_documentation */
4224 #ifndef INTEL_NO_MACRO_BODY
4225 #ifndef INTEL_NO_ITTNOTIFY_API
4226 ITT_STUBV(ITTAPI, void, stack_caller_destroy, (__itt_caller id))
4227 #define __itt_stack_caller_destroy ITTNOTIFY_VOID(stack_caller_destroy)
4228 #define __itt_stack_caller_destroy_ptr ITTNOTIFY_NAME(stack_caller_destroy)
4229 #else /* INTEL_NO_ITTNOTIFY_API */
4230 #define __itt_stack_caller_destroy(id)
4231 #define __itt_stack_caller_destroy_ptr 0
4232 #endif /* INTEL_NO_ITTNOTIFY_API */
4233 #else /* INTEL_NO_MACRO_BODY */
4234 #define __itt_stack_caller_destroy_ptr 0
4235 #endif /* INTEL_NO_MACRO_BODY */
4236 /** @endcond */
4237
4238 /**
4239 * @brief Sets the cut point. Stack from each event which occurs after this call will be cut
4240 * at the same stack level the function was called and stitched to the corresponding stitch point.
4241 */
4242 void ITTAPI __itt_stack_callee_enter(__itt_caller id);
4243
4244 /** @cond exclude_from_documentation */
4245 #ifndef INTEL_NO_MACRO_BODY
4246 #ifndef INTEL_NO_ITTNOTIFY_API
4247 ITT_STUBV(ITTAPI, void, stack_callee_enter, (__itt_caller id))
4248 #define __itt_stack_callee_enter ITTNOTIFY_VOID(stack_callee_enter)
4249 #define __itt_stack_callee_enter_ptr ITTNOTIFY_NAME(stack_callee_enter)
4250 #else /* INTEL_NO_ITTNOTIFY_API */
4251 #define __itt_stack_callee_enter(id)
4252 #define __itt_stack_callee_enter_ptr 0
4253 #endif /* INTEL_NO_ITTNOTIFY_API */
4254 #else /* INTEL_NO_MACRO_BODY */
4255 #define __itt_stack_callee_enter_ptr 0
4256 #endif /* INTEL_NO_MACRO_BODY */
4257 /** @endcond */
4258
4259 /**
4260 * @brief This function eliminates the cut point which was set by latest __itt_stack_callee_enter().
4261 */
4262 void ITTAPI __itt_stack_callee_leave(__itt_caller id);
4263
4264 /** @cond exclude_from_documentation */
4265 #ifndef INTEL_NO_MACRO_BODY
4266 #ifndef INTEL_NO_ITTNOTIFY_API
4267 ITT_STUBV(ITTAPI, void, stack_callee_leave, (__itt_caller id))
4268 #define __itt_stack_callee_leave ITTNOTIFY_VOID(stack_callee_leave)
4269 #define __itt_stack_callee_leave_ptr ITTNOTIFY_NAME(stack_callee_leave)
4270 #else /* INTEL_NO_ITTNOTIFY_API */
4271 #define __itt_stack_callee_leave(id)
4272 #define __itt_stack_callee_leave_ptr 0
4273 #endif /* INTEL_NO_ITTNOTIFY_API */
4274 #else /* INTEL_NO_MACRO_BODY */
4275 #define __itt_stack_callee_leave_ptr 0
4276 #endif /* INTEL_NO_MACRO_BODY */
4277 /** @endcond */
4278
4279 /** @} stitch group */
4280
4281 /* ***************************************************************************************************************************** */
4282
4283 #include <stdarg.h>
4284
4285 /** @cond exclude_from_documentation */
4286 typedef enum __itt_error_code
4287 {
4288 __itt_error_success = 0, /*!< no error */
4289 __itt_error_no_module = 1, /*!< module can't be loaded */
4290 /* %1$s -- library name; win: %2$d -- system error code; unx: %2$s -- system error message. */
4291 __itt_error_no_symbol = 2, /*!< symbol not found */
4292 /* %1$s -- library name, %2$s -- symbol name. */
4293 __itt_error_unknown_group = 3, /*!< unknown group specified */
4294 /* %1$s -- env var name, %2$s -- group name. */
4295 __itt_error_cant_read_env = 4, /*!< GetEnvironmentVariable() failed */
4296 /* %1$s -- env var name, %2$d -- system error. */
4297 __itt_error_env_too_long = 5, /*!< variable value too long */
4298 /* %1$s -- env var name, %2$d -- actual length of the var, %3$d -- max allowed length. */
4299 __itt_error_system = 6 /*!< pthread_mutexattr_init or pthread_mutex_init failed */
4300 /* %1$s -- function name, %2$d -- errno. */
4301 } __itt_error_code;
4302
4303 typedef void (__itt_error_handler_t)(__itt_error_code code, va_list);
4304 __itt_error_handler_t* __itt_set_error_handler(__itt_error_handler_t*);
4305
4306 const char* ITTAPI __itt_api_version(void);
4307 /** @endcond */
4308
4309 /** @cond exclude_from_documentation */
4310 #ifndef INTEL_NO_MACRO_BODY
4311 #ifndef INTEL_NO_ITTNOTIFY_API
4312 #define __itt_error_handler ITT_JOIN(INTEL_ITTNOTIFY_PREFIX, error_handler)
4313 void __itt_error_handler(__itt_error_code code, va_list args);
4314 extern const int ITTNOTIFY_NAME(err);
4315 #define __itt_err ITTNOTIFY_NAME(err)
4316 ITT_STUB(ITTAPI, const char*, api_version, (void))
4317 #define __itt_api_version ITTNOTIFY_DATA(api_version)
4318 #define __itt_api_version_ptr ITTNOTIFY_NAME(api_version)
4319 #else /* INTEL_NO_ITTNOTIFY_API */
4320 #define __itt_api_version() (const char*)0
4321 #define __itt_api_version_ptr 0
4322 #endif /* INTEL_NO_ITTNOTIFY_API */
4323 #else /* INTEL_NO_MACRO_BODY */
4324 #define __itt_api_version_ptr 0
4325 #endif /* INTEL_NO_MACRO_BODY */
4326 /** @endcond */
4327
4328 #ifdef __cplusplus
4329 }
4330 #endif /* __cplusplus */
4331
4332 #endif /* _ITTNOTIFY_PRIVATE_ */
4333
4334 #endif /* INTEL_ITTNOTIFY_API_PRIVATE */
4335