D2QueueMgr creates and manages a queue of DNS update requests. More...

#include <d2_queue_mgr.h>

Inheritance diagram for isc::d2::D2QueueMgr:

Public Types
enum	State { NOT_INITTED , INITTED , RUNNING , STOPPING , STOPPED_QUEUE_FULL , STOPPED_RECV_ERROR , STOPPED }
	Defines the list of possible states for D2QueueMgr. More...

Public Member Functions
	D2QueueMgr (asiolink::IOServicePtr &io_service, const size_t max_queue_size=MAX_QUEUE_DEFAULT)
	Constructor.

virtual	~D2QueueMgr ()
	Destructor.

void	clearQueue ()
	Removes all entries from the queue.

void	dequeue ()
	Removes the entry at the front of the queue.

void	dequeueAt (const size_t index)
	Removes the entry at a given position in the queue.

void	enqueue (dhcp_ddns::NameChangeRequestPtr &ncr)
	Adds a request to the end of the queue.

size_t	getMaxQueueSize () const
	Returns the maximum number of entries allowed in the queue.

State	getMgrState () const
	Returns the current state.

size_t	getQueueSize () const
	Returns the number of entries in the queue.

void	initUDPListener (const isc::asiolink::IOAddress &ip_address, const uint32_t port, const dhcp_ddns::NameChangeFormat format, const bool reuse_address=false)
	Initializes the listener as a UDP listener.

virtual void	operator() (const dhcp_ddns::NameChangeListener::Result result, dhcp_ddns::NameChangeRequestPtr &ncr)
	Function operator implementing the NCR receive callback.

const dhcp_ddns::NameChangeRequestPtr &	peek () const
	Returns the entry at the front of the queue.

const dhcp_ddns::NameChangeRequestPtr &	peekAt (const size_t index) const
	Returns the entry at a given position in the queue.

void	removeListener ()
	Deletes the current listener.

void	setMaxQueueSize (const size_t max_queue_size)
	Sets the maximum number of entries allowed in the queue.

void	startListening ()
	Starts actively listening for requests.

void	stopListening (const State target_stop_state=STOPPED)
	Stops listening for requests.

Public Member Functions inherited from isc::dhcp_ddns::NameChangeListener::RequestReceiveHandler
virtual	~RequestReceiveHandler ()

virtual void	operator() (const Result result, NameChangeRequestPtr &ncr)=0
	Function operator implementing a NCR receive callback.

Static Public Attributes
static const size_t	MAX_QUEUE_DEFAULT = 1024
	Maximum number of entries allowed in the request queue.

Detailed Description

D2QueueMgr creates and manages a queue of DNS update requests.

D2QueueMgr is a class specifically designed as an integral part of DHCP-DDNS. Its primary responsibility is to listen for NameChangeRequests from DHCP-DDNS clients (e.g. DHCP servers) and queue them for processing. In addition it may provide a number of services to locate entries in the queue such as by FQDN or DHCID. These services may eventually be used for processing optimization. The initial implementation will support simple FIFO access.

D2QueueMgr uses a NameChangeListener to asynchronously receive requests. It derives from NameChangeListener::RequestReceiveHandler and supplies an implementation of the operator()(Result, NameChangeRequestPtr). It is through this operator() that D2QueueMgr is passed inbound NCRs. D2QueueMgr will add each newly received request onto the back of the request queue

D2QueueMgr defines a simple state model constructed around the status of its NameChangeListener, consisting of the following states:

* NOT_INITTED - D2QueueMgr has been constructed, but its listener has
not been initialized.

* INITTED - The listener has been initialized, but it is not open for
listening.   To move from NOT_INITTED to INITTED, one of the D2QueueMgr
listener initialization methods must be invoked.  Currently there is
only one type of listener, NameChangeUDPListener, hence there is only
one listener initialization method, initUDPListener.  As more listener
types are created, listener initialization methods will need to be
added.

* RUNNING - The listener is open and listening for requests.
Once initialized, in order to begin listening for requests, the
startListener() method must be invoked.  Upon successful completion of
of this call, D2QueueMgr will begin receiving requests as they arrive
without any further steps.   This method may be called from the INITTED
or one of the STOPPED states.

