2 Copyright (c) 2018-2019 Nokia.
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
8 http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef SHAREDDATALAYER_ENGINE_HPP_
18 #define SHAREDDATALAYER_ENGINE_HPP_
21 #include "private/timer.hpp"
23 namespace shareddatalayer
28 * Engine provides the basic services needed by asynchronous library:
29 * - File descriptor monitoring
40 virtual ~Engine() = default;
42 virtual int fd() const = 0;
44 virtual void handleEvents() = 0;
46 /** There is data to read. */
47 static const unsigned int EVENT_IN;
49 /** Writing is now possible. */
50 static const unsigned int EVENT_OUT;
52 /** Error condition. */
53 static const unsigned int EVENT_ERR;
56 static const unsigned int EVENT_HUP;
59 * Event handler function type.
61 * @param events Pending events.
63 using EventHandler = std::function<void(unsigned int events)>;
66 * Add a new file descriptor to be monitored. The added file descriptor
67 * must be deleted with deleteMonitoredFD() function when no longer
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
75 * @param eh The event handler to call when any of the requested
78 * @see modifyMonitoredFD
79 * @see deleteMonitoredFD
81 virtual void addMonitoredFD(int fd, unsigned int events, const EventHandler& eh) = 0;
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.
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
93 * @param eh The event handler to call when any of the requested
96 * @see modifyMonitoredFD
98 virtual void addMonitoredFD(FileDescriptor& fd, unsigned int events, const EventHandler& eh) = 0;
101 * Modify monitored events related to an earlier added file descriptor.
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
109 * @see addMonitoredFD
110 * @see deleteMonitoredFD
112 virtual void modifyMonitoredFD(int fd, unsigned int events) = 0;
115 * Stop monitoring the given file descriptor.
117 * @param fd The file descriptor to stop monitoring.
119 * @see addMonitoredFD
120 * @see modifyMonitoredFD
122 virtual void deleteMonitoredFD(int fd) = 0;
124 using Callback = std::function<void()>;
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.
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
135 * @note This function <b>is</b> thread-safe.
137 virtual void postCallback(const Callback& callback) = 0;
139 virtual void run() = 0;
141 virtual void stop() = 0;
143 Engine(const Engine&) = delete;
144 Engine(Engine&&) = delete;
145 Engine& operator = (const Engine&) = delete;
146 Engine& operator = (Engine&&) = delete;
149 virtual void armTimer(Timer& timer, const Timer::Duration& duration, const Timer::Callback& cb) = 0;
151 virtual void disarmTimer(const Timer& timer) = 0;