d_process.h 8.11 KB
Newer Older
1
// Copyright (C) 2013-2019 Internet Systems Consortium, Inc. ("ISC")
2
//
3 4 5
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6 7 8 9

#ifndef D_PROCESS_H
#define D_PROCESS_H

10
#include <asiolink/io_service.h>
11
#include <cc/data.h>
12
#include <process/d_cfg_mgr.h>
13

14 15 16 17
#include <boost/shared_ptr.hpp>

#include <exceptions/exceptions.h>

18 19
#include <atomic>

20
namespace isc {
21
namespace process {
22 23

/// @brief Exception thrown if the process encountered an operational error.
24
class DProcessBaseError : public isc::Exception {
25
public:
26
    DProcessBaseError(const char* file, size_t line, const char* what) :
27 28 29
        isc::Exception(file, line, what) { };
};

Francis Dupont's avatar
Francis Dupont committed
30 31 32 33 34 35
/// @brief String value for the version-get command.
static const std::string VERSION_GET_COMMAND("version-get");

/// @brief String value for the build-report command.
static const std::string BUILD_REPORT_COMMAND("build-report");

Francis Dupont's avatar
Francis Dupont committed
36 37 38 39 40 41 42 43 44
/// @brief String value for the config-get command.
static const std::string CONFIG_GET_COMMAND("config-get");

/// @brief String value for the config-write command.
static const std::string CONFIG_WRITE_COMMAND("config-write");

/// @brief String value for the config-test command.
static const std::string CONFIG_TEST_COMMAND("config-test");

45 46 47
/// @brief String value for the config-reload command.
static const std::string CONFIG_RELOAD_COMMAND("config-reload");

48 49 50
/// @brief String value for the config-set command.
static const std::string CONFIG_SET_COMMAND("config-set");

51 52 53
/// @brief String value for the server-tag-get command.
static const std::string SERVER_TAG_GET_COMMAND("server-tag-get");

54 55 56
/// @brief String value for the shutdown command.
static const std::string SHUT_DOWN_COMMAND("shutdown");

57 58 59
/// @brief String value for the status-get command.
static const std::string STATUS_GET_COMMAND("status-get");

60
/// @brief Returned by the process to indicate a command was successful.
61
static const int COMMAND_SUCCESS = 0;
62 63

/// @brief Returned by the process to indicates a command failed.
64 65
static const int COMMAND_ERROR = 1;

66 67
/// @brief Returned by the process to indicates a command is not valid.
static const int COMMAND_INVALID = 2;
68

69 70
/// @brief Application Process Interface
///
71 72 73
/// DProcessBase is an abstract class represents the primary "application"
/// level object in a "managed" asynchronous application. It provides a uniform
/// interface such that a managing layer can construct, initialize, and start
74
/// the application's event loop.  The event processing is centered around the
75 76 77 78 79 80
/// use of isc::asiolink::io_service. The io_service is shared between the
/// managing layer and the DProcessBase.  This allows management layer IO such
/// as directives to be sensed and handled, as well as processing IO activity
/// specific to the application.  In terms of management layer IO, there are
/// methods shutdown, configuration updates, and commands unique to the
/// application.
81
class DProcessBase {
82 83 84
public:
    /// @brief Constructor
    ///
85
    /// @param app_name is a text label for the process. Generally used
86
    /// in log statements, but otherwise arbitrary.
87 88
    /// @param io_service is the io_service used by the caller for
    /// asynchronous event handling.
89 90
    /// @param cfg_mgr the configuration manager instance that handles
    /// configuration parsing.
91
    ///
92
    /// @throw DProcessBaseError is io_service is NULL.
93
    DProcessBase(const char* app_name, asiolink::IOServicePtr io_service,
94 95 96
                 DCfgMgrBasePtr cfg_mgr)
        : app_name_(app_name), io_service_(io_service), shut_down_flag_(false),
        cfg_mgr_(cfg_mgr) {
97
        if (!io_service_) {
98
            isc_throw (DProcessBaseError, "IO Service cannot be null");
99
        }
100 101 102 103

        if (!cfg_mgr_) {
            isc_throw (DProcessBaseError, "CfgMgr cannot be null");
        }
104 105 106
    };

