Kea  2.3.5-git
isc::d2::D2Process Class Reference

DHCP-DDNS Application Process. More...

#include <d2_process.h>

+ Inheritance diagram for isc::d2::D2Process:

Public Types

enum  ShutdownType { SD_NORMAL, SD_DRAIN_FIRST, SD_NOW }
 Defines the shutdown types supported by D2Process. More...
 

Public Member Functions

 D2Process (const char *name, const asiolink::IOServicePtr &io_service)
 Constructor. More...
 
virtual ~D2Process ()
 Destructor. More...
 
virtual isc::data::ConstElementPtr configure (isc::data::ConstElementPtr config_set, bool check_only=false)
 Processes the given configuration. More...
 
D2CfgMgrPtr getD2CfgMgr ()
 Returns a pointer to the configuration manager. More...
 
const D2QueueMgrPtrgetD2QueueMgr () const
 Returns a reference to the queue manager. More...
 
const D2UpdateMgrPtrgetD2UpdateMgr () const
 Returns a reference to the update manager. More...
 
bool getReconfQueueFlag () const
 Returns true if the queue manager should be reconfigured. More...
 
ShutdownType getShutdownType () const
 Returns the type of shutdown requested. More...
 
virtual void init ()
 Called after instantiation to perform initialization unique to D2. More...
 
virtual void run ()
 Implements the process's event loop. More...
 
virtual isc::data::ConstElementPtr shutdown (isc::data::ConstElementPtr args)
 Initiates the D2Process shutdown process. More...
 
- Public Member Functions inherited from isc::process::DProcessBase
 DProcessBase (const char *app_name, asiolink::IOServicePtr io_service, DCfgMgrBasePtr cfg_mgr)
 Constructor. More...
 
virtual ~DProcessBase ()
 Destructor. More...
 
const std::string getAppName () const
 Fetches the application name. More...
 
DCfgMgrBasePtrgetCfgMgr ()
 Fetches the process's configuration manager. More...
 
asiolink::IOServicePtrgetIoService ()
 Fetches the controller's IOService. More...
 
void setShutdownFlag (bool value)
 Sets the process shut down flag to the given value. More...
 
bool shouldShutdown () const
 Checks if the process has been instructed to shut down. More...
 
void stopIOService ()
 Convenience method for stopping IOservice processing. More...
 

Static Public Member Functions

static const char * getShutdownTypeStr (const ShutdownType &type)
 Returns a text label for the given shutdown type. More...
 

Static Public Attributes

static const unsigned int QUEUE_RESTART_PERCENT = 80
 Defines the point at which to resume receiving requests. More...
 

Protected Member Functions

virtual bool canShutdown () const
 Indicates whether or not the process can perform a shutdown. More...
 
virtual void checkQueueStatus ()
 Monitors current queue manager state, takes action accordingly. More...
 
void reconfigureCommandChannel ()
 (Re-)Configure the command channel. More...
 
virtual void reconfigureQueueMgr ()
 Initializes then starts the queue manager. More...
 
virtual size_t runIO ()
 Allows IO processing to run until at least callback is invoked. More...
 
void setReconfQueueFlag (const bool value)
 Sets queue reconfigure indicator to the given value. More...
 
void setShutdownType (const ShutdownType &value)
 Sets the shutdown type to the given value. More...
 

Detailed Description

DHCP-DDNS Application Process.

D2Process provides the top level application logic for DHCP-driven DDNS update processing. It provides the asynchronous event processing required to receive DNS mapping change requests and carry them out. It implements the DProcessBase interface, which structures it such that it is a managed "application", controlled by a management layer.

Definition at line 24 of file d2_process.h.

Member Enumeration Documentation

◆ ShutdownType

Defines the shutdown types supported by D2Process.

  • SD_NORMAL - Stops the queue manager and finishes all current transactions before exiting. This is the default.
  • SD_DRAIN_FIRST - Stops the queue manager but continues processing requests from the queue until it is empty.
  • SD_NOW - Exits immediately.
Enumerator
SD_NORMAL 
SD_DRAIN_FIRST 
SD_NOW 

Definition at line 36 of file d2_process.h.

Constructor & Destructor Documentation

