LCOV - code coverage report
Current view: top level - include/core/hardio/common - interface.h (source / functions) Hit Total Coverage
Test: hardiocore_coverage Lines: 31 35 88.6 %
Date: 2025-05-26 19:00:29 Functions: 74 152 48.7 %

          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

Generated by: LCOV version 1.16