diff options
Diffstat (limited to 'include/ppaml/tracer.h')
-rw-r--r-- | include/ppaml/tracer.h | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/include/ppaml/tracer.h b/include/ppaml/tracer.h new file mode 100644 index 0000000..df9891a --- /dev/null +++ b/include/ppaml/tracer.h @@ -0,0 +1,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 |