◆ D2Process()

isc::d2::D2Process::D2Process ( const char *  name,
const asiolink::IOServicePtr io_service 
)

Constructor.

Construction creates the configuration manager, the queue manager, and the update manager.

Parameters
namename is a text label for the process. Generally used in log statements, but otherwise arbitrary.
io_serviceis the io_service used by the caller for asynchronous event handling.
Exceptions
DProcessBaseErrorif io_service is NULL.

Definition at line 51 of file d2_process.cc.

References getD2CfgMgr(), isc::process::DProcessBase::getIoService(), and isc::d2::D2Stats::init().

+ Here is the call graph for this function:

◆ ~D2Process()

isc::d2::D2Process::~D2Process ( )
virtual

Destructor.

Definition at line 438 of file d2_process.cc.

Member Function Documentation

◆ canShutdown()

bool isc::d2::D2Process::canShutdown ( ) const
protectedvirtual

Indicates whether or not the process can perform a shutdown.

Determines if the process has been instructed to shutdown and if the criteria for performing the type of shutdown requested has been met.

Returns
Returns true if the criteria has been met, false otherwise.

Definition at line 157 of file d2_process.cc.

References isc::d2::d2_logger, isc::log::DBGLVL_START_SHUT, isc::d2::DHCP_DDNS_CLEARED_FOR_SHUTDOWN, getShutdownTypeStr(), LOG_DEBUG, isc::d2::D2QueueMgr::RUNNING, SD_DRAIN_FIRST, SD_NORMAL, SD_NOW, isc::process::DProcessBase::shouldShutdown(), and isc::d2::D2QueueMgr::STOPPING.

Referenced by run().

+ Here is the call graph for this function:

◆ checkQueueStatus()

void isc::d2::D2Process::checkQueueStatus ( )
protectedvirtual

Monitors current queue manager state, takes action accordingly.

This method ensures that the queue manager transitions to the state most appropriate to the operational state of the D2Process and any events that may have occurred since it was last called. It is called once for each iteration of the event loop. It is essentially a switch statement based on the D2QueueMgr's current state. The logic is as follows:

If the state is D2QueueMgr::RUNNING, and the queue manager needs to be reconfigured or we have been told to shutdown, then instruct the queue manager to stop listening. Exit the method.

If the state is D2QueueMgr::STOPPED_QUEUE_FULL, then check if the number of entries in the queue has fallen below the "resume threshold". If it has, then instruct the queue manager to start listening. Exit the method.

If the state is D2QueueMgr::STOPPED_RECV_ERROR, then attempt to recover by calling reconfigureQueueMgr(). Exit the method.

If the state is D2QueueMgr::STOPPING, simply exit the method. This is a NOP condition as we are waiting for the IO cancel event

For any other state, (NOT_INITTED,INITTED,STOPPED), if the reconfigure queue flag is set, call reconfigureQueueMgr(). Exit the method.

This method is exception safe.

If we need to reconfigure the queue manager or we have been told to shutdown, then stop listening first. Stopping entails canceling active listening which may generate an IO event, so instigate the stop and get out.

Resume receiving once the queue has decreased by twenty percent. This is an arbitrary choice.

Todo:
this value should probably be configurable.

If the receive error is not due to some fallout from shutting down then we will attempt to recover by reconfiguring the listener. This will close and destruct the current listener and make a new one with new resources.

Todo:
This may need a safety valve such as retry count or a timer to keep from endlessly retrying over and over, with little time in between.

We are waiting for IO to cancel, so this is a NOP.

Todo:
Possible timer for self-defense? We could conceivably get into a condition where we never get the event, which would leave us stuck in stopping. This is hugely unlikely but possible?

Definition at line 310 of file d2_process.cc.

