register.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup perfc_register
 * @brief Implementation of the counter register perfc::Register
 * @copyright
 *   SPDX-FileCopyrightText: 2022-2024 European Southern Observatory (ESO)
 *
 *   SPDX-License-Identifier: LGPL-3.0-only
 *
 *
 * @defgroup perfc_register Counter Register
 * @brief Keep track of counters.
 * @ingroup perfc
 *
 * Main type is @ref perfc::Register.
 */
#ifndef PERFC_REGISTER_HPP_
#define PERFC_REGISTER_HPP_
#include <algorithm>
#include <cstdint>
#include <functional>
#include <mutex>
#include <variant>
#include <vector>
 
namespace perfc {
 
/**
 * Helper used when declaring counter types in perfc::Register.
 *
 * Example:
 * @code
 * // Specify the counter types that should be supported by our Register
 * using Counters = perfc::CounterTypes<perfc::CounterDouble,
 *                                      perfc::CounterU64>;
 * // Metadata using simple string for this example.
 * using Metadata = std::string;
 *
 * // Specify the counters as first template parameter.
 * using Register = perfc::Register<Counters, Metadata>;
 * @endcode
 *
 * @ingroup perfc_register
 * @headerfile <> <perfc/register.hpp>
 */
template <class... CounterType>
struct CounterTypes {
    using CounterVariant = std::variant<std::add_pointer_t<CounterType>...>;
};
 
/**
 * Simple type that provide synchronized access by holding a lock to T container.
 *
 * Accessing the locked object is peformed using pointer semantics.
 * @ingroup perfc_register
 */
template <class T, class Mutex>
class Locked {
public:
    using PointerType = std::add_pointer_t<T>;
    using ReferenceType = std::add_lvalue_reference_t<T>;
 
    /**
     * Construct by providing reference to object requiring synchronized access and the mutex
     * protecting it.
     *
     * @param t Object to obtain exclusive access to.
     * @param mutex Mutex protecting @a t.
     * @throws Exception originating from `Mutex::lock()` (typically `std::system_error`)
     */
    Locked(ReferenceType t, Mutex& mutex) : m_lock(mutex), m_ptr(&t) {
    }
 
    /**
     * Move constructs by taking owneship of internal state of @a other.
     * @param other Object to move from.
     */
    Locked(Locked&& other) noexcept : m_lock(std::move(other.m_lock)), m_ptr(other.m_ptr) {
        if (m_ptr) {
            other.m_ptr = nullptr;
        }
    }
 
    /**
     * Move constructs by taking owneship of internal state of @a other.
     * @param other Object to move from.
     */
    Locked& operator=(Locked&& other) noexcept {
        if (other.m_ptr) {
            m_ptr = other.m_ptr;
            m_lock = std::move(other.m_lock);
            other.m_ptr = nullptr;
        }
    }
 
    /**
     * @return Reference to underlying object.
     */
    PointerType Get() const noexcept {
        return m_ptr;
    }
    /**
     * @return Reference to underlying object.
     */
    ReferenceType operator*() const noexcept {
        return *m_ptr;
    }
    /**
     * @return Pointer to underlying object.
     */
    PointerType operator->() const noexcept {
        return m_ptr;
    }
 
    /**
     * @returns true if to underlying object is valid, false otherwise.
     */
    operator bool() const noexcept {
        return m_ptr != nullptr;
    }
 
    /**
     * Unlocks lock.
     *
     * @note There is no way to re-acquire lock after this.
     *
     * @post `Get() == nullptr`
     */
    void Unlock() noexcept {
        if (m_ptr) {
            m_ptr = nullptr;
            m_lock.unlock();
        }
    }
 
private:
    std::unique_lock<Mutex> m_lock;
    PointerType m_ptr;
};
 
template <class CounterType, class MetadataType, class Mutex>
class Register;
 
/**
 * RAII object to manage automatic deregistration.
 *
 * @thread_compatible
 * @ingroup perfc_register
 */
class ScopedRegistration {
public:
    ScopedRegistration() noexcept = default;
    ScopedRegistration(ScopedRegistration&&) noexcept = default;
    ScopedRegistration& operator=(ScopedRegistration&&) noexcept = default;
    ~ScopedRegistration() noexcept {
        Reset();
    }
    /**
     * @name Observers
     */
    /// @{
    /**
     * @returns true if it still manages a deregistration.
     */
    bool IsValid() const noexcept {
        return m_dereg != nullptr;
    }
    /**
     * @returns true if it still manages a deregistration.
     */
    operator bool() const noexcept {
        return m_dereg != nullptr;
    }
    /// @}
    /**
     * @name Modifiers
     */
    /// @{
    /**
     * Release ownership such that destroying object will not deregister counter.
     *
     * @post `IsValid() == false`
     */
    void Release() noexcept {
        m_dereg = nullptr;
    }
 
    /**
     * Deregisters counter if object is managing a registration.
     *
     * @post `IsValid() == false`
     */
    void Reset() noexcept {
        if (m_dereg) {
            m_dereg();
            Release();
        }
    }
    /**
     * Swaps two entries.
     *
     * @param other Exchanges ownership between `*this` and @c other.
     */
    void Swap(ScopedRegistration& other) noexcept;
    /// @}
protected:
    /**
     * @note From C++20 `std::function(function&&)` is noexcept
     */
    template <class CounterType, class MetadataType, class Mutex>
    friend class Register;
    ScopedRegistration(std::function<void()> dereg) : m_dereg(std::move(dereg)){};
 
private:
    std::function<void()> m_dereg = nullptr;
};
 
/**
 * Register of counter variants, used for example to facilitate discovery/monitoring.
 *
 * @note A counter is uniquely identified by its address. If a counter is moved it must first be
 * deregistered and then re-registered afterwards.
 *
 * To define a register for `double` and `std::uint64_t` and a `std::string` as metadata:
 *
 * @code
 * #include <string>
 * #include <perfc/perfc.hpp>
 *
 * using Counters = perfc::CounterTypes<perfc::CounterDouble,
 *                                      perfc::CounterU64>;
 * using Register = perfc::Register<Counters, std::string>;
 *
 * Register register;
 *
 * perfc::CounterDouble counter;
 * ScopedRegistration reg = register.Add(&counter, "metadata for counter");
 *
 * @endcode
 *
 * @thread_safe{All operations take a mutex lock and are thread safe if Mutex type provides mutual
 *   exclusion (i.e. not a null-opt mutex).
 *   Register::Lock() returns a pointer-like object that holds a lock, providing mutual exclusion.
 * }
 *
 * @headerfile <> <perfc/register.hpp>
 * @tparam CounterTypes Specifies which counter types can be registered using the helper
 *   perfc::CounterTypes.
 * @tparam TMetadata Specifies the metadata type used to associate each registered counter with.
 * Type requirements: *CopyConstructible* and *CopyAssignable*
 *
 * @tparam TMutex The mutex type to use, defaults to std::recursive_mutex.
 *
 * @ingroup perfc_register
 *
 */
template <class CounterTypes, class TMetadata, class TMutex = std::recursive_mutex>
class Register {
public:
    using Mutex = TMutex;
    using MetadataType = TMetadata;
    using CounterVariant = typename CounterTypes::CounterVariant;
 
    /**
     * Register entry representing the counter and associated metadata.
     */
    struct Entry {
        CounterVariant counter;
        MetadataType metadata;
    };
 
    using Container = std::vector<Entry>;
    using LockedContainer = Locked<Container, Mutex>;
    using LockedContainerConst = Locked<Container const, Mutex>;
 
    /**
     * @name Access container of counters thread safely
     * Obtains proxy object to counters that holds lock for synchronized access.
     *
     * Prefer a new nested scope to minimize lock duration:
     * @code
     * // Minimal scope for Lock()
     * {
     *   auto counters = register.Lock();
     *   for (auto const& counter : *counters) {
     *      ...
     *   }
     * }
     * @endcode
     * @throws Exception originating from `Mutex::lock()`
     */
    /// @{
    /** @returns locked access to container of counters. */
    LockedContainer Lock() {
        return LockedContainer(m_counters, m_mutex);
    }
    /** @returns locked access to *const* container of counters. */
    LockedContainerConst Lock() const {
        return LockedContainerConst(m_counters, m_mutex);
    }
    /// @}
 
    /**
     * @name Counter registration
     *
     * @note Manual de-registration with Register::Remove is not necessary unless ScopedRegistration
     * is released from managing the registration.
     */
    /// @{
    /**
     * Add a counter, identified by its *address*, together with metadata to the register.
     *
     * @pre counter must point to a valid CounterType object.
     *
     * @note The caller must ensure that the @a counter is deregistered before the counter is
     * deleted. The returned object aims to facilitate this.
     *
     * @note May invalidate iterators.
     *
     * @param counter Pointer to any of the supported counter types.
     * @param metadata A metadata object to be associated with @a counter.
     *
     * @returns Empty ScopedRegistration if counter already has been registered before.
     * @returns Non-empty RAII registration management object that automatically deregisters the
     * counter when destroyed (or manually released).
     *
     * @throw std::exception-derived exceptions originating from standard library.
     */
    [[nodiscard]] ScopedRegistration Add(CounterVariant counter, MetadataType metadata) {
        std::unique_lock<Mutex> lk(m_mutex);
        if (auto it = FindCounter(counter); it != std::end(m_counters)) {
            return ScopedRegistration();
        }
        ScopedRegistration entry([counter, this]() { this->Remove(counter); });
        m_counters.push_back({std::move(counter), std::move(metadata)});
        return entry;
    }
 
    /**
     * Remove counter from register.
     *
     * @note May invalidate iterators.
     * @return true if counter was found and erased, false otherwise.
     *
     * @throw std::exception-derived exceptions originating from standard library.
     */
    bool Remove(CounterVariant counter) {
        std::unique_lock<Mutex> lk(m_mutex);
 
        if (auto it = FindCounter(counter); it != std::end(m_counters)) {
            m_counters.erase(it);
            return true;
        }
        return false;
    }
    /// @}
 
private:
    typename Container::iterator FindCounter(CounterVariant counter) noexcept {
        return std::find_if(
            std::begin(m_counters), std::end(m_counters), [&counter](Entry const& entry) -> bool {
                return entry.counter == counter;
            });
    }
    mutable Mutex m_mutex;
    Container m_counters;
    std::uint64_t m_next_id;
};
 
}  // namespace perfc
#endif  // #ifndef PERFC_REGISTER_HPP_