Line data Source code
1 : /* File: interface.h 2 : * This file is part of the program hardiocore 3 : * Program description : Abstract low level I/O removing direct hardware 4 : * implementation Copyright (C) 2018-2020 - Robin Passama (CNRS / LIRMM) 5 : * Clement Rebut (EPITA / LIRMM) Charles Villard (EPITA / LIRMM). All Right 6 : * reserved. 7 : * 8 : * This software is free software: you can redistribute it and/or modify 9 : * it under the terms of the CeCILL-C license as published by 10 : * the CEA CNRS INRIA, either version 1 11 : * of the License, or (at your option) any later version. 12 : * This software is distributed in the hope that it will be useful, 13 : * but WITHOUT ANY WARRANTY without even the implied warranty of 14 : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 : * CeCILL-C License for more details. 16 : * 17 : * You should have received a copy of the CeCILL-C License 18 : * along with this software. If not, it can be found on the official 19 : * website of the CeCILL licenses family (http://www.cecill.info/index.en.html). 20 : */ 21 : /** 22 : * @file common/interface.h 23 : * @author Robin Passama 24 : * @brief header file for Interface class 25 : * @date May 2025 26 : * @ingroup core 27 : */ 28 : #pragma once 29 : #include <stdexcept> 30 : #include <memory> 31 : #include <stdexcept> 32 : #include <pid/type_id.h> 33 : #include <pid/static_type_info.h> 34 : 35 : namespace hardio { 36 : class IOBoard; 37 : class Protocol; 38 : 39 : /** 40 : * @brief Represent an interface that allows direct or undirect access to 41 : * device(s). 42 : * @details An interface can be view as a point of connection allowing 43 : * discussion with a set of devices. An interface once instanciated can be 44 : * configured with a protocol that defines how dialogue takes place through this 45 : * interface. 46 : * @see ProtocolInterface 47 : * @see IO 48 : */ 49 : class Interface : public std::enable_shared_from_this<Interface> { 50 : public: 51 490 : Interface() = default; 52 490 : virtual ~Interface() = default; 53 : 54 : /** 55 : * @brief bind a protocol to this, meaning that the access point is used 56 : * through this protocol 57 : * @tparam T the type of protocol 58 : * @tparam Args, the variadic types of arguments for protocol creation 59 : * @param [in] args arguments passed to the object constructor 60 : * @return The reference to the protocol object created 61 : */ 62 : template <typename T, typename... Args> 63 200 : T& bind(Args&&... args) { 64 : static_assert( 65 : std::is_base_of_v<Protocol, T>, 66 : "Interface::bind: only a protocol can be bound to an interface"); 67 400 : auto prot = std::make_shared<T>(std::forward<Args>(args)...); 68 400 : std::string reason; 69 200 : if (not prot->can_bind_to(shared_from_this(), reason)) { 70 : throw std::runtime_error("Interface::bind: cannot bind protocol " + 71 4 : std::string(pid::type_name<T>()) + " to " + 72 8 : this->name() + " because " + reason); 73 : } 74 196 : if (static_cast<bool>(this->communication_layer())) { 75 : throw std::runtime_error( 76 : "Interface::bind: cannot bind protocol " + 77 3 : std::string(pid::type_name<T>()) + 78 6 : " because a protocol is already bound to " + this->name()); 79 : } 80 193 : if (not this->allow_binding(prot, reason)) { 81 : throw std::runtime_error("Interface::bind: cannot bind protocol " + 82 2 : std::string(pid::type_name<T>()) + " to " + 83 4 : this->name() + " because " + reason); 84 : } 85 191 : this->register_communication_layer(prot); 86 191 : communication_layer_ = prot; 87 191 : prot->uses(shared_from_this()); 88 382 : return *prot; 89 : } 90 : 91 : /** 92 : * @brief get a shared pointer to the interface 93 : * 94 : * @tparam T type of the interface 95 : * @return the std::shared_ptr<T> of this 96 : * @see ref() 97 : */ 98 : template <typename T> 99 84 : std::shared_ptr<T> ptr() { 100 84 : return std::static_pointer_cast<T>(shared_from_this()); 101 : } 102 : 103 : /** 104 : * @brief get a reference to this interface 105 : * 106 : * @tparam T the concrete type of this interface 107 : * @return the reference over this 108 : * @see ptr() 109 : */ 110 : template <typename T> 111 0 : T& ref() { 112 0 : return *static_cast<T*>(shared_from_this().get()); 113 : } 114 : 115 : /** 116 : * @brief get the name of the interface 117 : * 118 : * @return std::string the name 119 : */ 120 : virtual std::string name() const = 0; 121 : 122 : /** 123 : * @brief get the unique id of the interface 124 : * 125 : * @return std::string the id 126 : */ 127 : virtual std::string id() const = 0; 128 : 129 : /** 130 : * @brief initialise the interface (start using it) 131 : * 132 : * @param [out] reason the string explaining the problem if an error 133 : * occurred 134 : * @param [in] managed_thread true if user wants the threads to be 135 : * automatically managed for this interface false otherwise 136 : * @return true 137 : * @return false 138 : */ 139 : bool initialize(std::string& reason, bool managed_thread = true); 140 : 141 : /** 142 : * @brief stop using the interface 143 : * @see initialize() 144 : */ 145 : void finish(); 146 : 147 : /** 148 : * @brief Provide the communication layer used for all communications using 149 : * this interface 150 : * 151 : * @return const std::shared_ptr<Protocol>& the protocol configured for the 152 : * interface 153 : */ 154 : const std::shared_ptr<Protocol>& communication_layer() const; 155 : 156 : /** 157 : * @brief get id of the interface concrete type 158 : * 159 : * @return type id as a uint64_t 160 : */ 161 : virtual uint64_t type_id() const = 0; 162 : 163 : protected: 164 : /** 165 : * @brief Tell whether binding the given protocol to this is allowed 166 : * 167 : * @param [in] other the protocol to bind 168 : * @param [out] reason the string explaining the problem if an error 169 : * occurred 170 : * @return true if binding allowed, false otherwise 171 : */ 172 : virtual bool allow_binding(const std::shared_ptr<Protocol>& other, 173 : std::string& reason) const; 174 : 175 : /** 176 : * @brief Reaction to the binding of a protocol to this interface 177 : * @details this function is called after the protocol has been bound to 178 : * this interface. 179 : * @param [in] other the protocol to bind 180 : */ 181 : virtual void 182 : register_communication_layer(const std::shared_ptr<Protocol>& other); 183 : 184 : private: 185 : friend class IOBoard; 186 : std::shared_ptr<Protocol> communication_layer_; 187 : }; // namespace hardio 188 : 189 : /** 190 : * @brief Represents a virtual access point provided by a protocol. 191 : * 192 : * @tparam Prot the type of protocol providing this interface 193 : */ 194 : template <typename Prot> 195 : class ProtocolInterface : public Interface { 196 : static_assert( 197 : std::is_base_of_v<Protocol, Prot>, 198 : "ProtocolInterface: the template parameter must be a subclass " 199 : "of Protocol"); 200 : 201 : public: 202 341 : ProtocolInterface() = default; 203 341 : virtual ~ProtocolInterface() = default; 204 : 205 : using protocol_type = Prot; 206 : 207 : /** 208 : * @brief Get the potocol object providing this interface 209 : * 210 : * @return the protocol as a std::shared_ptr<Prot> 211 : */ 212 4023 : std::shared_ptr<Prot> protocol() const { 213 4023 : return protocol_.lock(); 214 : } 215 : 216 : /** 217 : * @brief get the id of the protocol interface type 218 : * @details an interface type id is defined by the type id of the 219 : * protocol 220 : * @return uint64_t identifying the protocol type 221 : */ 222 75 : virtual uint64_t type_id() const final { 223 75 : return protocol_.lock()->type_id(); 224 : } 225 : 226 : /** 227 : * @brief get the id of a protocol interface 228 : * @details by default, an interface ID is defined by the id used by 229 : * protocol. This function must be overridden any time the interface 230 : * provides additionnal identification information. 231 : * @return std::string identifying the interface 232 : */ 233 0 : std::string id() const override { 234 0 : return this->protocol()->id(); 235 : } 236 : 237 : /** 238 : * @brief get the protocol interface name, used for reporting information 239 : * @details by default, an interface name is defined by the name of the 240 : * protocol and its id. 241 : * @return std::string providing full reporting name of the interface. 242 : */ 243 2 : std::string name() const override { 244 2 : return protocol()->name() + "(" + id() + ")"; 245 : } 246 : 247 : private: 248 : std::weak_ptr<Prot> protocol_; 249 : friend class Protocol; 250 341 : void set_protocol(const std::shared_ptr<Prot>& prot) { 251 341 : protocol_ = prot; 252 341 : } 253 : }; 254 : 255 : } // namespace hardio