repositoryIf.hpp

Go to the documentation of this file.

 
#ifndef RTCTK_COMPONENTFRAMEWORK_REPOSITORYIF_HPP
#define RTCTK_COMPONENTFRAMEWORK_REPOSITORYIF_HPP
 
#include <rtctk/componentFramework/dataPointPath.hpp>
#include <rtctk/componentFramework/exceptions.hpp>
#include <rtctk/componentFramework/matrixBuffer.hpp>
#include <rtctk/componentFramework/matrixSpan.hpp>
#include <rtctk/config.hpp>
 
#include <taiclock/taiClock.hpp>
 
// FIXME: Add back when we start using CiiMatrix2D.
// #include <common/datatypes/ciiMatrix2D.hpp>
 
#include <gsl/span>
 
#include <any>
#include <chrono>
#include <cstdint>
#include <exception>
#include <functional>
#include <future>
#include <initializer_list>
#include <map>
#include <memory>
#include <optional>
#include <type_traits>
#include <vector>
 
namespace rtctk {
 
template <typename T>
using RtcVector = std::vector<T>;
 
// FIXME: Switch to using CII type for the matrix when we have ported to DevEnv 6.
// template <typename T>
// using RtcMatrix = elt::common::datatypes::CiiMatrix2D<T>;
template <typename T>
using RtcMatrix = componentFramework::MatrixBuffer<T>;
 
using RtcBool = bool;
using RtcInt8 = int8_t;
using RtcInt16 = int16_t;
using RtcInt32 = int32_t;
using RtcInt64 = int64_t;
using RtcUInt8 = uint8_t;
using RtcUInt16 = uint16_t;
using RtcUInt32 = uint32_t;
using RtcUInt64 = uint64_t;
using RtcFloat = float;
using RtcDouble = double;
using RtcString = std::string;
using RtcBinary = std::vector<std::byte>;
using RtcVectorBool = RtcVector<RtcBool>;
using RtcVectorInt8 = RtcVector<RtcInt8>;
using RtcVectorInt16 = RtcVector<RtcInt16>;
using RtcVectorInt32 = RtcVector<RtcInt32>;
using RtcVectorInt64 = RtcVector<RtcInt64>;
using RtcVectorUInt8 = RtcVector<RtcUInt8>;
using RtcVectorUInt16 = RtcVector<RtcUInt16>;
using RtcVectorUInt32 = RtcVector<RtcUInt32>;
using RtcVectorUInt64 = RtcVector<RtcUInt64>;
using RtcVectorFloat = RtcVector<RtcFloat>;
using RtcVectorDouble = RtcVector<RtcDouble>;
using RtcVectorString = RtcVector<RtcString>;
using RtcMatrixBool = RtcMatrix<RtcBool>;
using RtcMatrixInt8 = RtcMatrix<RtcInt8>;
using RtcMatrixInt16 = RtcMatrix<RtcInt16>;
using RtcMatrixInt32 = RtcMatrix<RtcInt32>;
using RtcMatrixInt64 = RtcMatrix<RtcInt64>;
using RtcMatrixUInt8 = RtcMatrix<RtcUInt8>;
using RtcMatrixUInt16 = RtcMatrix<RtcUInt16>;
using RtcMatrixUInt32 = RtcMatrix<RtcUInt32>;
using RtcMatrixUInt64 = RtcMatrix<RtcUInt64>;
using RtcMatrixFloat = RtcMatrix<RtcFloat>;
using RtcMatrixDouble = RtcMatrix<RtcDouble>;
using RtcMatrixString = RtcMatrix<RtcString>;
 
}  // namespace rtctk
 
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 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;
        };
 
        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&>;
 
            IteratorImpl() = default;
            IteratorImpl(const IteratorImpl& rhs) = default;
            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 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;
 
        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<const MetaData>> metadata = std::nullopt,
            const CallbackType& callback = nullptr);
 
        template <typename T>
        void WriteDataPoint(
            const DataPointPath& path,
            const T&& buffer,
            std::optional<std::reference_wrapper<const 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<const 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<const 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;
    };
 
    class RTCTK_API BatchResponse final {
    public:
        using ResponseList = std::vector<std::future<void>>;
 
        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>
    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);
 
protected:
    virtual BatchResponse ProcessRequests(const RequestList& requests) = 0;
 
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 
    // The following is part of the legacy API:
 