References isc::d2::d2_logger, isc::log::DBGLVL_START_SHUT, isc::log::DBGLVL_TRACE_BASIC, isc::d2::DHCP_DDNS_QUEUE_MGR_RECONFIGURING, isc::d2::DHCP_DDNS_QUEUE_MGR_RECOVERING, isc::d2::DHCP_DDNS_QUEUE_MGR_RESUME_ERROR, isc::d2::DHCP_DDNS_QUEUE_MGR_RESUMING, isc::d2::DHCP_DDNS_QUEUE_MGR_STOP_ERROR, isc::d2::DHCP_DDNS_QUEUE_MGR_STOPPING, LOG_DEBUG, LOG_ERROR, LOG_INFO, QUEUE_RESTART_PERCENT, reconfigureQueueMgr(), isc::d2::D2QueueMgr::RUNNING, isc::process::DProcessBase::shouldShutdown(), isc::d2::D2QueueMgr::STOPPED_QUEUE_FULL, isc::d2::D2QueueMgr::STOPPED_RECV_ERROR, isc::d2::D2QueueMgr::STOPPING, and isc::Exception::what().

Referenced by run().

+ Here is the call graph for this function:

◆ configure()

isc::data::ConstElementPtr isc::d2::D2Process::configure ( isc::data::ConstElementPtr  config_set,
bool  check_only = false 
)
virtual

Processes the given configuration.

This method may be called multiple times during the process lifetime. Certainly once during process startup, and possibly later if the user alters the configuration. This method must not throw, it should catch any processing errors and return a success or failure answer as described below.

This method passes the newly received configuration to the configuration manager instance for parsing. The configuration manager parses the configuration and updates the necessary values within the context, assuming it parses correctly. If that's the case this method sets the flag to reconfigure the queue manager and returns a successful response as described below.

If the new configuration fails to parse, then the current configuration is retained and a failure response is returned as described below.

Parameters
config_seta new configuration (JSON) for the process
check_onlytrue if configuration is to be verified only, not applied
Returns
an Element that contains the results of configuration composed of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.

(

Todo:
NOTE This could be turned into a bitmask of flags if we find other things that need reconfiguration. It might also be useful if we did some analysis to decide what if anything we need to do.)

Implements isc::process::DProcessBase.

Definition at line 237 of file d2_process.cc.

References isc::config::createAnswer(), isc::d2::d2_logger, isc::log::DBGLVL_TRACE_BASIC, isc::d2::DHCP_DDNS_CONFIGURE, isc::d2::DHCP_DDNS_CONFIGURED_CALLOUT_DROP, isc::db::error, isc::process::DProcessBase::getCfgMgr(), getD2CfgMgr(), isc::process::DProcessBase::getIoService(), Hooks, LOG_DEBUG, LOG_ERROR, isc::config::parseAnswer(), reconfigureCommandChannel(), and isc::process::redactConfig().

+ Here is the call graph for this function:

◆ getD2CfgMgr()

D2CfgMgrPtr isc::d2::D2Process::getD2CfgMgr ( )

Returns a pointer to the configuration manager.

Note, this method cannot return a reference as it uses dynamic pointer casting of the base class configuration manager.

Definition at line 442 of file d2_process.cc.

References isc::process::DProcessBase::getCfgMgr().

Referenced by configure(), D2Process(), reconfigureCommandChannel(), reconfigureQueueMgr(), and setShutdownType().

+ Here is the call graph for this function:

◆ getD2QueueMgr()

const D2QueueMgrPtr& isc::d2::D2Process::getD2QueueMgr ( ) const
inline

Returns a reference to the queue manager.

Definition at line 271 of file d2_process.h.

◆ getD2UpdateMgr()

const D2UpdateMgrPtr& isc::d2::D2Process::getD2UpdateMgr ( ) const
inline

Returns a reference to the update manager.

Definition at line 276 of file d2_process.h.

◆ getReconfQueueFlag()

bool isc::d2::D2Process::getReconfQueueFlag ( ) const
inline

Returns true if the queue manager should be reconfigured.

Definition at line 281 of file d2_process.h.

◆ getShutdownType()

ShutdownType isc::d2::D2Process::getShutdownType ( ) const
inline

Returns the type of shutdown requested.

Note, this value is meaningless unless shouldShutdown() returns true.

Definition at line 288 of file d2_process.h.

References getShutdownTypeStr().

+ Here is the call graph for this function:

◆ getShutdownTypeStr()

const char * isc::d2::D2Process::getShutdownTypeStr ( const ShutdownType type)
static

Returns a text label for the given shutdown type.

