repositoryIf.hpp

Go to the documentation of this file.

 
#ifndef RTCTK_COMPONENTFRAMEWORK_REPOSITORYIF_HPP
#define RTCTK_COMPONENTFRAMEWORK_REPOSITORYIF_HPP
 
#include <any>
#include <chrono>
#include <exception>
#include <functional>
#include <future>
#include <initializer_list>
#include <map>
#include <memory>
#include <optional>
#include <type_traits>
#include <vector>
 
#include <gsl/span>
 
#include <taiclock/taiClock.hpp>
 
#include <rtctk/basicTypes.hpp>
#include <rtctk/config.hpp>
 
#include <rtctk/componentFramework/dataPointPath.hpp>
#include <rtctk/componentFramework/exceptions.hpp>
#include <rtctk/componentFramework/matrixBuffer.hpp>
#include <rtctk/componentFramework/matrixSpan.hpp>
 
namespace rtctk::componentFramework {

class RTCTK_API RepositoryIf {
protected:
    using RequestList = std::vector<std::any>;
 
public:
    using PathList = std::vector<DataPointPath>;
    using Clock = taiclock::TaiClock;
    using Timestamp = Clock::time_point;

    using CallbackType = std::function<void(const DataPointPath&)>;
 
    RepositoryIf() = default;
    virtual ~RepositoryIf() = default;
 
    class RTCTK_API ServiceFailure : public RtctkException {
        using RtctkException::RtctkException;
    };
 
    class RTCTK_API UnsupportedType : public UnsupportedTypeException {
        using UnsupportedTypeException::UnsupportedTypeException;
    };
 
    class RTCTK_API IncompatibleType : public RtctkException {
        using RtctkException::RtctkException;
    };
 
    class RTCTK_API DataPointPathNotAbsolute : public RtctkException {
        using RtctkException::RtctkException;
    };
 
    class RTCTK_API DataPointDoesNotExist : public RtctkException {
        using RtctkException::RtctkException;
    };
 
    class RTCTK_API DataPointAlreadyExists : public RtctkException {
        using RtctkException::RtctkException;
    };
 
    class RTCTK_API BufferTooSmall : public rtctk::componentFramework::BufferTooSmall {
    public:
        using rtctk::componentFramework::BufferTooSmall::BufferTooSmall;
    };
 
    class RTCTK_API AccessOutOfBounds : public RtctkException {
        using RtctkException::RtctkException;
    };
 
    class RTCTK_API OperationNotAllowed : public RtctkException {
        using RtctkException::RtctkException;
    };
 
    class RTCTK_API MultipleRequestsFailed : public RtctkException {
    public:
        enum class Status : uint8_t { Success, Failed, Skipped };
 
        struct Info {
            Status status;
            std::exception_ptr exception;
        };
 
        explicit MultipleRequestsFailed(const std::vector<Info>& info);
        const std::vector<Info>& GetInfo() const;
 
    private:
        static RTCTK_LOCAL std::string InfoToString(const std::vector<Info>& info);
        // Note that using shared_ptr makes the exception's copy constructor noexcept.
        std::shared_ptr<std::vector<Info>> m_info;
    };

    class RTCTK_API MetaData final {
    public:
        class RTCTK_API ConstValueProxy final {
        public:
            ConstValueProxy() = delete;
            ConstValueProxy(const ConstValueProxy& rhs) = default;
            ConstValueProxy(ConstValueProxy&& rhs) = default;
            ~ConstValueProxy() = default;

            inline bool HasValue() const noexcept;

            const std::type_info& GetValueType() const noexcept;

            inline operator const std::any&() const;

            template <typename T>
            const T& Cast() const;
 
        private:
            friend MetaData;
 
            RTCTK_LOCAL inline ConstValueProxy(const std::string& key, const std::any& value);

            const std::string& m_key;

            const std::any& m_value;
        };

        class RTCTK_API ValueProxy final {
        public:
            ValueProxy() = delete;
            ValueProxy(const ValueProxy& rhs) = default;
            ValueProxy(ValueProxy&& rhs) = default;
            ~ValueProxy() = default;

            inline bool HasValue() const noexcept;

            const std::type_info& GetValueType() const noexcept;

            inline operator const std::any&() const;

            template <typename T>
            T& Cast();

            template <typename T>
            const T& Cast() const;

            ValueProxy& operator=(const ValueProxy& rhs);

            template <typename T>
            ValueProxy& operator=(T&& rhs);

            inline void Reset() noexcept;
 
        private:
            friend MetaData;
 
            RTCTK_LOCAL inline ValueProxy(const std::string& key, std::any& value);

