Merge pull request #698 from williamfgc/bindings

Bindings

ReadMe.md

@@ -70,7 +70,7 @@ $ cmake -DCMAKE_INSTALL_PREFIX=/opt/adios2/2.2.0/gnu/openmpi ../ADIOS2
 ...
 
 ADIOS2 build configuration:
-  ADIOS Version: 2.1.0
+  ADIOS Version: 2.2.0
   C++ Compiler : GNU 5.4.0 
     /usr/bin/c++
 

bindings/C/c/adios2_c_types.h

@@ -99,6 +99,15 @@ typedef enum {
     adios2_step_status_end_of_stream = 2
 } adios2_step_status;
 
+typedef enum {
+    adios2_shapeid_unknown = -1,
+    adios2_shapeid_global_value = 0,
+    adios2_shapeid_global_array = 1,
+    adios2_shapeid_joined_array = 2,
+    adios2_shapeid_local_value = 3,
+    adios2_shapeid_local_array = 4
+} adios2_shapeid;
+
 static size_t adios2_string_array_element_max_size = 4096;
 
 #ifdef __cplusplus

bindings/C/c/adios2_c_variable.cpp

@@ -68,6 +68,34 @@ adios2_type adios2_variable_type(const adios2_variable *variable)
     return itType->second.front();
 }
 
