AbstractIOHandler.hpp

/* Copyright 2017-2021 Fabian Koller, Axel Huebl
 *
 * 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"
 
#if openPMD_HAVE_MPI
#include <mpi.h>
#endif
 
#include <future>
#include <memory>
#include <queue>
#include <stdexcept>
#include <string>
#include <type_traits>
 
namespace openPMD
{
// do not write `enum class FlushLevel : unsigned char` here since NVHPC
// does not compile it correctly
enum class FlushLevel
{
    UserFlush,
    InternalFlush,
    SkeletonOnly,
    CreateOrOpenFiles
};
 
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 detail::ADIOS2File;
 
private:
    IterationEncoding m_encoding = IterationEncoding::groupBased;
 
    void setIterationEncoding(IterationEncoding encoding)
    {
        /*
         * In file-based iteration encoding, the APPEND mode is handled entirely
         * by the frontend, the backend should just treat it as CREATE mode.
         * Similar for READ_LINEAR which should be treated as READ_RANDOM_ACCESS
         * in the backend.
         */
        if (encoding == IterationEncoding::fileBased)
        {
            switch (m_backendAccess)
            {
 
            case Access::READ_LINEAR:
                // do we really want to have those as const members..?
                *const_cast<Access *>(&m_backendAccess) =
                    Access::READ_RANDOM_ACCESS;
                break;
            case Access::APPEND:
                *const_cast<Access *>(&m_backendAccess) = Access::CREATE;
                break;
            case Access::READ_RANDOM_ACCESS:
            case Access::READ_WRITE:
            case Access::CREATE:
                break;
            }
        }
 
        m_encoding = encoding;
    }
 
public:
#if openPMD_HAVE_MPI
    AbstractIOHandler(std::string path, Access at, MPI_Comm)
        : directory{std::move(path)}, m_backendAccess{at}, m_frontendAccess{at}
    {}
#endif
    AbstractIOHandler(std::string path, Access at)
        : directory{std::move(path)}, m_backendAccess{at}, m_frontendAccess{at}
    {}
    virtual ~AbstractIOHandler() = default;
 
    AbstractIOHandler(AbstractIOHandler const &) = default;
    AbstractIOHandler(AbstractIOHandler &&) = default;
 
    AbstractIOHandler &operator=(AbstractIOHandler const &) = default;
    AbstractIOHandler &operator=(AbstractIOHandler &&) = default;
 
    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;
 
    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;
    internal::SeriesStatus m_seriesStatus = internal::SeriesStatus::Default;
    std::queue<IOTask> m_work;
    bool m_lastFlushSuccessful = false;
}; // AbstractIOHandler
 
} // namespace openPMD