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 <iosfwd>
#include <string>
#include <unordered_map>
 
#include <fmt/format.h>
#include <log4cplus/logger.h>
#include <log4cplus/loggingmacros.h>
 
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;
};
 
/**
 * 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 metaata.
 * - 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.
 */
template <class C>
class Manager {
public:
    /**
     * Constructor
     *
     * @param config Configuration instance to manage. Object must outlive Manager.
     * @param logger Where to log to.
     */
    Manager(C* config, log4cplus::Logger const& logger) : m_config(config), m_logger(logger) {
    }
 
    /**
     * Registers a configuration parameter/attribute.
     *
     * The pointer address of C acts as the identifer and that object must outlive Manager.
     *
     * @param ptr Configuration member 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 C::*ptr, Metadata const& meta);
 
    /**
     * Update configuration value taking into account the origin of the change.
     *
     * @param ptr Configuration member 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 C::*ptr, T const& value, OriginInfo const& origin);
 
    /**
     * Describes current value.
     */
    template <class AttrType>
    struct CurrentValue {
        AttrType const& 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 C::*ptr) const;
 
private:
    struct State {
        Metadata metadata;
        OriginInfo origin;
    };
    struct Key {};
 
    C* m_config;
    log4cplus::Logger m_logger;
    // Type erased registered attributes
    std::unordered_map<void*, State> m_update;
};
 
template <class C>
template <class AttrType>
void Manager<C>::Register(AttrType C::*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.
    void* vptr = &((*m_config).*ptr);
    if (auto it = m_update.find(vptr); it != m_update.end()) {
        throw std::invalid_argument("Attribute already registered");
    }
    m_update.insert(std::make_pair(vptr, State{m}));
}
 
template <class C>
template <class AttrType>
typename Manager<C>::template CurrentValue<AttrType> Manager<C>::Get(AttrType C::*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.
    void* vptr = &((*m_config).*ptr);
    if (auto it = m_update.find(vptr); it == m_update.end()) {
        throw std::invalid_argument("Attribute not previously registered");
    } else {
        return CurrentValue<AttrType>{(*m_config).*ptr, it->second.origin, it->second.metadata};
    }
}
 
template <class C>
template <class AttrType, class T>
bool Manager<C>::Update(AttrType C::*ptr, T const& value, OriginInfo const& new_origin) {
    void* vptr = &((*m_config).*ptr);
    if (auto it = m_update.find(vptr); 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 old_value = (*m_config).*ptr;
        ((*m_config).*ptr) = value;
        auto const& new_value = (*m_config).*ptr;
        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,
                                       old_value,
                                       old_origin,
                                       new_value,
                                       new_origin));
            it->second.origin = new_origin;
            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,
                                        old_value,
                                        old_origin,
                                        new_value,
                                        new_origin));
            return false;
        }
    }
}
 
}  // namespace daq::config
#endif  // DAQ_CONFIG_MANAGER_HPP