manager.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup daq_config
 * @copyright (c) Copyright ESO 2022
 * All Rights Reserved
 * ESO (eso.org) is an Intergovernmental Organisation, and therefore special legal conditions apply.
 *
 * @brief daq::config::Manager and associated types.
 */
#ifndef DAQ_CONFIG_MANAGER_HPP
#define DAQ_CONFIG_MANAGER_HPP
 
#include <functional>
#include <iosfwd>
#include <optional>
#include <string>
#include <unordered_map>
 
#include <boost/algorithm/string/join.hpp>
#include <config-ng/ciiConfigApi.hpp>
#include <fmt/chrono.h>
#include <fmt/format.h>
#include <fmt/ostream.h>
#include <fmt/ranges.h>
 
#include <log4cplus/logger.h>
#include <log4cplus/loggingmacros.h>
#include <rad/cii/oldbTypes.hpp>
 
namespace daq::config {
 
/**
 * Configuration origins in descending priority.
 *
 * This is used to indicate from where a configuration parameter originates as well as its
 * configuration priority. Higher or equal priority (lower number) replace lower or equal priority
 * origins.
 */
enum class Origin {
    /**
     * Runtime change via e.g. request/reply command.
     */
    Runtime = 0,
    /**
     * Command line argument.
     */
    CommandLine,
    /**
     * Configuration file.
     */
    Configuration,
    /**
     * Environment variable.
     */
    EnvironmentVariable,
    /**
     * Built-in default value.
     */
    Default,
};
 
/**
 * Format Origin
 *
 * @param os output stream.
 * @param origin Origin to format.
 */
std::ostream& operator<<(std::ostream& os, Origin origin);
 
/**
 * Immutable information about a configuration attribute.
 */
struct Metadata {
    std::string canonical_name;
    std::string description;
};
 
/**
 * Extension point to allow adaptations from non-formattable configurations types.
 */
template <class T>
struct Formatter {
    static T const& Format(T const& t) {
        return t;
    }
};
 
template <class T>
struct Converter {
    static rad::cii::OldbType ToCii(T const& t) {
        return t;
    }
};
 
template <>
struct Converter<std::filesystem::path> {
    static rad::cii::OldbType ToCii(std::filesystem::path const& p) {
        return p.string();
    }
};
 
template <>
struct Converter<std::chrono::seconds> {
    static rad::cii::OldbType ToCii(std::chrono::seconds const& s) {
        return s.count();
    }
};
 
template <>
struct Converter<std::chrono::hours> {
    static rad::cii::OldbType ToCii(std::chrono::hours const& s) {
        return s.count();
    }
};
 
/**
 * @note: rad does not support vector of strings at the moment.
 */
template <>
struct Converter<std::vector<std::string>> {
    static rad::cii::OldbType ToCii(std::vector<std::string> const& s) {
        return boost::algorithm::join(s, ", ");
    }
};
 
/**
 * Mutable metadata about a configuration attribute that describes where a value comes from.
 */
struct OriginInfo {
    Origin origin = Origin::Default;
    /**
     * May include additional information like which configuration file was used.
     */
    std::string description = "";
};
 
/**
 * Format OriginInfo
 *
 * @param os output stream.
 * @param info OriginInfo to format.
 */
std::ostream& operator<<(std::ostream& os, OriginInfo const& info);
 
/**
 * Maintains the associativity of configuration attributes with metadata and value origin/priority.
 *
 * Main responsibilities:
 * - Maintain associativity between configuration attribute and metadata.
 * - Implement update logic in a way that configuration can only be overwritten if origin has a
 *   higher priority.
 *
 * Outside the scope:
 * - Implement parsing of various configuration origins.
 *
 * Manager works on the following assumptions and principles:
 *
 * - There is a 1:1 relationship between configuration class and manager.
 * - Configuration point identity is the member pointer to configuration class member variable.
 */
class Manager {
public:
    /**
     * Constructor
     *
     * @param logger Where to log to.
     */
    Manager(log4cplus::Logger const& logger) : m_logger(logger) {
    }
 
    /**
     * Registers a configuration parameter/attribute.
     *
     * @param ptr Configuration value pointer.
     * @param meta Metadata associated with attribute.
     * @throws std::exception if `ptr` has already been registered before or if allocation fails.
     */
    template <class AttrType>
    void Register(AttrType* ptr, Metadata const& meta);
 
    template <class AttrType, class Converter>
    void Register(AttrType* ptr, Metadata const& meta, Converter&& c);
 
    /**
     * Update configuration value taking into account the origin of the change.
     *
     * @param ptr Configuration value pointer.
     * @param value new configuration value.
     * @param origin Specifies origin of configuration value.
     * @returns true if configuration was changed false otherwise.
     * @throws std::exception if configuration member has not been registered before.
     */
    template <class AttrType, class T>
    bool Update(AttrType* ptr, T const& value, OriginInfo const& origin);
 
    /**
     * Describes current value.
     */
    template <class AttrType>
    struct CurrentValue {
        AttrType const& value;
        OriginInfo const& origin;
        Metadata const& metadata;
    };
 
    /**
     * CII representation of real value.
     */
    struct CiiValue {
        rad::cii::OldbType value;
        OriginInfo const& origin;
        Metadata const& metadata;
    };
 
    /**
     * Get current configuration value and associated metadata and origin
     * @param ptr Configuration member pointer.
     * @throws std::exception if configuration is unknown.
     */
    template <class AttrType>
    CurrentValue<AttrType> Get(AttrType* ptr) const;
 
