Line data    Source code

       1             : #ifndef FELIX_DATAPUBLISHER_H_
       2             : #define FELIX_DATAPUBLISHER_H_
       3             : 
       4             : #include <sys/uio.h>
       5             : 
       6             : #include <cstdint>
       7             : #include <functional>
       8             : #include <vector>
       9             : 
      10             : #include "elink.hpp"
      11             : #include "completion_table.hpp"
      12             : 
      13             : /**
      14             :  * Interface class to any publisher implemented by the network backend.
      15             :  */
      16          28 : class Publisher
      17             : {
      18             :     protected:
      19             :         size_t m_max_msg_size{};
      20             :         uint32_t m_max_iov_len{};
      21             :         /**
      22             :          * @brief Truncate the message if it is too large and returns status
      23             :          *
      24             :          * Changes iov to fit into message
      25             :          *
      26             :          * @param iov pointer to array of I/O vector
      27             :          * @param size number of entries in I/O vector array
      28             :          * @param status status byte
      29             :          * @return updated status byte
      30             :          */
      31             :         [[nodiscard]] std::uint8_t truncate_msg_if_too_large(iovec *iov, uint32_t &size, std::uint8_t status);
      32             : 
      33             :     public:
      34             :         using Callback = std::function<bool()>;
      35             : 
      36             :         enum Result
      37             :         {
      38             :             OK = 0,
      39             :             ERROR = 1,
      40             :             AGAIN = 2,
      41             :             PARTIAL = 3,
      42             :             ERROR_TOO_BIG = 4,
      43             :             NO_SUBSCRIBERS = 5,
      44             :             DECODING_ERROR = 7
      45             :         };
      46             : 
      47          24 :         virtual ~Publisher() = default;
      48             : 
      49             :         /** 
      50             :          * @brief advertise served e-links
      51             :          * @param elinks to advertise.
      52             :          * @return whether the operation was succesfull.
      53             :          */
      54             :         virtual bool declare(const std::vector<Elink> &elinks) = 0;
      55             : 
      56             :         /** 
      57             :          * @brief publish chunk.
      58             :          * @param fid e-link universal identifier.
      59             :          * @param iov pointer to array of I/O vector.
      60             :          * @param iovlen number of entries in I/O vector array.
      61             :          * @param bytes total message size in bytes.
      62             :          * @param block_addr address of block where the chunk starts (for zero-copy mode).
      63             :          * @param status felix-star status byte.
      64             :          * @return publisher-specific return code.
      65             :          */
      66             :         virtual Result publish(felix_id_t fid, iovec *iov, uint32_t iovlen, size_t bytes, uint32_t block_addr, std::uint8_t status) = 0;
      67             : 
      68             :         /** 
      69             :          * @brief publish chunk/message.
      70             :          * @param fid e-link universal identifier.
      71             :          * @param data pointer to the start of chunk/message to publish.
      72             :          * @param len size of message/chunk to publish.
      73             :          * @return publisher-specific return code.
      74             :          */
      75             :         virtual Result publish(felix_id_t fid, uint8_t *data, size_t len) = 0;
      76             : 
      77             :         /** 
      78             :          * @brief send right away (flush) the current buffer.
      79             :          * @param fid e-link universal identifier. All buffers containing data from
      80             :          * this e-link are flushed.
      81             :          * @return publisher-specific return code.
      82             :          */
      83             :         virtual Result flush(felix_id_t fid) = 0;
      84             : 
      85             :         /** 
      86             :          * @brief configure periodic callback e.g. the function used for polling input data.
      87             :          */
      88             :         virtual void set_periodic_callback(uint32_t period_us, Callback callback) = 0;
      89             : 
      90             :         /** 
      91             :          * @brief configure a callback with an asynchronous signal associated.
      92             :          */
      93             :         virtual void set_asynch_callback(Callback callback) = 0;
      94             : 
      95             :         /** 
      96             :          * @brief fire the signal associated to the asynchronous callback.
      97             :          */
      98             :         virtual void fire_asynch_callback() = 0;
      99             : 
     100             :         /** 
     101             :          * @brief zero-copy specific function to determine the DMA read pointer
     102             :          * on the basis of outstanding network transfers.
     103             :          * @return address in the DMA buffer.
     104             :          */
     105             :         virtual const CompletionTable* get_completion_table() = 0;
     106             : 
     107             :         // monitoring
     108             :         /**    
     109             :          * @return the number of available network buffers or similar resources.
     110             :          */
     111             :         virtual uint32_t get_resource_counter() = 0;
     112             : 
     113             :         /**    
     114             :          * @return the number of subscriptions.
     115             :          */
     116             :         virtual uint32_t get_subscription_number() = 0;
     117             : 
     118             :         /**    
     119             :          * @return the number of calls occurring when network resources become
     120             :          * availale after exhaustion.
     121             :          */
     122             :         virtual uint64_t get_resource_available_calls() = 0;
     123             : };
     124             : 
     125             : #endif /* FELIX_DATAPUBLISHER_H_ */