Attributable.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/Error.hpp"
#include "openPMD/IO/AbstractIOHandler.hpp"
#include "openPMD/ThrowError.hpp"
#include "openPMD/auxiliary/OutOfRangeMsg.hpp"
#include "openPMD/backend/Attribute.hpp"
#include "openPMD/backend/Writable.hpp"
 
#include <cstddef>
#include <map>
#include <memory>
#include <optional>
#include <string>
#include <type_traits>
#include <vector>
 
// expose private and protected members for invasive testing
#ifndef OPENPMD_protected
#define OPENPMD_protected protected:
#endif
 
namespace openPMD
{
namespace traits
{
    template <typename T>
    struct GenerationPolicy;
} // namespace traits
class AbstractFilePosition;
class Attributable;
class Iteration;
class Series;
 
namespace internal
{
    class IterationData;
    class SeriesData;
    struct HomogenizeExtents;
 
    class SharedAttributableData
    {
        friend class openPMD::Attributable;
 
    public:
        SharedAttributableData(AttributableData *);
        SharedAttributableData(SharedAttributableData const &) = delete;
        SharedAttributableData(SharedAttributableData &&) = delete;
        virtual ~SharedAttributableData() = default;
 
        SharedAttributableData &
        operator=(SharedAttributableData const &) = delete;
        SharedAttributableData &operator=(SharedAttributableData &&) = delete;
 
        using A_MAP = std::map<std::string, Attribute>;
        Writable m_writable;
 
        A_MAP m_attributes;
    };
 
    /*
     * This is essentially a two-level pointer.
     *
     * 1. level: Our public API hands out handles to users that are (shared)
     *    pointers to an internal object (PIMPL).
     * 2. level: Multiple internal objects might refer to the same item in an
     *    openPMD file, e.g. to the same backend object.
     *    So, the internal object for an Attributable is a shared pointer to the
     *    unique object identifying this item.
     *
     * Such sharing occurs in the CustomHierarchy class where multiple
     * containers refer to the same group in the openPMD hierarchy
     * (container of groups, of meshes, of particle species, of datasets).
     * This might also become relevant for links as in HDF5 if we choose to
     * implement them.
     */
 
    class AttributableData : public std::shared_ptr<SharedAttributableData>
    {
        friend class openPMD::Attributable;
 
        using SharedData_t = std::shared_ptr<SharedAttributableData>;
        using A_MAP = SharedData_t::element_type::A_MAP;
 
    public:
        AttributableData();
        AttributableData(SharedAttributableData *);
        AttributableData(AttributableData const &) = delete;
        AttributableData(AttributableData &&) = delete;
        virtual ~AttributableData() = default;
 
        AttributableData &operator=(AttributableData const &) = delete;
        AttributableData &operator=(AttributableData &&) = delete;
 
        // Make copies explicit, only to be used under the conditions described
        // above
        void cloneFrom(AttributableData const &other);
 
        template <typename T>
        T asInternalCopyOf()
        {
            auto *self = dynamic_cast<typename T::Data_t *>(this);
            if (!self)
            {
                if constexpr (std::is_same_v<Series, T>)
                {
                    throw std::runtime_error(
                        "[Attributable::retrieveSeries] Error when trying to "
                        "retrieve the Series object. Note: An instance of the "
                        "Series object must still exist when flushing. A "
                        "common cause for this error is using a flush call on "
                        "a handle (e.g. `Iteration::seriesFlush()`) when the "
                        "original Series object has already gone out of "
                        "scope.");
                }
                else
                {
                    throw std::runtime_error(
 
                        "[AttributableData::asInternalCopyOf<T>] Error when "
                        "trying to retrieve a containing object. Note: An "
                        "instance of the Series object must still exist when "
                        "flushing. A common cause for this error is using a "
                        "flush call on a handle (e.g. "
                        "`Iteration::seriesFlush()`) when the original Series "
                        "object has already gone out of scope.");
                }
            }
            T res;
            res.setData(
                std::shared_ptr<typename T::Data_t>(self, [](auto const *) {}));
            return res;
        }
 
        inline auto attributes() -> A_MAP &
        {
            return operator*().m_attributes;
        }
        [[nodiscard]] inline auto attributes() const -> A_MAP const &
        {
            return operator*().m_attributes;
        }
        [[nodiscard]] inline auto readAttribute(std::string const &name) const
            -> Attribute const &
        {
            auto const &attr = attributes();
            if (auto it = attr.find(name); it != attr.end())
            {
                return it->second;
            }
            else
            {
                throw error::ReadError(
                    error::AffectedObject::Attribute,
                    error::Reason::NotFound,
                    std::nullopt,
                    "Not found: '" + name + "'.");
            }
        }
    };
 