* STOPPING - The listener is in the process of stopping active
listening. This is transitory state between RUNNING and STOPPED, which
is completed by IO cancellation event.

* STOPPED - The listener has been listening but has been stopped
without error. To return to listening, startListener() must be invoked.

* STOPPED_QUEUE_FULL - Request queue is full, the listener has been
stopped.  D2QueueMgr will enter this state when the request queue
reaches the maximum queue size.  Once this limit is reached, the
listener will be closed and no further requests will be received.
To return to listening, startListener() must be invoked.  Note that so
long as the queue is full, any attempt to queue a request will fail.

* STOPPED_RECV_ERROR - The listener has experienced a receive error
and has been stopped.  D2QueueMgr will enter this state when it is
passed a failed status into the request completion handler.  To return
to listening, startListener() must be invoked.

D2QueueMgr does not attempt to recover from stopped conditions, this is left to upper layers.

It is important to note that the queue contents are preserved between state transitions. In other words entries in the queue remain there until they are removed explicitly via the deque() or implicitly by via the clearQueue() method.

Definition at line 129 of file d2_queue_mgr.h.

Member Enumeration Documentation

◆ State

enum isc::d2::D2QueueMgr::State

Defines the list of possible states for D2QueueMgr.

Enumerator
NOT_INITTED
INITTED
RUNNING
STOPPING
STOPPED_QUEUE_FULL
STOPPED_RECV_ERROR
STOPPED

Definition at line 138 of file d2_queue_mgr.h.

Constructor & Destructor Documentation

◆ D2QueueMgr()

isc::d2::D2QueueMgr::D2QueueMgr	(	asiolink::IOServicePtr &	io_service,
		const size_t	max_queue_size = `MAX_QUEUE_DEFAULT`
	)

Constructor.

Creates a D2QueueMgr instance. Note that the listener is not created in the constructor. The initial state will be NOT_INITTED.

Parameters

io_service	IOService instance to be passed into the listener for IO management.
max_queue_size	the maximum number of entries allowed in the queue. This value must be greater than zero. It defaults to MAX_QUEUE_DEFAULT.

Exceptions

D2QueueMgrError if max_queue_size is zero.

Definition at line 18 of file d2_queue_mgr.cc.

References isc_throw, and setMaxQueueSize().

Here is the call graph for this function:

◆ ~D2QueueMgr()

isc::d2::D2QueueMgr::~D2QueueMgr ( )

virtual

Destructor.

Definition at line 29 of file d2_queue_mgr.cc.

Member Function Documentation

◆ clearQueue()

void isc::d2::D2QueueMgr::clearQueue ( )

Removes all entries from the queue.

Definition at line 241 of file d2_queue_mgr.cc.

◆ dequeue()

void isc::d2::D2QueueMgr::dequeue ( )

Removes the entry at the front of the queue.

Exceptions

D2QueueMgrQueueEmpty if there are no entries in the queue.

Definition at line 226 of file d2_queue_mgr.cc.

References getQueueSize(), and isc_throw.

Here is the call graph for this function:

◆ dequeueAt()

void isc::d2::D2QueueMgr::dequeueAt ( const size_t index )

Removes the entry at a given position in the queue.

Parameters

index the index of the entry in the queue to remove. Valid values are 0 (front of the queue) to (queue size - 1).

Exceptions

D2QueueMgrInvalidIndex if the given index is beyond the end of the queue.

Definition at line 214 of file d2_queue_mgr.cc.

References getQueueSize(), and isc_throw.

Here is the call graph for this function:

◆ enqueue()

void isc::d2::D2QueueMgr::enqueue ( dhcp_ddns::NameChangeRequestPtr & ncr )

Adds a request to the end of the queue.

Parameters

ncr	pointer to the NameChangeRequest to add to the queue.

Definition at line 236 of file d2_queue_mgr.cc.

Referenced by operator()().

◆ getMaxQueueSize()

size_t isc::d2::D2QueueMgr::getMaxQueueSize ( ) const