public:
    class [[deprecated("Use BatchRequest instead.")]] ReadRequest {
    public:
        class [[deprecated]] Parameters {
        public:
            Parameters() = default;
 
            explicit Parameters(const DataPointPath& path,
                                void* buffer,
                                const std::type_info& type,
                                const std::function<void()>& callback)
                : m_path(path), m_buffer(buffer), m_type(&type), m_callback(callback) {
            }
 
            [[deprecated]] inline const DataPointPath& GetPath() const {
                return m_path;
            };
            [[deprecated]] inline void* GetBuffer() const {
                return m_buffer;
            };
            [[deprecated]] inline const std::type_info& GetType() const {
                return *m_type;
            };
            [[deprecated]] inline const std::function<void()>& GetCallback() const {
                return m_callback;
            };
 
        private:
            DataPointPath m_path;
 
            void* m_buffer;
 
            const std::type_info* m_type;
 
            std::function<void()> m_callback;
        };
 
        template <typename T>
        [[deprecated("Use BatchRequest instead.")]] void Add(const DataPointPath& path, T& buffer);
        template <typename T, typename F>
        [[deprecated("Use BatchRequest instead.")]] void
        Add(const DataPointPath& path, T& buffer, F handler);
        [[deprecated("Use BatchRequest instead.")]] inline const std::vector<Parameters>&
        GetParams() const {
            return m_params;
        };
        [[deprecated("Use BatchRequest instead.")]] inline std::vector<Parameters>& GetParams() {
            return m_params;
        };
 
    private:
        std::vector<Parameters> m_params;
    };
 
    class [[deprecated("Use BatchRequest instead.")]] WriteRequest {
    public:
        class [[deprecated]] Parameters {
        public:
            Parameters() = default;
 
            explicit Parameters(const DataPointPath& path,
                                const void* buffer,
                                const std::type_info& type,
                                const std::function<void()>& callback)
                : m_path(path), m_buffer(buffer), m_type(&type), m_callback(callback) {
            }
 
            [[deprecated]] inline const DataPointPath& GetPath() const {
                return m_path;
            };
            [[deprecated]] inline const void* GetBuffer() const {
                return m_buffer;
            };
            [[deprecated]] inline const std::type_info& GetType() const {
                return *m_type;
            };
            [[deprecated]] inline const std::function<void()>& GetCallback() const {
                return m_callback;
            };
 
        private:
            DataPointPath m_path;
 
            const void* m_buffer;
 
            const std::type_info* m_type;
 
            std::function<void()> m_callback;
        };
 
        template <typename T>
        [[deprecated("Use BatchRequest instead.")]] void
        Add(const DataPointPath& path, const T& buffer);
        template <typename T, typename F>
        [[deprecated("Use BatchRequest instead.")]] void
        Add(const DataPointPath& path, const T& buffer, F handler);
        [[deprecated("Use BatchRequest instead.")]] inline const std::vector<Parameters>&
        GetParams() const {
            return m_params;
        };
        [[deprecated("Use BatchRequest instead.")]] inline std::vector<Parameters>& GetParams() {
            return m_params;
        };
 
    private:
        std::vector<Parameters> m_params;
    };
 
    class [[deprecated("Use BatchResponse instead.")]] Response {
    public:
        explicit Response(std::future<void>&& future) noexcept;
        Response(Response&& other) noexcept;
        Response& operator=(Response&& other) noexcept;
 
        [[deprecated("Use BatchResponse instead.")]] void Wait();
 
        [[deprecated("Use BatchResponse instead.")]] bool
        Wait(const std::chrono::microseconds& timeout);
 
    private:
        Response(const Response& other) = delete;
        Response& operator=(const Response& other) = delete;
 
        std::future<void> m_future;
    };
 
    [[deprecated("Use version that takes a default value instead.")]] virtual void
    CreateDataPoint(const DataPointPath& path, const std::type_info& type);
 
protected:
    [[deprecated("Use DeleteDataPoint instead.")]] virtual void
    DeleteDataPointLegacy(const DataPointPath& path);
 
    [[deprecated("Use GetDataPointType instead.")]] virtual const std::type_info&
    GetDataPointTypeLegacy(const DataPointPath& path) const;
 
    [[deprecated("Use GetDataPointSize instead.")]] virtual size_t
    GetDataPointSizeLegacy(const DataPointPath& path) const;
 
    [[deprecated("Use DataPointExists instead.")]] virtual bool
    DataPointExistsLegacy(const DataPointPath& path) const;
 
    [[deprecated("Use GetChildren instead.")]] virtual std::pair<PathList, PathList>
    GetChildrenLegacy(const DataPointPath& path) const;
 
public:
    [[deprecated("Use SendRequest instead.")]] virtual Response
    SendReadRequest(const ReadRequest& request) const;
 
    [[deprecated("Use SendRequest instead.")]] virtual Response
    SendWriteRequest(const WriteRequest& request);
 
#pragma GCC diagnostic pop
};
 
}  // namespace rtctk::componentFramework
 
#include <rtctk/componentFramework/repositoryIf.ipp>
 
#endif  // RTCTK_COMPONENTFRAMEWORK_REPOSITORYIF_HPP