include/private/engine.hpp

   1 /*
   2    Copyright (c) 2018-2019 Nokia.
   3
   4    Licensed under the Apache License, Version 2.0 (the "License");
   5    you may not use this file except in compliance with the License.
   6    You may obtain a copy of the License at
   7
   8        http://www.apache.org/licenses/LICENSE-2.0
   9
  10    Unless required by applicable law or agreed to in writing, software
  11    distributed under the License is distributed on an "AS IS" BASIS,
  12    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13    See the License for the specific language governing permissions and
  14    limitations under the License.
  15 */
  16
  17 /*
  18  * This source code is part of the near-RT RIC (RAN Intelligent Controller)
  19  * platform project (RICP).
  20 */
  21
  22 #ifndef SHAREDDATALAYER_ENGINE_HPP_
  23 #define SHAREDDATALAYER_ENGINE_HPP_
  24
  25 #include <functional>
  26 #include "private/timer.hpp"
  27
  28 namespace shareddatalayer
  29 {
  30     class FileDescriptor;
  31
  32     /**
  33      * Engine provides the basic services needed by asynchronous library:
  34      * - File descriptor monitoring
  35      * - Timer monitoring
  36      * - Callback queue
  37      */
  38     class Engine
  39     {
  40         friend class Timer;
  41
  42     public:
  43         Engine() = default;
  44
  45         virtual ~Engine() = default;
  46
  47         virtual int fd() const = 0;
  48
  49         virtual void handleEvents() = 0;
  50
  51         /** There is data to read. */
  52         static const unsigned int EVENT_IN;
  53
  54         /** Writing is now possible. */
  55         static const unsigned int EVENT_OUT;
  56
  57         /** Error condition. */
  58         static const unsigned int EVENT_ERR;
  59
  60         /** Hang up. */
  61         static const unsigned int EVENT_HUP;
  62
  63         /**
  64          * Event handler function type.
  65          *
  66          * @param events Pending events.
  67          */
  68         using EventHandler = std::function<void(unsigned int events)>;
  69
  70         /**
  71          * Add a new file descriptor to be monitored. The added file descriptor
  72          * must be deleted with deleteMonitoredFD() function when no longer
  73          * monitored.
  74          *
  75          * @param fd     The file descriptor to monitor.
  76          * @param events The events to monitor as a bit mask of EVENT_IN and/or
  77          *               EVENT_OUT. There is no need to explicitly monitor
  78          *               EVENT_ERR or EVENT_HUP as they are automatically
  79          *               monitored.
  80          * @param eh     The event handler to call when any of the requested
  81          *               events occur.
  82          *
  83          * @see modifyMonitoredFD
  84          * @see deleteMonitoredFD
  85          */
  86         virtual void addMonitoredFD(int fd, unsigned int events, const EventHandler& eh) = 0;
  87
  88         /**
  89          * Add a new file descriptor to be monitored. The added file descriptor
  90          * is automatically deleted with deleteMonitorFD() upon its destructor.
  91          * This is achieved by using the FileDescriptor::atClose() function.
  92          *
  93          * @param fd     The file descriptor to monitor.
  94          * @param events The events to monitor as a bit mask of EVENT_IN and/or
  95          *               EVENT_OUT. There is no need to explicitly monitor
  96          *               EVENT_ERR or EVENT_HUP as they are automatically
  97          *               monitored.
  98          * @param eh     The event handler to call when any of the requested
  99          *               events occur.
 100          *
 101          * @see modifyMonitoredFD
 102          */
 103         virtual void addMonitoredFD(FileDescriptor& fd, unsigned int events, const EventHandler& eh) = 0;
 104
 105         /**
 106          * Modify monitored events related to an earlier added file descriptor.
 107          *
 108          * @param fd     The file descriptor whose monitored events to modify.
 109          * @param events The new events to monitor, bitmask of EVENTS_IN and/or
 110          *               EVENT_OUT. There is no need to explicitly monitor
 111          *               EVENT_ERR or EVENT_HUP as they are automatically
 112          *               monitored.
 113          *
 114          * @see addMonitoredFD
 115          * @see deleteMonitoredFD
 116          */
 117         virtual void modifyMonitoredFD(int fd, unsigned int events) = 0;
 118
 119         /**
 120          * Stop monitoring the given file descriptor.
 121          *
 122          * @param fd The file descriptor to stop monitoring.
 123          *
 124          * @see addMonitoredFD
 125          * @see modifyMonitoredFD
 126          */
 127         virtual void deleteMonitoredFD(int fd) = 0;
 128
 129         using Callback = std::function<void()>;
 130
 131         /**
 132          * Post a callback function. The function will be called by the
 133          * application's thread which is running the event loop and monitoring
 134          * the library epoll file descriptor.
 135          *
 136          * The main use cases for this function are
 137          * 1. To push work for the application's thread
 138          * 2. Fake asynchronous API with synchronous implementation
 139          *
 140          * @note This function <b>is</b> thread-safe.
 141          */
 142         virtual void postCallback(const Callback& callback) = 0;
 143
 144         virtual void run() = 0;
 145
 146         virtual void stop() = 0;
 147
 148         Engine(const Engine&) = delete;
 149         Engine(Engine&&) = delete;
 150         Engine& operator = (const Engine&) = delete;
 151         Engine& operator = (Engine&&) = delete;
 152
 153     protected:
 154         virtual void armTimer(Timer& timer, const Timer::Duration& duration, const Timer::Callback& cb) = 0;
 155
 156         virtual void disarmTimer(const Timer& timer) = 0;
 157     };
 158 }
 159
 160 #endif