Parameters
typethe numerical shutdown type for which the label is desired.
Returns
A text label corresponding the value or "invalid" if the value is not a valid value.

Definition at line 449 of file d2_process.cc.

References SD_DRAIN_FIRST, SD_NORMAL, and SD_NOW.

Referenced by canShutdown(), getShutdownType(), and shutdown().

◆ init()

void isc::d2::D2Process::init ( )
virtual

Called after instantiation to perform initialization unique to D2.

This is invoked by the controller after command line arguments but PRIOR to configuration reception. The base class provides this method as a place to perform any derivation-specific initialization steps that are inappropriate for the constructor but necessary prior to configure. For D2 it is used to initialize the command manager.

Implements isc::process::DProcessBase.

Definition at line 73 of file d2_process.cc.

References isc::process::DProcessBase::getIoService(), isc::config::CommandMgr::instance(), and isc::config::CommandMgr::setIOService().

+ Here is the call graph for this function:

◆ reconfigureCommandChannel()

void isc::d2::D2Process::reconfigureCommandChannel ( )
protected

(Re-)Configure the command channel.

Only close the current channel, if the new channel configuration is different. This avoids disconnecting a client and hence not sending them a command result, unless they specifically alter the channel configuration. In that case the user simply has to accept they'll be disconnected.

Definition at line 469 of file d2_process.cc.

References isc::config::CommandMgr::closeCommandSocket(), getD2CfgMgr(), isc::config::CommandMgr::instance(), and isc::config::CommandMgr::openCommandSocket().

Referenced by configure(), and setShutdownType().

+ Here is the call graph for this function:

◆ reconfigureQueueMgr()

void isc::d2::D2Process::reconfigureQueueMgr ( )
protectedvirtual

Initializes then starts the queue manager.

This method initializes the queue manager with the current configuration parameters and instructs it to start listening. Note the existing listener instance (if it exists) is destroyed, and that a new listener is created during initialization.

This method is exception safe.

Todo:
This method assumes only 1 type of listener. This will change to support at least a TCP version, possibly some form of RDBMS listener as well.

Warn the user if the server address is not the loopback.

Todo:
Remove this once we provide a secure mechanism.
Todo:
Add TCP/IP once it's supported
Todo:
Should that change then we will have to expand the state model to accommodate this.

Definition at line 387 of file d2_process.cc.

References isc::d2::d2_logger, isc::d2::DHCP_DDNS_NOT_ON_LOOPBACK, isc::d2::DHCP_DDNS_QUEUE_MGR_START_ERROR, getD2CfgMgr(), isc_throw, LOG_ERROR, LOG_WARN, isc::dhcp_ddns::NCR_UDP, isc::dhcp_ddns::ncrProtocolToString(), and isc::Exception::what().

Referenced by checkQueueStatus().

+ Here is the call graph for this function:

◆ run()

void isc::d2::D2Process::run ( )
virtual

Implements the process's event loop.

Once entered, the main control thread remains inside this method until shutdown. The event loop logic is as follows:

while should not shutdown {
process queue manager state change
process completed jobs
dequeue new jobs
wait for IO event(s)
ON an exception, exit with fatal error
}

To summarize, each pass through the event loop first checks the state of the received queue and takes any steps required to ensure it is operating in the manner necessary. Next the update manager is given a chance to clean up any completed transactions and start new transactions by dequeuing jobs from the request queue. Lastly, it allows IOService to process until one or more event handlers are called. Note that this last step will block until at least one ready handler is invoked. In other words, if no IO events have occurred since it was last called, the event loop will block at this step until an IO event occurs. At that time we return to the top of the loop.

Exceptions
DProcessBaseErrorif an error is encountered. Note that exceptions thrown at this point are assumed to be FATAL exceptions. This includes exceptions generated but not caught by IO callbacks. Services which rely on callbacks are expected to be well behaved and any errors they encounter handled internally.
Todo:
  • if queue isn't empty, we may need to persist its contents this might be the place to do it, once there is a persistence mgr. This may also be better in checkQueueStatus.

Implements isc::process::DProcessBase.

Definition at line 79 of file d2_process.cc.