+adios2_shapeid adios2_variable_shapeid(const adios2_variable *variable)
+{
+    adios2::helper::CheckForNullptr(variable,
+                                    "for const adios2_variable, in call to "
+                                    "adios2_variable_shapeid");
+    const adios2::core::VariableBase *variableBase =
+        reinterpret_cast<const adios2::core::VariableBase *>(variable);
+
+    switch (variableBase->m_ShapeID)
+    {
+    case (adios2::ShapeID::GlobalValue):
+        return adios2_shapeid_global_value;
+
+    case (adios2::ShapeID::GlobalArray):
+        return adios2_shapeid_global_array;
+
+    case (adios2::ShapeID::JoinedArray):
+        return adios2_shapeid_joined_array;
+
+    case (adios2::ShapeID::LocalValue):
+        return adios2_shapeid_local_value;
+
+    case (adios2::ShapeID::LocalArray):
+        return adios2_shapeid_local_array;
+    }
+    return adios2_shapeid_unknown;
+}
+
 int adios2_variable_is_constant_dims(const adios2_variable *variable)
 {
     adios2::helper::CheckForNullptr(variable,

bindings/C/c/adios2_c_variable.h

@@ -34,6 +34,13 @@ const char *adios2_variable_name(const adios2_variable *variable,
  */
 adios2_type adios2_variable_type(const adios2_variable *variable);
 
+/**
+ * Retrieve variable shapeid
+ * @param variable handler
+ * @return shapeid enum type
+ */
+adios2_shapeid adios2_variable_shapeid(const adios2_variable *variable);
+
 /**
  * Check if dimensions are constant
  * @param variable

bindings/CXX11/cxx11/ADIOS.h

@@ -35,18 +35,56 @@ class ADIOS
 {
 
 public:
+    /**
+     * adios2 library starting point. Creates an ADIOS object allowing a runtime
+     * config file.
+     * @param configFile runtime config file
+     * @param mpiComm defines domain scope from application
+     * @param debugMode true: extra user-input debugging information, false: run
+     * without checking user-input (stable workflows)
+     * @exception std::invalid_argument in debugMode = true if user input is
+     * incorrect
+     */
     ADIOS(const std::string &configFile, MPI_Comm mpiComm,
           const bool debugMode = true);
 
+    /**
+     * adios2 library starting point. Creates an ADIOS object.
+     * @param mpiComm defines domain scope from application
+     * @param debugMode true: extra user-input debugging information, false: run
+     * without checking user-input (stable workflows)
+     * @exception std::invalid_argument in debugMode = true if user input is
+     * incorrect
+     */
     ADIOS(MPI_Comm mpiComm, const bool debugMode = true);
 
+    /**
+     * adios2 NON-MPI library starting point. Creates an ADIOS object allowing a
+     * runtime config file.
+     * @param configFile runtime config file
+     * @param debugMode true: extra user-input debugging information, false: run
+     * without checking user-input (stable workflows)
+     * @exception std::invalid_argument in debugMode = true if user input is
+     * incorrect
+     */
     ADIOS(const std::string &configFile, const bool debugMode = true);
 
+    /**
+     * adios2 NON-MPI library starting point. Creates an ADIOS object
+     * @param debugMode true: extra user-input debugging information, false: run
+     * without checking user-input (stable workflows)
+     * @exception std::invalid_argument in debugMode = true if user input is
+     * incorrect
+     */
     ADIOS(const bool debugMode = true);
 
-    /** true: valid object, false: invalid object */
+    /** object inspection true: valid object, false: invalid object */
     explicit operator bool() const noexcept;
 
+    /** prevents copy constructor, ADIOS is the only object that manages its own
+     * memory. Create a separate for independent tasks */
+    ADIOS(const ADIOS &) = delete;
+
     ~ADIOS() = default;
 
     /**
@@ -84,6 +122,8 @@ public:
      * @param type supported ADIOS2 operator
      * @param parameters key/value parameters at the operator level
      * @return Operator object
+     * @exception std::invalid_argument if library can't support current
+     * operator due to missing dependency
      */
     Operator DefineOperator(const std::string name, const std::string type,
                             const Params &parameters = Params());
@@ -95,6 +135,8 @@ public:
      * @param function C++11 callable target
      * @param parameters key/value parameters at the operator level
      * @return Operator object for Callback functions
+     * * @exception std::invalid_argument if library can't support current
+     * operator due to missing dependency or unsupported signature
      */
     template <class R, class... Args>
     Operator DefineOperator(const std::string name,

bindings/CXX11/cxx11/Attribute.cpp

@@ -32,7 +32,7 @@ namespace adios2
     }                                                                          \
                                                                                \
     template <>                                                                \
-    const std::string &Attribute<T>::Name() const                              \
+    std::string Attribute<T>::Name() const                                     \
     {                                                                          \
         helper::CheckForNullptr(m_Attribute,                                   \
                                 "in call to Attribute<T>::Name()");            \

bindings/CXX11/cxx11/Attribute.h

@@ -35,10 +35,25 @@ public:
     Attribute<T>() = default;
     ~Attribute<T>() = default;
 
+    /** true: valid, false: invalid */
     explicit operator bool() const noexcept;
 
-    const std::string &Name() const;
+    /**
+     * Inspect attribute name
+     * @return unique name identifier
+     */
+    std::string Name() const;
+
+    /**
+     * Inspect attribute type
+     * @return type
+     */
     std::string Type() const;
+
+    /**
+     * Inspect attribute data
+     * @return data
+     */
     std::vector<T> Data() const;
 
 private:

bindings/CXX11/cxx11/Engine.cpp

@@ -27,6 +27,18 @@ Engine::operator bool() const noexcept
     return *m_Engine ? true : false;
 }
 
+std::string Engine::Name() const
+{
+    adios2::helper::CheckForNullptr(m_Engine, "in call to Engine::Name");
+    return m_Engine->m_Name;
+}
+
+std::string Engine::Type() const
+{
+    adios2::helper::CheckForNullptr(m_Engine, "in call to Engine::Type");
+    return m_Engine->m_EngineType;
+}
+
 StepStatus Engine::BeginStep()
 {
     adios2::helper::CheckForNullptr(m_Engine, "in call to Engine::BeginStep");

bindings/CXX11/cxx11/Engine.h

@@ -36,32 +36,115 @@ public:
 
     ~Engine() = default;
 
+    /**
+     * true: valid engine, false: invalid, not created with IO::Open
+     */
     explicit operator bool() const noexcept;
 
+    /**
+     * Inspect engine name
+     * @return name from IO::Open
+     */
+    std::string Name() const;
+
+    /**
+     * From ADIOS2 engine type: "bpfile", "sst", "dataman", "insitumpi", "hdf5"
+     * @return engine type as lower case string
+     */
+    std::string Type() const;
+
+    /**
+     * Begin a logical adios2 step, overloaded version with timeoutSeconds = 0
+     * and mode = NextAvailable
+     * @return current step status
+     */
     StepStatus BeginStep();
 
+    /**
+     * Begin a logical adios2 step, overloaded version for advanced stream
+     * control
+     * @param mode how
+     * @param timeoutSeconds
+     * @return current step status
+     */
     StepStatus BeginStep(const StepMode mode, const float timeoutSeconds = 0.f);
 
+    /**
+     * Inspect current logical step
+     * @return current logical step
+     */
     size_t CurrentStep() const;
 
+    /** Informs the engine that the BeginStep Put/Get EndStep schedule is fixed
+     * for the entire run. Simplifies synchronized between reader and writers
+     */
     void FixedSchedule();
 
+    /**
+     * Put data associated with a Variable in the adios2 library
+     * @param variable contains variable metadata information
+     * @param data user data to be associated with a variable
+     * @param launch mode policy
+     * <pre>
+     * 		Mode::Deferred, lazy evaulation, do not use data until first
+     * PerformPuts, EndStep, or Close. THis is the preferred way.
+     * 		Mode::Sync, data is consumed by the adios2 library and can be
+     * reused immediately. Special case, only use if necessary.
+     * </pre>
+     * @exception std::invalid_argument for invalid variable or nullptr data
+     */
     template <class T>
     void Put(Variable<T> variable, const T *data,
              const Mode launch = Mode::Deferred);
 
+    /**
+     * Put data associated with a Variable in the adios2 library
+     * Overloaded version that accepts a variable name string.
+     * @param variable contains variable metadata information
+     * @param data user data to be associated with a variable
+     * @param launch mode policy
+     * <pre>
+     * 		Mode::Deferred, lazy evaulation, do not use data until first
+     * PerformPuts, EndStep, or Close. THis is the preferred way.
+     * 		Mode::Sync, data is consumed by the adios2 library and can be
+     * reused immediately. Special case, only use if necessary.
+     * </pre>
+     * @exception std::invalid_argument if variable not found or nullptr data
+     */
     template <class T>
     void Put(const std::string &variableName, const T *data,
              const Mode launch = Mode::Deferred);
 
+    /**
+     * Put data associated with a Variable in the adios2 library
+     * Overloaded version that accepts r-values and single variable data.
+     * @param variable contains variable metadata information
+     * @param datum user data to be associated with a variable, r-value or
+     * single data value
+     * @param launch mode policy, optional for API consistency, internally is
+     * always sync
+     * @exception std::invalid_argument if variable is invalid or nullptr &datum
+     */
     template <class T>
     void Put(Variable<T> variable, const T &datum,
              const Mode launch = Mode::Deferred);
 
+    /**
+     * Put data associated with a Variable in the adios2 library
+     * Overloaded version that accepts variables names, and r-values and single
+     * variable data.
+     * @param variable contains variable metadata information
+     * @param data user data to be associated with a variable r-value or single
+     * data value
+     * @param launch mode policy, optional for API consistency, internally is
+     * always sync
+     * @exception std::invalid_argument if variable is invalid or nullptr &datum
+     */
     template <class T>
     void Put(const std::string &variableName, const T &datum,
              const Mode launch = Mode::Deferred);
 
+    /** Perform all Put calls in Deferred mode up to this point */
     void PerformPuts();
 
     template <class T>
@@ -87,12 +170,24 @@ public:
     void Get(const std::string &variableName, std::vector<T> &dataV,
              const Mode launch = Mode::Deferred);
 
+    /** Perform all Get calls in Deferred mode up to this point */
     void PerformGets();
 
+    /**
+     * Ends current step, by default consumes all Put/Get data in deferred mode
+     */
     void EndStep();
 
+    /**
+     * Manually flush to underlying transport to guarantee data is moved
+     * @param transportIndex
+     */
     void Flush(const int transportIndex = -1);
 
+    /**
+     * Closes current engine, after this call an engine becomes invalid
+     * @param transportIndex
+     */
     void Close(const int transportIndex = -1);
 
 private:

bindings/CXX11/cxx11/IO.cpp

@@ -88,6 +88,8 @@ void IO::AddOperator(Operator &op, const Params &parameters)
     m_IO.AddOperator(*op.m_Operator, parameters);
 }
 
+std::string IO::EngineType() const noexcept { return m_IO.m_EngineType; }
+
 // PRIVATE
 IO::IO(core::IO &io) : m_IO(io) {}
 

bindings/CXX11/cxx11/IO.h

@@ -211,9 +211,7 @@ public:
      */
     Engine Open(const std::string &name, const Mode mode);
 
-    /**
-     * Flushed all engines created with this IO with the Open function
-     */
+    /** Flushes all engines created with this IO with the Open function */
     void FlushAll();
 
     /**
@@ -240,8 +238,19 @@ public:
      */
     std::map<std::string, Params> AvailableAttributes() noexcept;
 
+    /**
+     * Adds an Operator at the IO object level
+     * @param op operator to be added
+     * @param parameters key/value parameters for op
+     */
     void AddOperator(Operator &op, const Params &parameters = Params());
 
+    /**
+     * Inspect current engine type
+     * @return current engine type
+     */
+    std::string EngineType() const noexcept;
+
 private:
     IO(core::IO &io);
     core::IO &m_IO;

bindings/CXX11/cxx11/Variable.cpp

@@ -54,7 +54,7 @@ namespace adios2
     }                                                                          \
                                                                                \
     template <>                                                                \
-    const std::string &Variable<T>::Name() const                               \
+    std::string Variable<T>::Name() const                                      \
     {                                                                          \
         helper::CheckForNullptr(m_Variable, "in call to Variable<T>::Name");   \
         return m_Variable->m_Name;                                             \
@@ -82,21 +82,21 @@ namespace adios2
     }                                                                          \
                                                                                \
     template <>                                                                \
-    const Dims &Variable<T>::Shape() const                                     \
+    Dims Variable<T>::Shape() const                                            \
     {                                                                          \
         helper::CheckForNullptr(m_Variable, "in call to Variable<T>::Shape");  \
         return m_Variable->m_Shape;                                            \
     }                                                                          \
                                                                                \
     template <>                                                                \
-    const Dims &Variable<T>::Start() const                                     \
+    Dims Variable<T>::Start() const                                            \
     {                                                                          \
         helper::CheckForNullptr(m_Variable, "in call to Variable<T>::Start");  \
         return m_Variable->m_Start;                                            \
     }                                                                          \
                                                                                \
     template <>                                                                \
-    const Dims &Variable<T>::Count() const                                     \
+    Dims Variable<T>::Count() const                                            \
     {                                                                          \
         helper::CheckForNullptr(m_Variable, "in call to Variable<T>::Count");  \
         return m_Variable->m_Count;                                            \

bindings/CXX11/cxx11/Variable.h

@@ -42,21 +42,94 @@ public:
 
     explicit operator bool() const noexcept;
 
+    /**
+     * Sets a variable selection modifying current {start, count}
+     * Count is the dimension from Start point
+     * @param selection input {start, count}
+     */
     void SetSelection(const Box<Dims> &selection);
+
+    /**
+     * Sets a step selection modifying current startStep, countStep
+     * countStep is the number of steps from startStep point
+     * @param stepSelection input {startStep, countStep}
+     */
     void SetStepSelection(const Box<size_t> &stepSelection);
+
+    /**
+     * Returns the number of elements required for pre-allocation based on
+     * current count and stepsCount
+     * @return elements of type T required for pre-allocation
+     */
     size_t SelectionSize() const;
-    const std::string &Name() const;
+
+    /**
+     * Inspects Variable name
+     * @return name
+     */
+    std::string Name() const;
+
+    /**
+     * Inspects Variable type
+     * @return type string literal containing the type: double, float, unsigned
+     * int, etc.
+     */
     std::string Type() const;
+
+    /**
+     * Inspects size of the current element type, sizeof(T)
+     * @return sizeof(T) for current system
+     */
     size_t Sizeof() const;
+
+    /**
+     * Inspects shape id for current variable
+     * @return from enum adios2::ShapeID
+     */
     adios2::ShapeID ShapeID() const;
-    const Dims &Shape() const;
-    const Dims &Start() const;
-    const Dims &Count() const;
+
+    /**
+     * Inspects current shape
+     * @return shape vector
+     */
+    Dims Shape() const;
+
+    /**
+     * Inspects current start point
+     * @return start vector
+     */
+    Dims Start() const;
+
+    /**
+     * Inspects current count from start
+     * @return count vector
+     */
+    Dims Count() const;
+
+    /**
+     * For read mode, inspect the number of available steps
+     * @return available steps
+     */
     size_t Steps() const;
+
+    /**
+     * For read mode, inspect the start step for available steps
+     * @return available start step
+     */
     size_t StepsStart() const;
 
+    /**
+     * EXPERIMENTAL: Adds operator at the Variable level
+     * @param op operator to be added
+     * @param parameters key/value settings
+     * @return operator order in OperatorsInfo
+     */
     unsigned int AddOperator(Operator &op, const Params &parameters = Params());
 
+    /**
+     * EXPERIMENTAL: carries information about an Operator added with
+     * AddOperator
+     */
     struct OperatorInfo
     {
         Operator ADIOSOperator;
@@ -64,6 +137,10 @@ public:
         Params Info;
     };
 
+    /**
+     * EXPERIMENTAL: inspects current operators added with AddOperator
+     * @return vector of Variable<T>::OperatorInfo
+     */
     std::vector<OperatorInfo> OperatorsInfo() const noexcept;
 
 private:

bindings/CXX98/cxx98/cxx98ADIOS.cpp

@@ -53,15 +53,6 @@ ADIOS::ADIOS(const bool debugMode)
 }
 #endif
 
-ADIOS::ADIOS(const ADIOS &adios)
-{
-    if (m_ADIOS != NULL)
-    {
-        adios2_finalize(m_ADIOS);
-    }
-    m_ADIOS = adios.m_ADIOS;
-}
-
 ADIOS::~ADIOS()
 {
     if (m_ADIOS != NULL)
@@ -85,5 +76,8 @@ IO ADIOS::AtIO(const std::string &name)
 
 void ADIOS::FlushAll() { adios2_flush_all(m_ADIOS); }
 
+// Disabled copy constructor
+ADIOS::ADIOS(const ADIOS &adios) : m_ADIOS(NULL) {}
+
 } // end namespace cxx03
 } // end namespace adios2

bindings/CXX98/cxx98/cxx98ADIOS.h

@@ -34,24 +34,77 @@ class ADIOS
 
 public:
 #ifdef ADIOS2_HAVE_MPI
+
+    /**
+     * adios2 library starting point. Creates an ADIOS object allowing a
+     * runtime
+     * config file.
+     * @param configFile runtime config file
+     * @param mpiComm defines domain scope from application
+     * @param debugMode true: extra user-input debugging information, false:
+     * run
+     * without checking user-input (stable workflows)
+     * @exception std::invalid_argument in debugMode = true if user input is
+     * incorrect
+     */
     ADIOS(const std::string &configFile, MPI_Comm mpiComm,
           const bool debugMode = true);
 
+    /**
+     * adios2 library starting point. Creates an ADIOS object.
+     * @param mpiComm defines domain scope from application
+     * @param debugMode true: extra user-input debugging information, false: run
+     * without checking user-input (stable workflows)
+     * @exception std::invalid_argument in debugMode = true if user input is
+     * incorrect
+     */
     ADIOS(MPI_Comm mpiComm, const bool debugMode = true);
 
+    /**
+     * adios2 library starting point. Creates an ADIOS object allowing a
+     * runtime config file and using MPI_COMM_SELF
+     * @param configFile runtime config file
+     * @param debugMode true: extra user-input debugging information, false: run
+     * without checking user-input (stable workflows)
+     * @exception std::invalid_argument in debugMode = true if user input is
+     * incorrect
+     */
     ADIOS(const std::string &configFile, const bool debugMode = true);
 
+    /**
+     * adios2 library starting point. Creates an ADIOS object using
+     * MPI_COMM_SELF
+     * @param debugMode true: extra user-input debugging information, false: run
+     * without checking user-input (stable workflows)
+     * @exception std::invalid_argument in debugMode = true if user input is
+     * incorrect
+     */
     ADIOS(const bool debugMode = true);
 #else
+    /**
+     * adios2 NON-MPI library starting point. Creates an ADIOS object allowing a
+     * runtime config file.
+     * @param configFile runtime config file
+     * @param debugMode true: extra user-input debugging information, false: run
+     * without checking user-input (stable workflows)
+     * @exception std::invalid_argument in debugMode = true if user input is
+     * incorrect
+     */
     ADIOS(const std::string &configFile, const bool debugMode = true);
 
+    /**