            const std::string& m_key;

            std::any& m_value;
        };
 
    private:
        using MapType = std::map<std::string, std::any>;

        template <typename MapIterType, typename ProxyType>
        class RTCTK_LOCAL IteratorImpl {
        public:
            using iterator_concept = std::bidirectional_iterator_tag;
            using iterator_category = std::bidirectional_iterator_tag;
            using value_type = std::pair<const MapType::key_type&, ProxyType>;
            using difference_type = MapType::difference_type;
            using pointer = void;
            using reference = std::conditional_t<std::is_same_v<ProxyType, ConstValueProxy>,
                                                 const value_type&,
                                                 value_type&>;
 
            // uninitMemberVar: The members will be initialised correctly.
            // noExplicitConstructor: The constructors should be called implicitly for an iterator.
            // cppcheck-suppress uninitMemberVar
            IteratorImpl() = default;
            // cppcheck-suppress [uninitMemberVar, noExplicitConstructor]
            IteratorImpl(const IteratorImpl& rhs) = default;
            // cppcheck-suppress [uninitMemberVar, noExplicitConstructor]
            IteratorImpl(IteratorImpl&& rhs) noexcept = default;
            ~IteratorImpl() = default;
            IteratorImpl& operator=(const IteratorImpl& rhs) = default;
            IteratorImpl& operator=(IteratorImpl&& rhs) noexcept = default;
            value_type& operator*();
            value_type operator*() const;
            value_type* operator->();
            const value_type* operator->() const;
            IteratorImpl& operator++();
            IteratorImpl operator++(int);
            IteratorImpl& operator--();
            IteratorImpl operator--(int);
            bool operator==(const IteratorImpl& rhs) const;
            bool operator!=(const IteratorImpl& rhs) const;
 
        protected:
            RTCTK_LOCAL explicit IteratorImpl(MapIterType&& iter);
 
            MapIterType m_iterator;  // The underlying map iterator.

            std::optional<value_type> m_pair;
        };
 
    public:
        class RTCTK_API Iterator final : public IteratorImpl<MapType::iterator, ValueProxy> {
        private:
            friend MetaData;
            RTCTK_LOCAL inline Iterator(MapType::iterator&& iter);
        };

        class RTCTK_API ConstIterator final
            : public IteratorImpl<MapType::const_iterator, ConstValueProxy> {
        private:
            friend MetaData;
            RTCTK_LOCAL inline ConstIterator(MapType::const_iterator&& iter);
        };

        class RTCTK_API ReverseIterator final
            : public IteratorImpl<MapType::reverse_iterator, ValueProxy> {
        private:
            friend MetaData;
            RTCTK_LOCAL inline ReverseIterator(MapType::reverse_iterator&& iter);
        };

        class RTCTK_API ConstReverseIterator final
            : public IteratorImpl<MapType::const_reverse_iterator, ConstValueProxy> {
        private:
            friend MetaData;
            RTCTK_LOCAL inline ConstReverseIterator(MapType::const_reverse_iterator&& iter);
        };

        class RTCTK_API KeyDoesNotExist : public RtctkException {
        public:
            explicit KeyDoesNotExist(const std::string& key);
            const std::string& GetKey() const;
 
        private:
            std::shared_ptr<std::string> m_key;
        };

        class RTCTK_API KeyAlreadyExists : public RtctkException {
        public:
            explicit KeyAlreadyExists(const std::string& key);
            const std::string& GetKey() const;
 
        private:
            std::shared_ptr<std::string> m_key;
        };

        class RTCTK_API TypeMismatch : public RtctkException {
        public:
            explicit TypeMismatch(const std::string& key,
                                  const std::type_info& type_used,
                                  const std::type_info& type_expected);
            const std::string& GetKey() const;
            const std::type_info& GetTypeUsed() const;
            const std::type_info& GetTypeExpected() const;
 
        private:
            struct RTCTK_LOCAL Attributes {
                inline Attributes(const std::string& key,
                                  const std::type_info& type_used,
                                  const std::type_info& type_expected);
                std::string m_key;
                std::reference_wrapper<const std::type_info> m_type_used;
                std::reference_wrapper<const std::type_info> m_type_expected;
            };
            // Note that using shared_ptr makes the exception's copy constructor noexcept.
            std::shared_ptr<Attributes> m_attribs;
        };

        class RTCTK_API UnsupportedType : public UnsupportedTypeException {
        public:
            using UnsupportedTypeException::UnsupportedTypeException;
        };
 
