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