ADIOS.h 7.3 KB
Newer Older
1
2
3
4
/*
 * Distributed under the OSI-approved Apache License, Version 2.0.  See
 * accompanying file Copyright.txt for details.
 *
5
 * ADIOS.h : ADIOS library starting point, factory class for IO objects
6
7
8
9
10
11
12
13
 *  Created on: Oct 3, 2016
 *      Author: William F Godoy godoywf@ornl.gov
 */

#ifndef ADIOS2_CORE_ADIOS_H_
#define ADIOS2_CORE_ADIOS_H_

/// \cond EXCLUDE_FROM_DOXYGEN
William F Godoy's avatar
William F Godoy committed
14
#include <functional> //std::function
15
16
17
18
19
20
21
22
#include <map>
#include <memory> //std::shared_ptr
#include <string>
#include <vector>
/// \endcond

#include "adios2/ADIOSConfig.h"
#include "adios2/ADIOSMPICommOnly.h"
William F Godoy's avatar
William F Godoy committed
23
#include "adios2/ADIOSTypes.h"
24
#include "adios2/core/IO.h"
25
#include "adios2/core/Operator.h"
26

wgodoy's avatar
wgodoy committed
27
namespace adios2
28
29
30
31
32
33
34
35
{

/** @brief Point of entry class for an application.
 *         Serves as factory of IO class objects and Transforms */
class ADIOS
{
public:
    /** Passed from parallel constructor, MPI_Comm is a pointer itself. */
William F Godoy's avatar
William F Godoy committed
36
    MPI_Comm m_MPIComm;
37

38
    /**
William F Godoy's avatar
William F Godoy committed
39
     * @brief Constructor for MPI applications WITH a XML config file
40
     * @param configFile XML format (maybe support different formats in the
41
42
43
44
45
46
     * future (json)?)
     * @param mpiComm MPI communicator from application, make sure is valid
     * through the scope of adios2 calls
     * @param debugMode true (default): extra exception checks (recommended),
     * false: optional feature to turn off checks on user input data,
     * recommended in stable flows
47
     */
William F Godoy's avatar
William F Godoy committed
48
    ADIOS(const std::string configFile, MPI_Comm mpiComm,
William F Godoy's avatar
William F Godoy committed
49
          const bool debugMode = true, const std::string hostLanguage = "C++");
50
51

    /**
52
53
     * @brief Constructor for non-MPI applications WITH a XML config file (it
     * must end with extension .xml)
54
     * @param configFile XML format (maybe support different formats in the
55
56
57
58
     * future (json)?)
     * @param debugMode true (default): extra exception checks (recommended),
     * false: optional feature to turn off checks on user input data,
     * recommended in stable flows
59
     */
William F Godoy's avatar
William F Godoy committed
60
61
    ADIOS(const std::string configFile, const bool debugMode = true,
          const std::string hostLanguage = "C++");
62
63
64
65

    /**
     * @brief Constructor for MPI apps WITHOUT a XML config file
     * @param mpiComm MPI communicator from application
66
67
68
     * @param debugMode true (default): extra exception checks (recommended),
     * false: optional feature to turn off checks on user input data,
     * recommended in stable flows
69
     */
William F Godoy's avatar
William F Godoy committed
70
71
    ADIOS(MPI_Comm mpiComm, const bool debugMode = true,
          const std::string hostLanguage = "C++");
72

William F Godoy's avatar
William F Godoy committed
73
74
    /**
     *  @brief ADIOS no-MPI default empty constructor
75
76
77
     * @param debugMode true (default): extra exception checks (recommended),
     * false: optional feature to turn off checks on user input data,
     * recommended in stable flows
William F Godoy's avatar
William F Godoy committed
78
     */
William F Godoy's avatar
William F Godoy committed
79
    ADIOS(const bool debugMode = true, const std::string hostLanguage = "C++");
William F Godoy's avatar
William F Godoy committed
80

81
82
83
84
85
86
87
    /**
     * Delete copy constructor explicitly. Objects shouldn't be allowed to be
     * redefined. Use smart pointers if this is absolutely necessary.
     * @param adios reference to another adios object
     */
    ADIOS(const ADIOS &adios) = delete;

88
89
90
    ~ADIOS() = default;

    /**
91
     * Declares a new IO class object and returns a reference to that object.
92
     * @param ioName must be unique
93
94
95
     * @return reference to newly created IO object inside current ADIOS object
     * @exception std::invalid_argument if IO with unique name is already
     * declared, in debug mode only
96
     */
97
    IO &DeclareIO(const std::string name);
98

99
    /**
100
101
     * Retrieve a reference to an existing IO object created with DeclareIO.
     * Follow the C++11 STL containers at function.
102
103
     * @param name of IO to look for
     * @return if IO exists returns a reference to existing IO object inside
104
105
106
     * ADIOS
     * @exception std::invalid_argument if IO was not created with DeclareIO, in
     * debug mode only
107
     */
108
    IO &AtIO(const std::string name);
109

110
111
112
113
114
115
116
117
    /**
     * Declares a derived class of the Operator abstract class. If object is
     * defined in the user
     * config file, by name, it will be already created during the processing of
     * the config file. So this function returns a reference to that object.
     * @param name must be unique for each operator created with DefineOperator
     * @param type from derived class
     * @param parameters optional parameters
118
     * @return reference to Operator object
119
120
     * @exception std::invalid_argument if Operator with unique name is already
     * defined, in debug mode only
121
122
123
124
     */
    Operator &DefineOperator(const std::string name, const std::string type,
                             const Params &parameters = Params());

125
126
127
128
    /**
     * Signature for passing Callback functions as operators
     * @param name unique operator name
     * @param function callable function
129
     * @param parameters optional key-value pairs parameters
130
     * @return reference to Operator object
131
132
     * @exception std::invalid_argument if Operator with unique name is already
     * defined, in debug mode only
133
     */
134
135
136
137
138
139
140
    template <class R, class... Args>
    Operator &DefineOperator(const std::string name,
                             const std::function<R(Args...)> &function,
                             const Params &parameters = Params());

    /**
     * Retrieve a reference pointer to an existing Operator object
141
     * created with DefineOperator.
142
143
144
145
     * @return if IO exists returns a reference to existing IO object inside
     * ADIOS, otherwise a nullptr
     */
    Operator *InquireOperator(const std::string name) noexcept;
146

147
private:
148
    /** XML File to be read containing configuration information */
149
    const std::string m_ConfigFile;
150
151

    /** if true will do more checks, exceptions, warnings, expect slower code */
152
    const bool m_DebugMode = true;
153

William F Godoy's avatar
William F Godoy committed
154
155
156
    /** Changed by language bindings in constructor */
    const std::string m_HostLanguage = "C++";

157
158
159
160
161
162
163
164
165
166
167
    /**
     * @brief List of IO class objects defined from either ADIOS
     * configuration file (XML) or the DeclareIO function explicitly.
     * Using map (binary tree) to preserve references returned by DeclareIO.
     * <pre>
     *     Key: unique method name
     *     Value: IO class object
     * </pre>
     */
    std::map<std::string, IO> m_IOs;

168
169
170
    /** operators created with DefineOperator */
    std::map<std::string, std::shared_ptr<Operator>> m_Operators;

171
172
    /** throws exception if m_MPIComm = MPI_COMM_NULL */
    void CheckMPI() const;
William F Godoy's avatar
William F Godoy committed
173
174
175
176
177
178
179
180
181

/** define CallBack1 */
#define declare_type(T)                                                        \
    Operator &DefineCallBack(                                                  \
        const std::string name,                                                \
        const std::function<void(const T *, const std::string,                 \
                                 const std::string, const std::string,         \
                                 const Dims &)> &function,                     \
        const Params &parameters);
182

William F Godoy's avatar
William F Godoy committed
183
184
    ADIOS2_FOREACH_TYPE_1ARG(declare_type)
#undef declare_type
185
186
187
188

    /** define CallBack2 */
    Operator &DefineCallBack(
        const std::string name,
William F Godoy's avatar
William F Godoy committed
189
190
191
        const std::function<void(void *, const std::string &,
                                 const std::string &, const std::string &,
                                 const Dims &)> &function,
192
        const Params &parameters);
193
194
};

195
} // end namespace adios2
196

197
198
#include "ADIOS.inl"

199
#endif /* ADIOS2_ADIOS_H_ */