inline

Returns the maximum number of entries allowed in the queue.

Definition at line 250 of file d2_queue_mgr.h.

Referenced by operator()().

◆ getMgrState()

State isc::d2::D2QueueMgr::getMgrState ( ) const

inline

Returns the current state.

Definition at line 264 of file d2_queue_mgr.h.

◆ getQueueSize()

size_t isc::d2::D2QueueMgr::getQueueSize ( ) const

inline

Returns the number of entries in the queue.

Definition at line 245 of file d2_queue_mgr.h.

Referenced by dequeue(), dequeueAt(), operator()(), peek(), peekAt(), and setMaxQueueSize().

◆ initUDPListener()

void isc::d2::D2QueueMgr::initUDPListener	(	const isc::asiolink::IOAddress &	ip_address,
		const uint32_t	port,
		const dhcp_ddns::NameChangeFormat	format,
		const bool	reuse_address = `false`
	)

Initializes the listener as a UDP listener.

Instantiates the listener_ member as NameChangeUDPListener passing the given parameters. Upon successful completion, the D2QueueMgr state will be INITTED.

Parameters

ip_address	is the network address on which to listen
port	is the IP port on which to listen
format	is the wire format of the inbound requests.
reuse_address	enables IP address sharing when true It defaults to false.

Definition at line 99 of file d2_queue_mgr.cc.

References INITTED, and isc_throw.

◆ operator()()

void isc::d2::D2QueueMgr::operator()	(	const dhcp_ddns::NameChangeListener::Result	result,
		dhcp_ddns::NameChangeRequestPtr &	ncr
	)

virtual

Function operator implementing the NCR receive callback.

This method is invoked by the listener as part of its receive completion callback and is how the inbound NameChangeRequests are passed up to the D2QueueMgr for queuing. If the given result indicates a successful receive completion and there is room left in the queue, the given request is queued.

If the queue is at maximum capacity, stopListening() is invoked and the state is set to STOPPED_QUEUE_FULL.

If the result indicates IO stopped, then the state is set to STOPPED. Note this is not an error, it results from a deliberate cancellation of listener IO as part of a normal stopListener call.

If the result indicates a failed receive, stopListening() is invoked and the state is set to STOPPED_RECV_ERROR.

This method specifically avoids throwing on an error as any such throw would surface at the io_service::run (or run variant) method invocation site. The upper layers are expected to monitor D2QueueMgr's state and act accordingly.

Parameters

result	contains that receive outcome status.
ncr	is a pointer to the newly received NameChangeRequest if result is NameChangeListener::SUCCESS. It is indeterminate other wise.

Implements isc::dhcp_ddns::NameChangeListener::RequestReceiveHandler.

Definition at line 33 of file d2_queue_mgr.cc.

References isc::log::DBGLVL_TRACE_DETAIL_DATA, isc::d2::DHCP_DDNS_QUEUE_MGR_QUEUE_FULL, isc::d2::DHCP_DDNS_QUEUE_MGR_QUEUE_RECEIVE, isc::d2::DHCP_DDNS_QUEUE_MGR_RECV_ERROR, isc::d2::DHCP_DDNS_QUEUE_MGR_UNEXPECTED_HANDLER_ERROR, isc::d2::DHCP_DDNS_QUEUE_MGR_UNEXPECTED_STOP, isc::d2::dhcp_to_d2_logger, enqueue(), getMaxQueueSize(), getQueueSize(), LOG_DEBUG, LOG_ERROR, stopListening(), isc::dhcp_ddns::NameChangeListener::STOPPED, STOPPED_QUEUE_FULL, STOPPED_RECV_ERROR, STOPPING, and isc::dhcp_ddns::NameChangeListener::SUCCESS.

Here is the call graph for this function:

◆ peek()

const dhcp_ddns::NameChangeRequestPtr & isc::d2::D2QueueMgr::peek ( ) const

Returns the entry at the front of the queue.

The entry returned is next in line to be processed, assuming a FIFO approach to task selection. Note, the entry is not removed from the queue.