    template <typename, typename>
    class BaseRecordData;
 
    class RecordComponentData;
 
    /*
     * Internal function to turn a handle into an owning handle that will keep
     * not only itself, but the entire Series alive. Works by hiding a copy of
     * the Series into the destructor lambda of the internal shared pointer. The
     * returned handle is entirely safe to use in just the same ways as a normal
     * handle, just the surrounding Series needs not be kept alive any more
     * since it is stored within the handle. By storing the Series in the
     * handle, not in the actual data, reference cycles are avoided.
     *
     * Instantiations for T exist for types RecordComponent,
     * MeshRecordComponent, Mesh, Record, ParticleSpecies, Iteration.
     */
    template <typename T>
    T &makeOwning(T &self, Series);
} // namespace internal
 
namespace debug
{
    void printDirty(Series const &);
}
 
class Attributable
{
    // @todo remove unnecessary friend (wew that sounds bitter)
    using A_MAP = std::map<std::string, Attribute>;
    friend Writable *getWritable(Attributable *);
    template <typename T_elem>
    friend class BaseRecord;
    template <typename T_elem>
    friend class BaseRecordInterface;
    template <typename, typename>
    friend class internal::BaseRecordData;
    template <typename T, typename T_key, typename T_container>
    friend class Container;
    template <typename T>
    friend struct traits::GenerationPolicy;
    friend class Iteration;
    friend class Series;
    friend class Writable;
    friend class internal::RecordComponentData;
    friend void debug::printDirty(Series const &);
    template <typename T>
    friend T &internal::makeOwning(T &self, Series);
    friend class StatefulSnapshotsContainer;
    friend class internal::AttributableData;
    friend class Snapshots;
    friend struct internal::HomogenizeExtents;
 
protected:
    // tag for internal constructor
    struct NoInit
    {};
 
    using Data_t = internal::AttributableData;
    std::shared_ptr<Data_t> m_attri;
 
public:
    Attributable();
    Attributable(NoInit) noexcept;
 
    virtual ~Attributable() = default;
 
    template <typename T>
    bool setAttribute(std::string const &key, T value);
    bool setAttribute(std::string const &key, char const value[]);
    Attribute getAttribute(std::string const &key) const;
 
    bool deleteAttribute(std::string const &key);
 
    std::vector<std::string> attributes() const;
    size_t numAttributes() const;
    bool containsAttribute(std::string const &key) const;
 
    std::string comment() const;
    Attributable &setComment(std::string const &comment);
 
    void seriesFlush(std::string backendConfig = "{}");
 
    void iterationFlush(std::string backendConfig = "{}");
 
    struct MyPath
    {
        std::string directory; 
        std::string seriesName; 
        std::string seriesExtension; 
        std::vector<std::string> group;
        Access access;
 
        std::string filePath() const;
        std::string openPMDPath() const;
    };
 
    MyPath myPath() const;
 
    void touch();
 
    [[nodiscard]] OpenpmdStandard openPMDStandard() const;
 
    // clang-format off
OPENPMD_protected
    // clang-format on
 
    Series retrieveSeries() const;
 
    [[nodiscard]] auto containingIteration() const -> std::pair<
        std::optional<internal::IterationData const *>,
        internal::SeriesData const *>;
    auto containingIteration() -> std::
        pair<std::optional<internal::IterationData *>, internal::SeriesData *>;
    template <bool flush_entire_series>
    void seriesFlush_impl(internal::FlushParams const &);
 
    void flushAttributes(internal::FlushParams const &);
 
    enum ReadMode
    {
        IgnoreExisting,
        OverrideExisting,
        FullyReread
    };
    void readAttributes(ReadMode);
 
    template <typename T>
    T readFloatingpoint(std::string const &key) const;
    template <typename T>
    std::vector<T> readVectorFloatingpoint(std::string const &key) const;
 
    /* views into the resources held by m_writable
     * purely for convenience so code that uses these does not have to go
     * through m_writable-> */
    AbstractIOHandler *IOHandler()
    {
        return const_cast<AbstractIOHandler *>(
            static_cast<Attributable const *>(this)->IOHandler());
    }
    AbstractIOHandler const *IOHandler() const
    {
        auto &opt = writable().IOHandler;
        if (!opt || !opt->has_value())
        {
            return nullptr;
        }
        return &*opt->value();
    }
    Writable *&parent()
    {
        return writable().parent;
    }
    Writable const *parent() const
    {
        return writable().parent;
    }
    Writable &writable()
    {
        return (*m_attri)->m_writable;
    }
    Writable const &writable() const
    {
        return (*m_attri)->m_writable;
    }
 
