1MPIL_Trace_on(3) LAM/MPI MPIL_Trace_on(3)
2
6 MPIL_Trace_on - LAM/MPI-specific function to enable run-time tracing
7
9 #include <mpi.h>
10 int MPIL_Trace_on(void)
11
13 These functions give the application the flexibility to generate traces
14 only during certain interesting phases of the application's execution.
15 This technique can considerably reduce the size of the trace files and
16 burden of displaying them.
17 Both functions are collective over the MPI_COMM_WORLD communicator. In
19 typical usage, the -toff option of mpirun (1) would be used to enable
20 tracing, but start with the runtime switch in the off position. At the
21 beginning of an interesting phase of program execution, MPIL_Trace_on
22 would be called. MPIL_Trace_off would be called after the interesting
23 phase. Tracing can be turned on and off many times. Each period of
24 tracing eventually forms a trace segment in the trace file extracted by
25 lamtrace (1). If the on/off functions are never used and tracing is
26 enabled with the -ton option of mpirun (1), a single trace segment is
27 produced.
28 The on/off functions have no effect if tracing is not enabled by mpirun
30 (1) with either the -ton or -toff switches. Thus, an application can
31 be littered with these functions but run without trace collection and
32 very little additional overhead due to the no-operation function calls.
33 This is a LAM/MPI-specific function and is intended mainly for debug‐
35 ging. If this function is used, it should be used in conjunction with
36 the LAM_MPI C preprocessor macro
37 #if LAM_MPI
39 MPIL_Trace_on();
40 #endif
41
45 After the volume of generated traces exceeds a preset limit, the oldest
46 traces are discarded in favour of new traces. Avoiding discarded
47 traces is further incentive to use MPIL_Trace_on and MPIL_Trace_off .
48
52 All MPI routines in Fortran (except for MPI_WTIME and MPI_WTICK ) have
53 an additional argument ierr at the end of the argument list. ierr is
54 an integer and has the same meaning as the return value of the routine
55 in C. In Fortran, MPI routines are subroutines, and are invoked with
56 the call statement.
57 All MPI objects (e.g., MPI_Datatype , MPI_Comm ) are of type INTEGER in
59 Fortran.
60
63 If an error occurs in an MPI function, the current MPI error handler is
64 called to handle it. By default, this error handler aborts the MPI
65 job. The error handler may be changed with MPI_Errhandler_set ; the
66 predefined error handler MPI_ERRORS_RETURN may be used to cause error
67 values to be returned (in C and Fortran; this error handler is less
68 useful in with the C++ MPI bindings. The predefined error handler
69 MPI::ERRORS_THROW_EXCEPTIONS should be used in C++ if the error value
70 needs to be recovered). Note that MPI does not guarantee that an MPI
71 program can continue past an error.
72 All MPI routines (except MPI_Wtime and MPI_Wtick ) return an error
74 value; C routines as the value of the function and Fortran routines in
75 the last argument. The C++ bindings for MPI do not return error val‐
76 ues; instead, error values are communicated by throwing exceptions of
77 type MPI::Exception (but not by default). Exceptions are only thrown
78 if the error value is not MPI::SUCCESS .
79 Note that if the MPI::ERRORS_RETURN handler is set in C++, while MPI
82 functions will return upon an error, there will be no way to recover
83 what the actual error value was.
84 MPI_SUCCESS
85 - No error; MPI routine completed successfully.
86 MPI_ERR_OTHER
87 - Other error; use MPI_Error_string to get more information
88 about this error code.
89
92 MPI_Trace_off, mpirun
93
95 mpil_trace.c
96LAM/MPI 7.1.2 2/23/2006 MPIL_Trace_on(3)