    /**
     * Visit each registered parameter.
     *
     * @tparam Func Callable invocable with `func(cii_value)` where `cii_value` is const-reference
     * CiiValue.
     */
    template <class Func>
    void Visit(Func&& func) {
        for (auto const& entry : m_update) {
            auto value =
                CiiValue{entry.second.as_cii(), entry.second.origin, entry.second.metadata};
            func(value);
        }
    }
 
private:
    struct State {
        Metadata metadata;
        OriginInfo origin;
        std::function<rad::cii::OldbType()> as_cii;
    };
 
    log4cplus::Logger m_logger;
    // Type erased registered attributes
    std::unordered_map<void*, State> m_update;
};
 
template <class AttrType>
void Manager::Register(AttrType* ptr, Metadata const& m) {
    // Note pointer to member cannot be converted to void*, so we store the actual data pointer to
    // the instance provided in constructor. This works equally well as we only care about using
    // &C::member syntax as an identity.
    if (auto it = m_update.find(ptr); it != m_update.end()) {
        throw std::invalid_argument("Attribute already registered");
    }
    m_update.insert(
        std::make_pair(static_cast<void*>(ptr),
                       State{m, {}, [ptr]() { return Converter<AttrType>::ToCii(*ptr); }}));
    LOG4CPLUS_INFO(m_logger,
                   fmt::format("Registering configuration parameter <{}> with default value {}",
                               m.canonical_name,
                               Formatter<AttrType>::Format(*ptr)));
}
 
template <class AttrType, class Converter>
void Manager::Register(AttrType* ptr, Metadata const& m, Converter&& converter) {
    // Note pointer to member cannot be converted to void*, so we store the actual data pointer to
    // the instance provided in constructor. This works equally well as we only care about using
    // &C::member syntax as an identity.
    if (auto it = m_update.find(ptr); it != m_update.end()) {
        throw std::invalid_argument("Attribute already registered");
    }
    m_update.insert(
        std::make_pair(static_cast<void*>(ptr),
                       State{m, {}, [ptr, c = std::move(converter)]() { return c(*ptr); }}));
}
 
template <class AttrType>
typename Manager::template CurrentValue<AttrType> Manager::Get(AttrType* ptr) const {
    // Note pointer to member cannot be converted to void*, so we store the actual data pointer to
    // the instance provided in constructor. This works equally well as we only care about using
    // &C::member syntax as an identity.
    if (auto it = m_update.find(ptr); it == m_update.end()) {
        throw std::invalid_argument("Attribute not previously registered");
    } else {
        return CurrentValue<AttrType>{*ptr, it->second.origin, it->second.metadata};
    }
}
 
template <class AttrType, class T>
bool Manager::Update(AttrType* ptr, T const& value, OriginInfo const& new_origin) {
    if (auto it = m_update.find(ptr); it == m_update.end()) {
        throw std::invalid_argument("Attribute not previously registered");
    } else {
        // Keep old value and assign new before logging as T may not be the same as AttrType
        auto const& old_value = *ptr;
        auto const& new_value = value;
        auto const& meta = it->second.metadata;
        auto const& old_origin = it->second.origin;
 
        if (new_origin.origin <= it->second.origin.origin) {
            // Same or higher priority origin -> update!
            LOG4CPLUS_INFO(m_logger,
                           fmt::format("Updating configuration value for <{}> from "
                                       "old value {} ({}) -> new value {} ({})",
                                       meta.canonical_name,
                                       Formatter<AttrType>::Format(old_value),
                                       old_origin,
                                       Formatter<T>::Format(new_value),
                                       new_origin));
            it->second.origin = new_origin;
            *ptr = new_value;
            return true;
        } else {
            // Current value came from higher priority origin!
            LOG4CPLUS_DEBUG(m_logger,
                            fmt::format("Will _not_ update configuration value for <{}> from "
                                        "old value {} (origin {}) -> new value {} (origin {}) as "
                                        "current origin has higher priority",
                                        meta.canonical_name,
                                        Formatter<AttrType>::Format(old_value),
                                        old_origin,
                                        Formatter<T>::Format(new_value),
                                        new_origin));
            return false;
        }
    }
}
 
/**
 * Performs lookup of parameters in the form `root/node/leaf` relative to the provided node.
 *
 * @param selector Configuration selector in the format `node/node/param`
 * @param node The configuration node to select from.
 */
std::optional<std::reference_wrapper<elt::configng::CiiConfigInstanceNode const>>
GetParam(std::string const& selector, elt::configng::CiiConfigInstanceNode const& node);
 
/**
 * Performs lookup of parameters in the form `root/node/leaf` relative to the provided node.
 *
 * @param selector Configuration selector in the format `node/node/param`
 * @param node The configuration node to select from.
 * @tparam T Type convertion to perform.
 */
template <class T>
std::optional<T>
GetParamAs(std::string const& query, elt::configng::CiiConfigInstanceNode const& node) {
    if (auto opt = GetParam(query, node); opt.has_value()) {
        return opt->get().As<T>();
    }
    return {};
}
 
}  // namespace daq::config
 
template <>
struct fmt::formatter<daq::config::OriginInfo> : ostream_formatter {};
template <>
struct fmt::formatter<daq::config::Origin> : ostream_formatter {};
 
#endif  // DAQ_CONFIG_MANAGER_HPP