        MetaData() = default;
        MetaData(const MetaData& rhs) = default;
        MetaData(MetaData&& rhs) = default;
        MetaData(std::initializer_list<std::pair<std::string, std::any>> init_list);
        ~MetaData() = default;
        MetaData& operator=(const MetaData& rhs) = default;
        MetaData& operator=(MetaData&& rhs) = default;

        inline bool Empty() const;

        inline size_t GetSize() const noexcept;

        inline bool Contains(const std::string& key) const;

        ValueProxy Insert(const std::string& key);

        ValueProxy Insert(std::string&& key);

        template <typename T>
        auto& Insert(const std::string& key, T&& value);

        template <typename T>
        auto& Insert(std::string&& key, T&& value);

        bool Remove(const std::string& key);

        ValueProxy operator[](const std::string& key);

        ValueProxy operator[](std::string&& key);

        ConstValueProxy operator[](const std::string& key) const;

        void Merge(const MetaData& source);

        void Merge(MetaData&& source);
 
        // The following methods are for STL compatibility and therefore must use lower case.
        // NOLINTBEGIN(readability-identifier-naming)
        inline Iterator begin();

        inline ConstIterator begin() const;

        inline ConstIterator cbegin() const noexcept;

        inline Iterator end();

        inline ConstIterator end() const;

        inline ConstIterator cend() const noexcept;

        inline ReverseIterator rbegin();

        inline ConstReverseIterator rbegin() const;

        inline ConstReverseIterator crbegin() const noexcept;

        inline ReverseIterator rend();

        inline ConstReverseIterator rend() const;

        inline ConstReverseIterator crend() const noexcept;
        // NOLINTEND(readability-identifier-naming)
 
    private:
        friend RepositoryIf;
 
        // We are using an std::map because it is often faster to copy/manipulate for a small number
        // of keys compared to std::unordered_map.
        MapType m_metadata;  
    };

    class RTCTK_API BatchRequest {
    public:
        virtual ~BatchRequest() = default;
 
        // Due to Doxygen limitations the multi-line @async_exceptions command cannot have the '*'
        // character on each line.
        template <typename T>
        void CreateDataPoint(
            const DataPointPath& path,
            const T& initial_value,
            std::optional<std::reference_wrapper<const MetaData>> metadata = std::nullopt,
            const CallbackType& callback = nullptr);

        template <typename T>
        void CreateDataPoint(
            const DataPointPath& path,
            const T&& initial_value,
            std::optional<std::reference_wrapper<const MetaData>> metadata = std::nullopt,
            const CallbackType& callback = nullptr) = delete;
 
        void DeleteDataPoint(const DataPointPath& path, const CallbackType& callback = nullptr);
 
        void DataPointExists(const DataPointPath& path,
                             bool& result,
                             const CallbackType& callback = nullptr) const;

        void GetChildren(const DataPointPath& path,
                         std::pair<PathList, PathList>& result,
                         bool recurse = false,
                         const CallbackType& callback = nullptr) const;

        void GetChildren(const DataPointPath& path,
                         std::pair<PathList, PathList>&& result,
                         bool recurse = false,
                         const CallbackType& callback = nullptr) const = delete;
 
        template <typename T>
        void ReadDataPoint(const DataPointPath& path,
                           T& buffer,
                           std::optional<std::reference_wrapper<MetaData>> metadata = std::nullopt,
                           const CallbackType& callback = nullptr) const;

        template <typename T>
        void ReadDataPoint(const DataPointPath& path,
                           T&& buffer,
                           std::optional<std::reference_wrapper<MetaData>> metadata = std::nullopt,
                           const CallbackType& callback = nullptr) const = delete;

        template <typename T>
        void WriteDataPoint(const DataPointPath& path,
                            const T& buffer,
                            std::optional<std::reference_wrapper<MetaData>> metadata = std::nullopt,
                            const CallbackType& callback = nullptr);

        template <typename T>
        void WriteDataPoint(const DataPointPath& path,
                            const T&& buffer,
                            std::optional<std::reference_wrapper<MetaData>> metadata = std::nullopt,
                            const CallbackType& callback = nullptr) = delete;

        template <typename T>
        void PartialReadDataPoint(
            const DataPointPath& path,
            T& buffer,
            size_t first,
            size_t last,
            size_t d_first,
            std::optional<std::reference_wrapper<MetaData>> metadata = std::nullopt,
            const CallbackType& callback = nullptr) const;

        template <typename T>
        void PartialReadDataPoint(
            const DataPointPath& path,
            T&& buffer,
            size_t first,
            size_t last,
            size_t d_first,
            std::optional<std::reference_wrapper<MetaData>> metadata = std::nullopt,
            const CallbackType& callback = nullptr) const = delete;