Returns: Pointer reference to the queue entry.

Exceptions

D2QueueMgrQueueEmpty if there are no entries in the queue.

Definition at line 193 of file d2_queue_mgr.cc.

References getQueueSize(), and isc_throw.

Here is the call graph for this function:

◆ peekAt()

const dhcp_ddns::NameChangeRequestPtr & isc::d2::D2QueueMgr::peekAt ( const size_t index ) const

Returns the entry at a given position in the queue.

Note that the entry is not removed from the queue.

Parameters

index the index of the entry in the queue to fetch. Valid values are 0 (front of the queue) to (queue size - 1).

Returns: Pointer reference to the queue entry.

Exceptions

D2QueueMgrInvalidIndex if the given index is beyond the end of the queue.

Definition at line 203 of file d2_queue_mgr.cc.

References getQueueSize(), and isc_throw.

Here is the call graph for this function:

◆ removeListener()

void isc::d2::D2QueueMgr::removeListener ( )

Deletes the current listener.

This method will delete the current listener and returns the manager to the NOT_INITTED state. This is provided to support reconfiguring a new listener without losing queued requests.

Exceptions

D2QueueMgrError if called when the manager state is RUNNING.

Definition at line 181 of file d2_queue_mgr.cc.

References isc_throw, NOT_INITTED, and RUNNING.

◆ setMaxQueueSize()

void isc::d2::D2QueueMgr::setMaxQueueSize ( const size_t max_queue_size )

Sets the maximum number of entries allowed in the queue.

Parameters

max_queue_size is the new maximum size of the queue.

Exceptions

D2QueueMgrError if the new value is less than one or if the new value is less than the number of entries currently in the queue.

Definition at line 246 of file d2_queue_mgr.cc.

References getQueueSize(), and isc_throw.

Referenced by D2QueueMgr().

Here is the call graph for this function:

◆ startListening()

void isc::d2::D2QueueMgr::startListening ( )

Starts actively listening for requests.

Invokes the listener's startListening method passing in our IOService instance.

Exceptions

D2QueueMgrError if the listener has not been initialized, state is already RUNNING, or the listener fails to actually start.

Definition at line 117 of file d2_queue_mgr.cc.

References isc::d2::d2_logger, isc::log::DBGLVL_START_SHUT, isc::d2::DHCP_DDNS_QUEUE_MGR_STARTED, isc_throw, LOG_DEBUG, RUNNING, and isc::Exception::what().

Here is the call graph for this function:

◆ stopListening()

void isc::d2::D2QueueMgr::stopListening ( const State target_stop_state = STOPPED )

Stops listening for requests.

Invokes the listener's stopListening method which will cause it to cancel any pending IO and close its IO source. It the sets target stop state to the given value.

If there is no IO pending, the manager state is immediately set to the target stop state, otherwise the manager state is set to STOPPING.

Parameters

target_stop_state is one of the three stopped state values.

Exceptions

D2QueueMgrError if stop_state is a valid stop state.

Definition at line 145 of file d2_queue_mgr.cc.

References isc_throw, STOPPED, STOPPED_QUEUE_FULL, STOPPED_RECV_ERROR, and STOPPING.

Referenced by operator()().

Member Data Documentation

◆ MAX_QUEUE_DEFAULT

const size_t isc::d2::D2QueueMgr::MAX_QUEUE_DEFAULT = 1024

static

Maximum number of entries allowed in the request queue.

NOTE that 1024 is an arbitrary choice picked for the initial implementation.

Definition at line 135 of file d2_queue_mgr.h.

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

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ D2QueueMgr()

◆ ~D2QueueMgr()

Member Function Documentation

◆ clearQueue()

◆ dequeue()

◆ dequeueAt()

◆ enqueue()

◆ getMaxQueueSize()

◆ getMgrState()

◆ getQueueSize()

◆ initUDPListener()

◆ operator()()

◆ peek()

◆ peekAt()

◆ removeListener()

◆ setMaxQueueSize()

◆ startListening()

◆ stopListening()

Member Data Documentation

◆ MAX_QUEUE_DEFAULT