1 // Copyright (C) 2011-2021 Internet Systems Consortium, Inc. ("ISC")
2 //
3 // This Source Code Form is subject to the terms of the Mozilla Public
4 // License, v. 2.0. If a copy of the MPL was not distributed with this
5 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
6 
7 #ifndef ASIOLINK_IO_SERVICE_H
8 #define ASIOLINK_IO_SERVICE_H
9 
10 #include <boost/version.hpp>
11 #include <boost/shared_ptr.hpp>
12 #include <functional>
13 
14 namespace boost {
15 namespace asio {
16 #if BOOST_VERSION < 106600
17     class io_service;
18 #else
19     class io_context;
20     typedef io_context io_service;
21 #endif
22 }
23 }
24 
25 namespace isc {
26 namespace asiolink {
27 
28 class IOServiceImpl;
29 
30 /// \brief The \c IOService class is a wrapper for the ASIO \c io_service
31 /// class.
32 ///
33 class IOService {
34     ///
35     /// \name Constructors and Destructor
36     ///
37     /// Note: The copy constructor and the assignment operator are
38     /// intentionally defined as private, making this class non-copyable.
39     //@{
40 private:
41     IOService(const IOService& source);
42     IOService& operator=(const IOService& source);
43 public:
44     /// \brief The constructor
45     IOService();
46     /// \brief The destructor.
47     ~IOService();
48     //@}
49 
50     /// \brief Start the underlying event loop.
51     ///
52     /// This method does not return control to the caller until
53     /// the \c stop() method is called via some handler.
54     void run();
55 
56     /// \brief Run the underlying event loop for a single event.
57     ///
58     /// This method return control to the caller as soon as the
59     /// first handler has completed.  (If no handlers are ready when
60     /// it is run, it will block until one is.)
61     void run_one();
62 
63     /// \brief Run the underlying event loop for a ready events.
64     ///
65     /// This method executes handlers for all ready events and returns.
66     /// It will return immediately if there are no ready events.
67     void poll();
68 
69     /// \brief Stop the underlying event loop.
70     ///
71     /// This will return the control to the caller of the \c run() method.
72     void stop();
73 
74     /// \brief Indicates if the IOService has been stopped.
75     ///
76     /// \return true if the IOService has been stopped, false otherwise.
77     bool stopped() const;
78 
79     /// \brief Restarts the IOService in preparation for a subsequent \c run() invocation.
80     void restart();
81 
82     /// \brief Removes IO service work object to let it finish running
83     /// when all handlers have been invoked.
84     void stopWork();
85 
86     /// \brief Return the native \c io_service object used in this wrapper.
87     ///
88     /// This is a short term work around to support other Kea modules
89     /// that share the same \c io_service with the authoritative server.
90     /// It will eventually be removed once the wrapper interface is
91     /// generalized.
92     boost::asio::io_service& get_io_service();
93 
94     /// \brief Post a callback to the end of the queue.
95     ///
96     /// Requests the callback be called sometime later. It is not guaranteed
97     /// by the underlying asio, but it can reasonably be expected the callback
98     /// is put to the end of the callback queue. It is not called from within
99     /// this function.
100     ///
101     /// It may be used to implement "background" work, for example (doing stuff
102     /// by small bits that are called from time to time).
103     void post(const std::function<void ()>& callback);
104 
105 private:
106     boost::shared_ptr<IOServiceImpl> io_impl_;
107 };
108 
109 /// @brief Defines a smart pointer to an IOService instance.
110 typedef boost::shared_ptr<IOService> IOServicePtr;
111 
112 } // namespace asiolink
113 } // namespace isc
114 #endif // ASIOLINK_IO_SERVICE_H
115