1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
/* ppaml/tracer.h -- PPAML timing instrumentation interface
* Copyright (C) 2013 Galois, Inc.
*
* This library is free software: you can redistribute it and/or modify it
* under the terms of the GNU General Public License as published by the Free
* Software Foundation, either version 3 of the License, or (at your option)
* any later version.
*
* This library is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
* more details.
*
* You should have received a copy of the GNU General Public License along with
* this library. If not, see <http://www.gnu.org/licenses/>.
*
* To contact Galois, complete the Web form at
* <http://corp.galois.com/contact/> or write to Galois, Inc., 421 Southwest
* 6th Avenue, Suite 300, Portland, Oregon, 97204-1622. */
/**
* @file tracer.h
* Library interface.
*
* This file defines the top-level interface for ppamltracer.
*
* Since all the functions in this file operate on @ref ppaml_tracer_t and @ref
* ppaml_phase_t structs, their documentation has been moved to the relevant
* data structure pages.
*/
#ifndef PPAML_TRACER_H
#define PPAML_TRACER_H
#include "tracer/internal.h" // for ppaml_tracer_t and ppaml_phase_t
/**
* @name Resource management
*
* @{
*/
/**
* Initializes a ppaml_tracer_t.
*
* @relates ppaml_tracer_t
*
* The trace report will be stored in Open Trace Format; all trace file paths
* will begin with @p report_name_base.
*
* @param[out] tracer pointer to the tracer to be initialized
* @param[in] report_name_base base file name for the report files
*
* @pre @p tracer is nonnull.
* @pre @p *tracer is uninitialized.
*
* @return 0 upon success
* @return 1 if the Open Trace Format file manager could not be initialized
* @return 2 if the Open Trace Format writer could not be initialized
* @return 3 if setting the trace resolution failed
* @return 4 if defining the main OTF process failed
*
* @post If the function return successfully, @p *tracer is initialized.
*/
int ppaml_tracer_init(ppaml_tracer_t *tracer, const char report_name_base[]);
/**
* Finalizes a ppaml_tracer_t.
*
* @relates ppaml_tracer_t
*
* @param[out] tracer pointer to the tracer to be finalized
*
* @pre @p tracer is nonnull.
* @pre @p *tracer is initialized.
*
* @return 0 upon success
* @return 1 if the Open Trace Format writer could not be closed
*
* @post If the function return successfully, @p *tracer is uninitialized.
*/
int ppaml_tracer_done(ppaml_tracer_t *tracer);
/**
* Initializes a ppaml_phase_t.
*
* @relates ppaml_phase_t
*
* @param[in] tracer pointer to the tracer which records this phase
* @param[out] phase pointer to the phase to be initialized
* @param[in] name name of the phase
*
* @pre @p tracer is nonnull.
* @pre @p *tracer is initialized.
* @pre @p phase is nonnull.
* @pre @p *phase is uninitialized.
*
* @return 0 upon success
* @return 1 if defining the phase failed
*
* @post If the function return successfully, @p *phase is initialized.
*/
int ppaml_phase_init(
ppaml_tracer_t *tracer,
ppaml_phase_t *phase,
const char name[]);
/**
* Finalizes a ppaml_phase_t.
*
* @relates ppaml_phase_t
*
* @param[out] phase pointer to the phase to be finalized
*
* @pre @p phase is nonnull.
* @pre @p *phase is initialized.
*
* @return 0 upon success; a nonzero return indicates failure.
*
* @post If the function return successfully, @p *phase is uninitialized.
*/
int ppaml_phase_done(ppaml_phase_t *phase);
/// @}
/**
* @name Timing
*
* @{
*/
/**
* Records the start of a phase.
*
* @relates ppaml_phase_t
*
* @param[in] phase pointer to the phase
*
* @pre @p phase is nonnull.
* @pre @p *phase is initialized.
*
* @return 0 upon success
* @return 1 if getting the time failed
* @return 2 if recording the phase start failed
*/
int ppaml_phase_start(ppaml_phase_t *phase);
/**
* Records the end of a phase.
*
* @relates ppaml_phase_t
*
* @param[in] phase pointer to the phase
*
* @pre @p phase is nonnull.
* @pre @p *phase is initialized.
*
* @return 0 upon success
* @return 1 if getting the time failed
* @return 2 if recording the phase stop failed
*/
int ppaml_phase_stop(ppaml_phase_t *phase);
/// @}
#endif
|
