CnC
cnc
itac.h
1
/* *******************************************************************************
2
* Copyright (c) 2007-2014, Intel Corporation
3
*
4
* Redistribution and use in source and binary forms, with or without
5
* modification, are permitted provided that the following conditions are met:
6
*
7
* * Redistributions of source code must retain the above copyright notice,
8
* this list of conditions and the following disclaimer.
9
* * Redistributions in binary form must reproduce the above copyright
10
* notice, this list of conditions and the following disclaimer in the
11
* documentation and/or other materials provided with the distribution.
12
* * Neither the name of Intel Corporation nor the names of its contributors
13
* may be used to endorse or promote products derived from this software
14
* without specific prior written permission.
15
*
16
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19
* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
20
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
22
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
23
* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26
********************************************************************************/
27
28
#pragma once
29
#ifndef _CNC_ITAC_H_
30
#define _CNC_ITAC_H_
31
32
/**
33
\page itac Using Intel(R) Trace Analyzer and Collector with CnC
34
A CnC program run can be traced with Intel(R) Trace Collector (ITC)
35
and post-morten analyzed with Intel(R) Trace Analyzer (ITA)
36
(http://software.intel.com/en-us/intel-trace-analyzer)
37
38
The CnC header files are instrumented with hooks into ITC; when
39
compiling with CNC_WITH_ITAC being defined the compiler will insert
40
calls into ITC. Those work in shared and distributed mode, with distCnC
41
you'll not only see the step-execution but also the communication.
42
If you construct your collections with names (string parameters to
43
their constructors) then the instrumentation will use those names and
44
create a meaningful trace without further manual instrumentation.
45
46
The CnC runtime will initialize ITC automatically. In shared memory
47
this will happen when the first context is created, in distributed memory
48
right when dist_cnc_init is created. You can call VT_INIT earlier
49
in the code if you want to to see ITC things before the first context
50
creation (shared memory).
51
52
Please see \ref itac_in on how to instrument your code further.
53
54
After instrumentation/recompilation the execution of your applicaton
55
"app" will let ITC write a tracefile "app.stf". To start analysis,
56
simply execute "traceanalyzer app.stf".
57
58
\section itac-tips Hints
59
For a more convinient file handling it is
60
recommended to let ITC write the trac in the "SINGLESTF" format:
61
simply set VT_LOGFILE_FORMAT=SINGLESTF when runnig your application.
62
63
Usually CnC codes are threaded. ITC will create a trace in which every
64
thread is shown as busy from it's first acitivity to its termination,
65
even if it is actually idle. To prevent this set VT_ENTER_USERCODE=0
66
at application runtime.
67
68
\section mpitrace Intel(R) MPI and ITC
69
The switch "-trace" to mpi[exec|run|cc] does not work
70
out-of-the-box. However, if using the instrumented version ITC will
71
load automatically. For this, compile with -DCNC_WITH_ITAC and link
72
against ITAC (see \ref itac_build). To load ITC in a
73
"plain" MPI environment (without recompiling or -linking), just
74
preload the following libraries:
75
\code
76
env LD_PRELOAD="libcnc.so:libcnc_mpi_itac.so:libVT.so" env DIST_CNC=MPI mpiexec -n ...
77
\endcode
78
or in debug mode
79
\code
80
env LD_PRELOAD="libcnc_debug.so:libcnc_mpi_itac_debug.so:libVT.so" env DIST_CNC=MPI mpiexec -n ...
81
\endcode
82
83
\section itac_build Compiling and linking with ITAC instrumentation
84
Apparently you need a working isntallation of ITAC. When compiling add
85
the include-directory of ITAC to your include path
86
(-I$VT_ROOT/include). When linking, add the slib directory to the
87
lib-path and link against the following libraries
88
- SOCKETS:-L$VT_SLIB_DIR -lVTcs $VT_ADD_LIBS
89
- MPI: use mpicxx/mpiicpc -trace -L$VT_SLIB_DIR
90
Please refer to the ITAC documentation for more details.
91
**/
92
93
/// \defgroup itac_in Instrumenting with/for ITAC
94
/// @{
95
/// Two Macros are provided for a convenient way to instrument your code with ITAC.
96
/// When adding instrumentation you need to take care about building your bainry properly (\ref itac_build).
97
#ifdef CNC_WITH_ITAC
98
99
#include <VT.h>
100
#include <iostream>
101
102
namespace
CnC
{
103
namespace
Internal {
104
105
struct
ITAC_FUNC {
106
ITAC_FUNC(
int
id
) { VT_enter(
id
, VT_NOSCL ); }
107
~ITAC_FUNC() { VT_leave( VT_NOSCL ); }
108
};
109
110
}
// namespace Internal
111
}
// namespace CnC
112
113
#define VT_THREAD_NAME( threadName ) VT_registernamed( threadName, -1 )
114
115
#define VT_FUNC( funcName ) __VT_FUNC__( funcName, __LINE__ )
116
#define VT_FUNC_D( funcName ) __VT_FUNC_D__( funcName, __LINE__ )
117
118
#define VT_INIT() VT_initialize( 0, 0 )
119
120
//%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
121
122
// -- Implementational macros for VT_FUNC --
123
// Guarantee that generated variable names get the line number appended.
124
// This allows to have several VT_FUNC statements in the same scope.
125
#define __VT_FUNC__( _funcName, _line ) ____VT_FUNC____( _funcName, _line, static )
126
#define __VT_FUNC_D__( _funcName, _line ) ____VT_FUNC____( _funcName, _line, )
127
#define ____VT_FUNC____( _funcName, _line, _qual ) \
128
_qual int ____CnC_vt_func_id____##_line = 0; \
129
if ( ____CnC_vt_func_id____##_line == 0 ) { VT_funcdef( _funcName, VT_NOCLASS, &____CnC_vt_func_id____##_line ); } \
130
CnC::Internal::ITAC_FUNC ____CnC_vt_func_obj____##_line( ____CnC_vt_func_id____##_line )
131
132
//%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
133
134
// you better not use this
135
#define VT_SYMDEF( _id, _name ) VT_symdef( _id, _name, NULL )
136
137
#else
138
139
#define VT_SYMDEF( _id, _name )
140
141
/// \def VT_THREAD_NAME( threadName )
142
/// Use this macro to define an (optional) name for your application thread, e.g. VT_THREAD_NAME( "myApp" ).
143
/// This name will appear for your thread in ITAC's event timeline.
144
/// \param threadName name of calling thread (in double quotes), to appear in ITAC tracefile
145
#define VT_THREAD_NAME( threadName )
146
147
/// \def VT_FUNC( funcName )
148
/// Use this macro to manually instrument your function (or scope) at its beginning, e.g. VT_FUNC( "MyClass::myMethod" );
149
/// See also \ref itac_build
150
/// \param funcName name of function (in double quotes), potentially including class/namespace hierachy
151
#define VT_FUNC( funcName )
152
153
/// \def VT_FUNC_D( funcName )
154
/// Similar to VT_FUNC, but the recorded function name can change between invocations.
155
/// It is slower, so don't use it unless really needed.
156
/// See also \ref itac_build
157
/// \param funcName name of function (in double quotes), potentially including class/namespace hierachy
158
#define VT_FUNC_D( funcName )
159
160
/// \def VT_INIT()
161
/// In shared memory, ITC needs to be initialized. This is done automatically with the first
162
/// context construction. Use this only if you want to see things in the trace before the first
163
/// context is created. Don't use it for distributed memory.
164
# define VT_INIT()
165
166
#endif //CNC_WITH_ITAC
167
168
/// @}
169
170
#endif // _CNC_ITAC_H_
CnC
CnC API.
Definition:
cnc.h:49
Generated on Wed Oct 28 2015 21:20:32 for CnC by
1.8.13