    /// @brief May be used after instantiation to perform initialization unique
107 108 109
    /// to application. It must be invoked prior to invoking run. This would
    /// likely include the creation of additional IO sources and their
    /// integration into the io_service.
110
    /// @throw DProcessBaseError if the initialization fails.
111 112 113 114 115 116
    virtual void init() = 0;

    /// @brief Implements the process's event loop. In its simplest form it
    /// would an invocation io_service_->run().  This method should not exit
    /// until the process itself is exiting due to a request to shutdown or
    /// some anomaly is forcing an exit.
117
    /// @throw DProcessBaseError if an operational error is encountered.
118 119
    virtual void run() = 0;

120 121 122
    /// @brief Initiates the process's shutdown process.
    ///
    /// This is last step in the shutdown event callback chain, that is
123 124 125
    /// intended to notify the process it is to begin its shutdown process.
    ///
    /// @param args an Element set of shutdown arguments (if any) that are
126 127
    /// supported by the process derivation.
    ///
128
    /// @return an Element that contains the results of argument processing,
129 130 131
    /// consisting of an integer status value (0 means successful,
    /// non-zero means failure), and a string explanation of the outcome.
    ///
132
    /// @throw DProcessBaseError if an operational error is encountered.
133
    virtual isc::data::ConstElementPtr
134
    shutdown(isc::data::ConstElementPtr args) = 0;
135 136 137

    /// @brief Processes the given configuration.
    ///
138 139 140 141
    /// This method may be called multiple times during the process lifetime.
    /// Certainly once during process startup, and possibly later if the user
    /// alters configuration. This method must not throw, it should catch any
    /// processing errors and return a success or failure answer as described
142
    /// below. On success the last commit timestamp must be updated.
143 144
    ///
    /// @param config_set a new configuration (JSON) for the process
145
    /// @param check_only true if configuration is to be verified only, not applied
146 147
    /// @return an Element that contains the results of configuration composed
    /// of an integer status value (0 means successful, non-zero means failure),
148
    /// and a string explanation of the outcome.
149
    virtual isc::data::ConstElementPtr
150 151
    configure(isc::data::ConstElementPtr config_set,
              bool check_only = false) = 0;
152

153
    /// @brief Destructor
154
    virtual ~DProcessBase(){};
155

156 157
    /// @brief Checks if the process has been instructed to shut down.
    ///
158
    /// @return true if process shutdown flag is true.
159
    bool shouldShutdown() const {
160
        return (shut_down_flag_);
161 162
    }

163 164 165 166 167
    /// @brief Sets the process shut down flag to the given value.
    ///
    /// @param value is the new value to assign the flag.
    void setShutdownFlag(bool value) {
        shut_down_flag_ = value;
168 169
    }

170
    /// @brief Fetches the application name.
171
    ///
172
    /// @return application name string.
173 174
    const std::string getAppName() const {
        return (app_name_);
175 176
    }

177 178
    /// @brief Fetches the controller's IOService.
    ///
179
    /// @return a reference to the controller's IOService.
180
    asiolink::IOServicePtr& getIoService() {
181 182 183
        return (io_service_);
    }

184
    /// @brief Convenience method for stopping IOservice processing.
185
    /// Invoking this will cause the process to exit any blocking
186 187 188 189 190 191
    /// IOService method such as run().  No further IO events will be
    /// processed.
    void stopIOService() {
        io_service_->stop();
    }

192 193
    /// @brief Fetches the process's configuration manager.
    ///
194
    /// @return a reference to the configuration manager.
195 196 197 198
    DCfgMgrBasePtr& getCfgMgr() {
        return (cfg_mgr_);
    }

199
private:
200 201
    /// @brief Text label for the process. Generally used in log statements,
    /// but otherwise can be arbitrary.
202
    std::string app_name_;
203

204
    /// @brief The IOService to be used for asynchronous event handling.
205
    asiolink::IOServicePtr io_service_;
206 207

    /// @brief Boolean flag set when shutdown has been requested.
208
    std::atomic<bool> shut_down_flag_;
209 210 211

    /// @brief  Pointer to the configuration manager.
    DCfgMgrBasePtr cfg_mgr_;
212 213
};

214 215
/// @brief Defines a shared pointer to DProcessBase.
typedef boost::shared_ptr<DProcessBase> DProcessBasePtr;
216

217
}; // namespace isc::process
218 219 220
}; // namespace isc

#endif