Merge pull request #933 from williamfgc/py_lock

Py lock

bindings/Python/py11IO.cpp

@@ -34,10 +34,7 @@ void IO::SetParameter(const std::string key, const std::string value) noexcept
     m_IO.SetParameter(key, value);
 }
 
-const Params &IO::GetParameters() const noexcept
-{
-    return m_IO.GetParameters();
-}
+Params IO::Parameters() const noexcept { return m_IO.GetParameters(); }
 
 unsigned int IO::AddTransport(const std::string type, const Params &parameters)
 {

bindings/Python/py11IO.h

@@ -37,7 +37,7 @@ class IO
     void SetParameters(const Params &parameters) noexcept;
     void SetParameter(const std::string key, const std::string value) noexcept;
 
-    const Params &GetParameters() const noexcept;
+    Params Parameters() const noexcept;
 
     core::VariableBase *DefineVariable(const std::string &name,
                                        std::string &stringValue);

bindings/Python/py11glue.cpp

@@ -238,8 +238,7 @@ PYBIND11_MODULE(adios2, m)
         .def("SetParameters", &adios2::py11::IO::SetParameters,
              pybind11::arg("parameters") = adios2::Params())
         .def("SetParameter", &adios2::py11::IO::SetParameter)
-        .def("GetParameters", &adios2::py11::IO::GetParameters,
-             pybind11::return_value_policy::reference_internal)
+        .def("Parameters", &adios2::py11::IO::Parameters)
         .def("AddTransport", &adios2::py11::IO::AddTransport,
              pybind11::arg("type"),
              pybind11::arg("parameters") = adios2::Params())
@@ -287,7 +286,8 @@ PYBIND11_MODULE(adios2, m)
         .def("AvailableVariables", &adios2::py11::IO::AvailableVariables)
         .def("AvailableAttributes", &adios2::py11::IO::AvailableAttributes)
         .def("FlushAll", &adios2::py11::IO::FlushAll)
-        .def("EngineType", &adios2::py11::IO::EngineType);
+        .def("EngineType", &adios2::py11::IO::EngineType)
+        .def("LockDefinitions", &adios2::py11::IO::LockDefinitions);
 
     pybind11::class_<adios2::py11::Engine>(m, "py11::Engine")
         .def("BeginStep", &adios2::py11::Engine::BeginStep,

docs/user_guide/source/bindings/c.rst

@@ -4,7 +4,9 @@ C bindings
 
 The C bindings are specifically designed for C applications and those using an older C++ standard (98 and 03). If you are using a C++11 or more recent standard, please use the C++11 bindings.
 
-The C bindings are based on opaque pointers. Every ADIOS2 function that generates a new adios2_* unique handler returns the latter explicitly. Therefore, checks can be applied to know if the resulting handler is NULL. Other functions used to manipulate these valid handlers will return a value of type `enum adios2_error` explicitly. These possible errors are cased on the `C++ standardized exceptions <https://en.cppreference.com/w/cpp/error/exception>`_ . Each error will issue a more detailed description in the standard error output: `stderr`.
+The C bindings are based on opaque pointers. Every ADIOS2 function that generates a new adios2_* unique handler returns the latter explicitly. Therefore, checks can be applied to know if the resulting handler is NULL. Other functions used to manipulate these valid handlers will return a value of type `enum adios2_error` explicitly. These possible errors are based on the `C++ standardized exceptions <https://en.cppreference.com/w/cpp/error/exception>`_ . Each error will issue a more detailed description in the standard error output: `stderr`. 
+
+adios2_error possible values:
 
 .. code-block:: C
 
@@ -29,7 +31,7 @@ The C bindings are based on opaque pointers. Every ADIOS2 function that generate
    } adios2_error; 
 
 
-For example:
+Usage:
 
 .. code-block:: C
 

docs/user_guide/source/faq/faq.rst

@@ -1,5 +1,5 @@
 ##########################
-Frequently Asked Questions 
+Frequently Asked Questions
 ##########################
 
 
@@ -13,6 +13,9 @@ APIs
 
 #. :ref:`Can I use ADIOS 2 C++11 library with C++98 codes?`
 #. :ref:`Why are C and Fortran APIs missing functionality?`
+#. :ref:`C++11: Why are std::string arguments passed sometimes by value and sometimes by reference?`
+#. :ref:`C++11: Should I pass adios2:: objects by value or by reference?`
+#. :ref:`Fortran: Can I pass slices and temporary arrays to adios2_put?`
 
 Building on Titan
 *****************
@@ -44,6 +47,26 @@ Why are C and Fortran APIs missing functionality?
 Because language instrinsics are NOT THE SAME. For example, C++ and Python support key/value pair structures natively, *e.g.* std::map and dictionaries, respectively. Fortran and C only support arrays natively. Use the right language (tool) for the right task.
 
 
+C++11: Why are std::string arguments passed sometimes by value and sometimes by reference?
+------------------------------------------------------------------------------------------
+
+C++11, provides mechanisms to optimize copying small objects, rather than passing by reference. The latter was always the rule for C++98. When a string is passed by value, it's assumed that the name will be short, <= 15 characters, most of the time. While passing by reference indicates that the string can be of any size. Check the `isocpp guidelines on this topic <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f15-prefer-simple-and-conventional-ways-of-passing-information>`_ for more information.    
+
+
+C++11: Should I pass adios2:: objects by value or by reference?
+---------------------------------------------------------------
+
+`adios2::ADIOS`: always pass by reference this is the only "large memory" object; all others: pass by reference or value depending on your coding standards and requirements, they are small objects that wrap around a pointer to an internal object inside `adios2::ADIOS`.    
+
+
+Fortran: Can I pass slices and temporary arrays to adios2_put?
+--------------------------------------------------------------
+
+By definition the lifetime of a temporary if the scope of the function is passed to. Therefore, 
+you must use sync mode with adios2_put. Deferred mode will save garbage data since the memory location of a temporary is undefined after adios2_put, not able to reach adios2_end_step, adios2_close or adios2_perform_puts where the memory is actually used.   
+
+
+
 My application uses PGI on Titan, can I link ADIOS 2?
 -----------------------------------------------------
 

testing/adios2/bindings/python/TestBPWriteReadTypes.py

@@ -85,6 +85,14 @@ def check_name(name, name_list):
 ioWriter.SetParameter("profileunits", "microseconds")
 ioWriter.AddTransport("file")
 
+
+ioParams = ioWriter.Parameters()
+print("Final IO parameters")
+for key, value in ioParams.items():
+    print("\t" + key + ": " + value)
+
+ioWriter.LockDefinitions()
+
 # ADIOS Engine
 writer = ioWriter.Open("npTypes.bp", adios2.Mode.Write)