Writable.hpp

/* Copyright 2017-2025 Fabian Koller, Axel Huebl, Franz Poeschel, Luca Fedeli
 *
 * 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/AbstractIOHandler.hpp"
 
#include <memory>
#include <string>
#include <vector>
 
// expose private and protected members for invasive testing
#ifndef OPENPMD_private
#define OPENPMD_private private:
#endif
 
namespace openPMD
{
namespace test
{
    struct TestHelper;
} // namespace test
class AbstractFilePosition;
class AbstractIOHandler;
struct ADIOS2FilePosition;
template <typename FilePositionType>
class AbstractIOHandlerImplCommon;
template <typename>
class Span;
class Series;
 
namespace internal
{
    class SharedAttributableData;
    class AttributableData;
    class SeriesData;
} // namespace internal
namespace detail
{
    class ADIOS2File;
}
 
namespace debug
{
    void printDirty(Series const &);
}

class Writable final
{
    friend class internal::SharedAttributableData;
    friend class internal::AttributableData;
    friend class internal::SeriesData;
    friend class Attributable;
    template <typename T_elem>
    friend class BaseRecord;
    template <typename T_elem>
    friend class BaseRecordInterface;
    template <typename T, typename T_key, typename T_container>
    friend class Container;
    friend class Iteration;
    friend class Mesh;
    friend class ParticleSpecies;
    friend class Series;
    friend class Record;
    friend class RecordComponent;
    friend class AbstractIOHandlerImpl;
    friend class ADIOS2IOHandlerImpl;
    friend class detail::ADIOS2File;
    friend class HDF5IOHandlerImpl;
    friend class ParallelHDF5IOHandlerImpl;
    template <typename>
    friend class AbstractIOHandlerImplCommon;
    friend class JSONIOHandlerImpl;
    friend struct test::TestHelper;
    friend std::string concrete_h5_file_position(Writable *);
    friend std::string concrete_bp1_file_position(Writable *);
    template <typename>
    friend class Span;
    friend void debug::printDirty(Series const &);
    friend struct Parameter<Operation::CREATE_DATASET>;
    friend struct Parameter<Operation::OPEN_DATASET>;
 
private:
    Writable(internal::AttributableData *);
 
public:
    ~Writable();
 
    Writable(Writable const &other) = delete;
    Writable(Writable &&other) = delete;
    Writable &operator=(Writable const &other) = delete;
    Writable &operator=(Writable &&other) = delete;

    template <bool flush_entire_series>
    void seriesFlush(std::string backendConfig = "{}");
 
    // clang-format off
OPENPMD_private
    // clang-format on
 
    template <bool flush_entire_series>
    void seriesFlush(internal::FlushParams const &);
    /*
     * These members need to be shared pointers since distinct instances of
     * Writable may share them.
     */
    std::shared_ptr<AbstractFilePosition> abstractFilePosition = nullptr;
    /*
     * shared_ptr since the IOHandler is shared by multiple Writable instances.
     * optional to make it possible to release the IOHandler, without first
     * having to destroy every single Writable.
     * unique_ptr since AbstractIOHandler is an abstract class.
     */
    std::shared_ptr<std::optional<std::unique_ptr<AbstractIOHandler>>>
        IOHandler = nullptr;
    /*
     * Link to the containing Attributable.
     * If multiple Attributables share the same Writable, then the creating one.
     * (See SharedAttributableData)
     */
    internal::AttributableData *attributable = nullptr;
    Writable *parent = nullptr;

    bool dirtySelf = true;
    bool dirtyRecursive = true;
    std::string ownKeyWithinParent;
    bool written = false;
};
} // namespace openPMD