References canShutdown(), checkQueueStatus(), isc::d2::d2_logger, isc::log::DBGLVL_START_SHUT, isc::d2::DHCP_DDNS_FAILED, isc::d2::DHCP_DDNS_RUN_EXIT, isc::d2::DHCP_DDNS_STARTED, isc::d2::D2Controller::instance(), isc_throw, LOG_DEBUG, LOG_FATAL, LOG_INFO, isc::d2::D2Controller::registerCommands(), runIO(), and isc::Exception::what().

+ Here is the call graph for this function:

◆ runIO()

size_t isc::d2::D2Process::runIO ( )
protectedvirtual

Allows IO processing to run until at least callback is invoked.

This method is called from within the D2Process main event loop and is the point at which the D2Process blocks, waiting for IO events to cause IO event callbacks to be invoked.

If callbacks are ready to be executed upon entry, the method will return as soon as these callbacks have completed. If no callbacks are ready, then it will wait (indefinitely) until at least one callback is executed.

Note
: Should become desirable to periodically force an event, an interval timer could be used to do so.
Returns
The number of callback handlers executed, or 0 if the IO service has been stopped.
Exceptions
Thismethod does not throw directly, but the execution of callbacks invoked in response to IO events might. If so, these will propagate upward out of this method.

Definition at line 130 of file d2_process.cc.

References isc::process::DProcessBase::getIoService().

Referenced by run().

+ Here is the call graph for this function:

◆ setReconfQueueFlag()

void isc::d2::D2Process::setReconfQueueFlag ( const bool  value)
inlineprotected

Sets queue reconfigure indicator to the given value.

Parameters
valueis the new value to assign to the indicator
Note
this method is really only intended for testing purposes.

Definition at line 242 of file d2_process.h.

◆ setShutdownType()

void isc::d2::D2Process::setShutdownType ( const ShutdownType value)
inlineprotected

Sets the shutdown type to the given value.

Parameters
valueis the new value to assign to shutdown type.
Note
this method is really only intended for testing purposes.

Definition at line 251 of file d2_process.h.

References getD2CfgMgr(), and reconfigureCommandChannel().

+ Here is the call graph for this function:

◆ shutdown()

isc::data::ConstElementPtr isc::d2::D2Process::shutdown ( isc::data::ConstElementPtr  args)
virtual

Initiates the D2Process shutdown process.

This is last step in the shutdown event callback chain. It is invoked to notify D2Process that it needs to begin its shutdown procedure. Note that shutting down may be neither instantaneous nor synchronous, This method records the request for and the type of shutdown desired. Generally it will require one or more subsequent events to complete, dependent on the type of shutdown requested. The type of shutdown is specified as an optional argument of the shutdown command. The types of shutdown supported are:

  • "normal" - Stops the queue manager and finishes all current transactions before exiting. This is the default.
  • "drain_first" - Stops the queue manager but continues processing requests from the queue until it is empty.
  • "now" - Exits immediately.
Parameters
argsSpecifies the shutdown "type" as "normal", "drain_first", or "now"
Returns
an Element that contains the results of argument processing, consisting of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.

Implements isc::process::DProcessBase.

Definition at line 202 of file d2_process.cc.

References isc::config::createAnswer(), isc::d2::d2_logger, isc::log::DBGLVL_START_SHUT, isc::d2::DHCP_DDNS_SHUTDOWN_COMMAND, getShutdownTypeStr(), LOG_DEBUG, isc::data::Element::map, SD_DRAIN_FIRST, SD_NORMAL, SD_NOW, and isc::process::DProcessBase::setShutdownFlag().

+ Here is the call graph for this function:

Member Data Documentation

◆ QUEUE_RESTART_PERCENT

const unsigned int isc::d2::D2Process::QUEUE_RESTART_PERCENT = 80
static

Defines the point at which to resume receiving requests.

If the receive queue has become full, D2Process will "pause" the reception of requests by putting the queue manager in the stopped state. Once the number of entries has decreased to this percentage of the maximum allowed, D2Process will "resume" receiving requests by restarting the queue manager.

Definition at line 48 of file d2_process.h.

Referenced by checkQueueStatus().


The documentation for this class was generated from the following files: