AbstractIOHandler.hpp

/* Copyright 2017-2025 Fabian Koller, Axel Huebl, Franz Poeschel
 *
 * This file is part of openPMD-api.
 *
 * openPMD-api is free software: you can redistribute it and/or modify
 * it under the terms of of either the GNU General Public License or
 * the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * openPMD-api 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 and the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * and the GNU Lesser General Public License along with openPMD-api.
 * If not, see <http://www.gnu.org/licenses/>.
 */
#pragma once
 
#include "openPMD/IO/Access.hpp"
#include "openPMD/IO/Format.hpp"
#include "openPMD/IO/IOTask.hpp"
#include "openPMD/IterationEncoding.hpp"
#include "openPMD/config.hpp"
#include "openPMD/version.hpp"
 
#if openPMD_HAVE_MPI
#include <mpi.h>
#endif
 
#include <future>
#include <memory>
#include <queue>
#include <stdexcept>
#include <string>
#include <type_traits>
 
namespace openPMD
{
namespace json
{
    class JsonMatcher;
}

// do not write `enum class FlushLevel : unsigned char` here since NVHPC
// does not compile it correctly
enum class FlushLevel
{
    UserFlush,
    InternalFlush,
    SkeletonOnly,
    CreateOrOpenFiles
};
 
enum class OpenpmdStandard
{
    v_1_0_0,
    v_1_0_1,
    v_1_1_0,
    v_2_0_0
};
 
namespace auxiliary
{
    auto parseStandard(std::string const &) -> OpenpmdStandard;
    auto formatStandard(OpenpmdStandard) -> char const *;
} // namespace auxiliary
 
namespace internal
{
    struct FlushParams
    {
        FlushLevel flushLevel = FlushLevel::InternalFlush;
        std::string backendConfig = "{}";
 
        explicit FlushParams()
        {}
        FlushParams(FlushLevel flushLevel_in) : flushLevel(flushLevel_in)
        {}
        FlushParams(FlushLevel flushLevel_in, std::string backendConfig_in)
            : flushLevel(flushLevel_in)
            , backendConfig{std::move(backendConfig_in)}
        {}
    };
 
    /*
     * To be used for reading
     */
    FlushParams const defaultFlushParams{};
 
    struct ParsedFlushParams;

    enum class SeriesStatus : unsigned char
    {
        Default, 
        Parsing 
    };
 
    // @todo put this somewhere else
    template <typename Functor, typename... Args>
    auto withRWAccess(SeriesStatus &status, Functor &&functor, Args &&...args)
        -> decltype(std::forward<Functor>(functor)(std::forward<Args>(args)...))
    {
        using Res = decltype(std::forward<Functor>(functor)(
            std::forward<Args>(args)...));
        if constexpr (std::is_void_v<Res>)
        {
            auto oldStatus = status;
            status = internal::SeriesStatus::Parsing;
            try
            {
                std::forward<decltype(functor)>(functor)();
            }
            catch (...)
            {
                status = oldStatus;
                throw;
            }
            status = oldStatus;
            return;
        }
        else
        {
            auto oldStatus = status;
            status = internal::SeriesStatus::Parsing;
            Res res;
            try
            {
                res = std::forward<decltype(functor)>(functor)();
            }
            catch (...)
            {
                status = oldStatus;
                throw;
            }
            status = oldStatus;
            return res;
        }
    }
} // namespace internal
 
namespace detail
{
    class ADIOS2File;
}

class AbstractIOHandler
{
    friend class Series;
    friend class ADIOS2IOHandlerImpl;
    friend class JSONIOHandlerImpl;
    friend class HDF5IOHandlerImpl;
    friend class detail::ADIOS2File;
 
private:
    void setIterationEncoding(IterationEncoding encoding);
 
protected:
    // Needs to be a pointer due to include structure, this header is
    // transitively included in user code, but we don't reexport the JSON
    // library
    std::unique_ptr<json::JsonMatcher> jsonMatcher;
 
public:
#if openPMD_HAVE_MPI
    template <typename TracingJSON>
    AbstractIOHandler(
        std::optional<std::unique_ptr<AbstractIOHandler>> initialize_from,
        std::string path,
        Access at,
        TracingJSON &&jsonConfig,
        MPI_Comm);
#endif
 
    template <typename TracingJSON>
    AbstractIOHandler(
        std::optional<std::unique_ptr<AbstractIOHandler>> initialize_from,
        std::string path,
        Access at,
        TracingJSON &&jsonConfig);
 
    AbstractIOHandler(std::optional<std::unique_ptr<AbstractIOHandler>>);
 
    virtual ~AbstractIOHandler();
 
    AbstractIOHandler(AbstractIOHandler const &) = delete;
    // std::queue::queue(queue&&) is not noexcept
    // NOLINTNEXTLINE(performance-noexcept-move-constructor)
    AbstractIOHandler(AbstractIOHandler &&) noexcept(false);
 
    AbstractIOHandler &operator=(AbstractIOHandler const &) = delete;
    AbstractIOHandler &operator=(AbstractIOHandler &&) noexcept;

    virtual void enqueue(IOTask const &iotask)
    {
        m_work.push(iotask);
    }

    std::future<void> flush(internal::FlushParams const &);

    virtual std::future<void> flush(internal::ParsedFlushParams &) = 0;

    virtual std::string backendName() const = 0;
    virtual bool fullSupportForVariableBasedEncoding() const;
 
    std::string directory;
    /*
     * Originally, the reason for distinguishing these two was that during
     * parsing in reading access modes, the access type would be temporarily
     * const_cast'ed to an access type that would support modifying
     * the openPMD object model. Then, it would be const_cast'ed back to
     * READ_ONLY, to disable further modifications.
     * Due to this approach's tendency to cause subtle bugs, and due to its
     * difficult debugging properties, this was replaced by the SeriesStatus
     * enum, defined in this file.
     * The distinction of backendAccess and frontendAccess stays relevant, since
     * the frontend can use it in order to pretend to the backend that another
     * access type is being used. This is used by the file-based append mode,
     * which is entirely implemented by the frontend, which internally uses
     * the backend in CREATE mode.
     */
    Access m_backendAccess;
    Access m_frontendAccess;
    std::queue<IOTask> m_work;
 
    /**************************************************************************
     * Since the AbstractIOHandler is linked to every object of the frontend, *
     * it stores a number of members that are needed by methods traversing    *
     * the object hierarchy. Those members are found below.                   *
     **************************************************************************/

    bool m_lastFlushSuccessful = false;
    internal::SeriesStatus m_seriesStatus = internal::SeriesStatus::Default;
    IterationEncoding m_encoding = IterationEncoding::groupBased;
    OpenpmdStandard m_standard = auxiliary::parseStandard(getStandardDefault());
    bool m_verify_homogeneous_extents = true;
}; // AbstractIOHandler
 
} // namespace openPMD