    inline void setData(std::shared_ptr<internal::AttributableData> attri)
    {
        m_attri = std::move(attri);
    }
 
    inline internal::SharedAttributableData &get()
    {
        return **m_attri;
    }
    inline internal::SharedAttributableData const &get() const
    {
        return **m_attri;
    }
 
    bool dirty() const
    {
        return writable().dirtySelf;
    }
    bool dirtyRecursive() const
    {
        return writable().dirtyRecursive;
    }
    void setDirty(bool dirty_in)
    {
        auto &w = writable();
        w.dirtySelf = dirty_in;
        setDirtyRecursive(dirty_in);
    }
    /* Amortized O(1) if dirty_in is true, else O(1).
     *
     * Must be used carefully with `dirty_in == false` since it is assumed that
     * all children are not dirty.
     *
     * Invariant of dirtyRecursive:
     *   this->dirtyRecursive implies parent->dirtyRecursive.
     *
     * Hence:
     *
     * * If dirty_in is true: This needs only go up far enough until a parent is
     *   found that itself is dirtyRecursive.
     * * If dirty_in is false: Only sets `this` to `dirtyRecursive == false`.
     *   The caller must ensure that the invariant holds (e.g. clearing
     *   everything during flushing or reading logic).
     */
    void setDirtyRecursive(bool dirty_in)
    {
        auto &w = writable();
        w.dirtyRecursive = dirty_in;
        if (dirty_in)
        {
            auto current = w.parent;
            while (current && !current->dirtyRecursive)
            {
                current->dirtyRecursive = true;
                current = current->parent;
            }
        }
    }
    bool written() const
    {
        return writable().written;
    }
    enum class EnqueueAsynchronously : bool
    {
        Yes,
        No
    };
    /*
     * setWritten() will take effect immediately.
     * But it might additionally be necessary in some situations to enqueue a
     * SET_WRITTEN task to the backend:
     * A single flush() operation might encompass different Iterations. In
     * file-based Iteration encoding, some objects must be written to every
     * single file, thus their `written` flag must be restored to `false` for
     * each Iteration. When flushing multiple Iterations at once, this must
     * happen as an asynchronous IO task.
     */
    void setWritten(bool val, EnqueueAsynchronously);
 
private:
    virtual void linkHierarchy(Writable &w);
}; // Attributable
 
// note: we explicitly instantiate Attributable::setAttributeImpl for all T in
// Datatype in Attributable.cpp
template <typename T>
inline bool Attributable::setAttribute(std::string const &key, T value)
{
    auto &attri = get();
    if (IOHandler() &&
        IOHandler()->m_seriesStatus == internal::SeriesStatus::Default &&
        Access::READ_ONLY == IOHandler()->m_frontendAccess)
    {
        auxiliary::OutOfRangeMsg const out_of_range_msg(
            "Attribute", "can not be set (read-only).");
        error::throwNoSuchAttribute(out_of_range_msg(key));
    }
 
    setDirty(true);
    auto it = attri.m_attributes.lower_bound(key);
    if (it != attri.m_attributes.end() &&
        !attri.m_attributes.key_comp()(key, it->first))
    {
        // key already exists in map, just replace the value
        it->second = Attribute(std::move(value));
        return true;
    }
    else
    {
        // emplace a new map element for an unknown key
        attri.m_attributes.emplace_hint(
            it, std::make_pair(key, Attribute(std::move(value))));
        return false;
    }
}
 
inline bool
Attributable::setAttribute(std::string const &key, char const value[])
{
    return this->setAttribute(key, std::string(value));
}
 
template <typename T>
inline T Attributable::readFloatingpoint(std::string const &key) const
{
    static_assert(
        std::is_floating_point<T>::value,
        "Type of attribute must be floating point");
 
    return getAttribute(key).get<T>();
}
 
template <typename T>
inline std::vector<T>
Attributable::readVectorFloatingpoint(std::string const &key) const
{
    static_assert(
        std::is_floating_point<T>::value,
        "Type of attribute must be floating point");
 
    return getAttribute(key).get<std::vector<T> >();
}
} // namespace openPMD