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 #ifndef SHAREDDATALAYER_ENGINE_HPP_
  18 #define SHAREDDATALAYER_ENGINE_HPP_
  19
  20 #include <functional>
  21 #include "private/timer.hpp"
  22
  23 namespace shareddatalayer
  24 {
  25     class FileDescriptor;
  26
  27     /**
  28      * Engine provides the basic services needed by asynchronous library:
  29      * - File descriptor monitoring
  30      * - Timer monitoring
  31      * - Callback queue
  32      */
  33     class Engine
  34     {
  35         friend class Timer;
  36
  37     public:
  38         Engine() = default;
  39
  40         virtual ~Engine() = default;
  41
  42         virtual int fd() const = 0;
  43
  44         virtual void handleEvents() = 0;
  45
  46         /** There is data to read. */
  47         static const unsigned int EVENT_IN;
  48
  49         /** Writing is now possible. */
  50         static const unsigned int EVENT_OUT;
  51
  52         /** Error condition. */
  53         static const unsigned int EVENT_ERR;
  54
  55         /** Hang up. */
  56         static const unsigned int EVENT_HUP;
  57
  58         /**
  59          * Event handler function type.
  60          *
  61          * @param events Pending events.
  62          */
  63         using EventHandler = std::function<void(unsigned int events)>;
  64
  65         /**
  66          * Add a new file descriptor to be monitored. The added file descriptor
  67          * must be deleted with deleteMonitoredFD() function when no longer
  68          * monitored.
  69          *
  70          * @param fd     The file descriptor to monitor.
  71          * @param events The events to monitor as a bit mask of EVENT_IN and/or
  72          *               EVENT_OUT. There is no need to explicitly monitor
  73          *               EVENT_ERR or EVENT_HUP as they are automatically
  74          *               monitored.
  75          * @param eh     The event handler to call when any of the requested
  76          *               events occur.
  77          *
  78          * @see modifyMonitoredFD
  79          * @see deleteMonitoredFD
  80          */
  81         virtual void addMonitoredFD(int fd, unsigned int events, const EventHandler& eh) = 0;
  82
  83         /**
  84          * Add a new file descriptor to be monitored. The added file descriptor
  85          * is automatically deleted with deleteMonitorFD() upon its destructor.
  86          * This is achieved by using the FileDescriptor::atClose() function.
  87          *
  88          * @param fd     The file descriptor to monitor.
  89          * @param events The events to monitor as a bit mask of EVENT_IN and/or
  90          *               EVENT_OUT. There is no need to explicitly monitor
  91          *               EVENT_ERR or EVENT_HUP as they are automatically
  92          *               monitored.
  93          * @param eh     The event handler to call when any of the requested
  94          *               events occur.
  95          *
  96          * @see modifyMonitoredFD
  97          */
  98         virtual void addMonitoredFD(FileDescriptor& fd, unsigned int events, const EventHandler& eh) = 0;
  99
 100         /**
 101          * Modify monitored events related to an earlier added file descriptor.
 102          *
 103          * @param fd     The file descriptor whose monitored events to modify.
 104          * @param events The new events to monitor, bitmask of EVENTS_IN and/or
 105          *               EVENT_OUT. There is no need to explicitly monitor
 106          *               EVENT_ERR or EVENT_HUP as they are automatically
 107          *               monitored.
 108          *
 109          * @see addMonitoredFD
 110          * @see deleteMonitoredFD
 111          */
 112         virtual void modifyMonitoredFD(int fd, unsigned int events) = 0;
 113
 114         /**
 115          * Stop monitoring the given file descriptor.
 116          *
 117          * @param fd The file descriptor to stop monitoring.
 118          *
 119          * @see addMonitoredFD
 120          * @see modifyMonitoredFD
 121          */
 122         virtual void deleteMonitoredFD(int fd) = 0;
 123
 124         using Callback = std::function<void()>;
 125
 126         /**
 127          * Post a callback function. The function will be called by the
 128          * application's thread which is running the event loop and monitoring
 129          * the library epoll file descriptor.
 130          *
 131          * The main use cases for this function are
 132          * 1. To push work for the application's thread
 133          * 2. Fake asynchronous API with synchronous implementation
 134          *
 135          * @note This function <b>is</b> thread-safe.
 136          */
 137         virtual void postCallback(const Callback& callback) = 0;
 138
 139         virtual void run() = 0;
 140
 141         virtual void stop() = 0;
 142
 143         Engine(const Engine&) = delete;
 144         Engine(Engine&&) = delete;
 145         Engine& operator = (const Engine&) = delete;
 146         Engine& operator = (Engine&&) = delete;
 147
 148     protected:
 149         virtual void armTimer(Timer& timer, const Timer::Duration& duration, const Timer::Callback& cb) = 0;
 150
 151         virtual void disarmTimer(const Timer& timer) = 0;
 152     };
 153 }
 154
 155 #endif