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.

virtual	~D2Process ()
	Destructor.

virtual isc::data::ConstElementPtr	configure (isc::data::ConstElementPtr config_set, bool check_only=false)
	Processes the given configuration.

D2CfgMgrPtr	getD2CfgMgr ()
	Returns a pointer to the configuration manager.

const D2QueueMgrPtr &	getD2QueueMgr () const
	Returns a reference to the queue manager.

const D2UpdateMgrPtr &	getD2UpdateMgr () const
	Returns a reference to the update manager.

bool	getReconfQueueFlag () const
	Returns true if the queue manager should be reconfigured.

ShutdownType	getShutdownType () const
	Returns the type of shutdown requested.

virtual void	init ()
	Called after instantiation to perform initialization unique to D2.

virtual void	run ()
	Implements the process's event loop.

virtual isc::data::ConstElementPtr	shutdown (isc::data::ConstElementPtr args)
	Initiates the D2Process shutdown process.

Public Member Functions inherited from isc::process::DProcessBase
	DProcessBase (const char *app_name, asiolink::IOServicePtr io_service, DCfgMgrBasePtr cfg_mgr)
	Constructor.

virtual	~DProcessBase ()
	Destructor.

virtual isc::data::ConstElementPtr	configure (isc::data::ConstElementPtr config_set, bool check_only=false)=0
	Processes the given configuration.

const std::string	getAppName () const
	Fetches the application name.

DCfgMgrBasePtr &	getCfgMgr ()
	Fetches the process's configuration manager.

asiolink::IOServicePtr &	getIOService ()
	Fetches the controller's IOService.

virtual void	init ()=0
	May be used after instantiation to perform initialization unique to application.

virtual void	run ()=0
	Implements the process's event loop.

void	setShutdownFlag (bool value)
	Sets the process shut down flag to the given value.

bool	shouldShutdown () const
	Checks if the process has been instructed to shut down.

virtual isc::data::ConstElementPtr	shutdown (isc::data::ConstElementPtr args)=0
	Initiates the process's shutdown process.

void	stopIOService ()
	Convenience method for stopping IOservice processing.

Static Public Member Functions
static const char *	getShutdownTypeStr (const ShutdownType &type)
	Returns a text label for the given shutdown type.

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

Protected Member Functions
virtual bool	canShutdown () const
	Indicates whether or not the process can perform a shutdown.

virtual void	checkQueueStatus ()
	Monitors current queue manager state, takes action accordingly.

void	reconfigureCommandChannel ()
	(Re-)Configure the command channel.

virtual void	reconfigureQueueMgr ()
	Initializes then starts the queue manager.

virtual size_t	runIO ()
	Allows IO processing to run until at least callback is invoked.

void	setReconfQueueFlag (const bool value)
	Sets queue reconfigure indicator to the given value.

void	setShutdownType (const ShutdownType &value)
	Sets the shutdown type to the given value.

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

enum isc::d2::D2Process::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

name	name is a text label for the process. Generally used in log statements, but otherwise arbitrary.
io_service	is the io_service used by the caller for asynchronous event handling.

Exceptions

DProcessBaseError if io_service is NULL.

Definition at line 52 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 441 of file d2_process.cc.

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

Here is the call graph for this function:

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 156 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 311 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_set	a new configuration (JSON) for the process
check_only	true 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 238 of file d2_process.cc.

References isc::hooks::HooksManager::callCallouts(), isc::hooks::HooksManager::calloutsPresent(), isc::config::CONTROL_RESULT_ERROR, isc::config::createAnswer(), isc::hooks::HooksManager::createCalloutHandle(), isc::d2::d2_logger, isc::log::DBGLVL_TRACE_BASIC, isc::d2::DHCP_DDNS_CONFIGURE, isc::d2::DHCP_DDNS_CONFIGURED_CALLOUT_DROP, isc::process::DProcessBase::getCfgMgr(), getD2CfgMgr(), isc::process::DProcessBase::getIOService(), Hooks, LOG_DEBUG, LOG_ERROR, isc::hooks::CalloutHandle::NEXT_STEP_DROP, 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 453 of file d2_process.cc.

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

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

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 269 of file d2_process.h.

◆ getD2UpdateMgr()

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

inline

Returns a reference to the update manager.

Definition at line 274 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 279 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 286 of file d2_process.h.

◆ getShutdownTypeStr()

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

static

Returns a text label for the given shutdown type.

Parameters

type	the 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 460 of file d2_process.cc.

References SD_DRAIN_FIRST, SD_NORMAL, and SD_NOW.

Referenced by canShutdown(), 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 74 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 481 of file d2_process.cc.

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

Referenced by configure().

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 388 of file d2_process.cc.

References isc::d2::d2_logger, isc::d2::DHCP_DDNS_LISTENING_ON_ALL_INTERFACES, 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

DProcessBaseError if 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 80 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, 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

This	method 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 131 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

value is the new value to assign to the indicator

Note: this method is really only intended for testing purposes.

Definition at line 240 of file d2_process.h.

◆ setShutdownType()

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

inlineprotected

Sets the shutdown type to the given value.

Parameters

value is the new value to assign to shutdown type.

Note: this method is really only intended for testing purposes.

Definition at line 249 of file d2_process.h.

◆ 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

args	Specifies 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 201 of file d2_process.cc.

References isc::config::CONTROL_RESULT_ERROR, isc::config::CONTROL_RESULT_SUCCESS, 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:

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ ShutdownType

Constructor & Destructor Documentation

◆ D2Process()

◆ ~D2Process()

Member Function Documentation

◆ canShutdown()

◆ checkQueueStatus()

◆ configure()

◆ getD2CfgMgr()

◆ getD2QueueMgr()

◆ getD2UpdateMgr()

◆ getReconfQueueFlag()

◆ getShutdownType()

◆ getShutdownTypeStr()

◆ init()

◆ reconfigureCommandChannel()

◆ reconfigureQueueMgr()

◆ run()

◆ runIO()

◆ setReconfQueueFlag()

◆ setShutdownType()

◆ shutdown()

Member Data Documentation

◆ QUEUE_RESTART_PERCENT