        template <typename T>
        void PartialWriteDataPoint(
            const DataPointPath& path,
            const T& buffer,
            size_t first,
            size_t last,
            size_t d_first,
            std::optional<std::reference_wrapper<MetaData>> metadata = std::nullopt,
            const CallbackType& callback = nullptr);

        template <typename T>
        void PartialWriteDataPoint(
            const DataPointPath& path,
            const T&& buffer,
            size_t first,
            size_t last,
            size_t d_first,
            std::optional<std::reference_wrapper<MetaData>> metadata = std::nullopt,
            const CallbackType& callback = nullptr) = delete;
 
        void ReadMetaData(const DataPointPath& path,
                          MetaData& metadata,
                          const CallbackType& callback = nullptr) const;

        void ReadMetaData(const DataPointPath& path,
                          MetaData&& metadata,
                          const CallbackType& callback = nullptr) const = delete;
 
        void WriteMetaData(const DataPointPath& path,
                           const MetaData& metadata,
                           const CallbackType& callback = nullptr);
 
        void CreateSymlink(const DataPointPath& dp,
                           const DataPointPath& link,
                           const CallbackType& callback = nullptr);
 
        void UpdateSymlink(const DataPointPath& dp,
                           const DataPointPath& link,
                           const CallbackType& callback = nullptr);
 
    protected:
        friend RepositoryIf;
        mutable RequestList m_requests;
 
    private:
        template <typename T>
        void ReadDataPointImpl(const DataPointPath& path,
                               T& buffer,
                               std::optional<std::reference_wrapper<MetaData>> metadata,
                               const CallbackType& callback) const;
 
        template <typename T>
        void PartialReadDataPointImpl(const DataPointPath& path,
                                      T& buffer,
                                      size_t first,
                                      size_t last,
                                      size_t d_first,
                                      std::optional<std::reference_wrapper<MetaData>> metadata,
                                      const CallbackType& callback) const;
    };
 
    class RTCTK_API BatchResponse final {
    public:
        using ResponseList = std::vector<std::future<void>>;
 
        explicit BatchResponse(ResponseList futures);
 
        // await all
        void Wait();
 
        template <typename Rep, typename Period>
        bool WaitFor(const std::chrono::duration<Rep, Period>& timeout);
 
        template <typename Clk, typename Duration>
        bool WaitUntil(const std::chrono::time_point<Clk, Duration>& timeout);
 
    protected:
        ResponseList m_responses;
    };
 
    BatchResponse SendRequest(const BatchRequest& request);
    BatchResponse SendRequest(const BatchRequest& request) const;
 
    // The following are synchronous convenience methods.

    template <typename T>
    void CreateDataPoint(const DataPointPath& path);

    template <typename T>
    void CreateDataPoint(const DataPointPath& path, const T& initial_value);
 
    void CreateDataPoint(const DataPointPath& path, const char* initial_value);

    void DeleteDataPoint(const DataPointPath& path, bool recurse = false);

    const std::type_info& GetDataPointType(const DataPointPath& path) const;

    size_t GetDataPointSize(const DataPointPath& path) const;

    RtcVectorUInt64 GetDataPointShape(const DataPointPath& path) const;

    bool DataPointExists(const DataPointPath& path) const;

    std::pair<PathList, PathList>
    GetChildren(const DataPointPath& path, bool recurse = false) const;

    template <typename T>
    T GetDataPoint(const DataPointPath& path) const;

    template <typename T>
    std::optional<T> TryGetDataPoint(const DataPointPath& path) const;

    template <typename T>
    void SetDataPoint(const DataPointPath& path, const T& value);
 
    void SetDataPoint(const DataPointPath& path, const char* value);

    template <typename T>
    void ReadDataPoint(const DataPointPath& path, T& buffer) const;

    template <typename T>
    void WriteDataPoint(const DataPointPath& path, const T& buffer);
 
    void WriteDataPoint(const DataPointPath& path, const char* buffer);
 
    template <typename... T>
    void WriteDataPoints(const T&... args);
 
    template <typename... T>
    void ReadDataPoints(T&... args) const;

    static const std::type_info& StringToType(const std::string& arg);

    static std::string TypeToString(const std::type_info& arg);

    static std::any MakeAnyBuffer(const MetaData& metadata);
 
protected:
    virtual BatchResponse ProcessRequests(const RequestList& requests) = 0;
};
 
}  // namespace rtctk::componentFramework
 
#include <rtctk/componentFramework/repositoryIf.ipp>
 
#endif  // RTCTK_COMPONENTFRAMEWORK_REPOSITORYIF_HPP