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

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. More...
 
virtual ~D2QueueMgr ()
 Destructor. More...
 
void clearQueue ()
 Removes all entries from the queue. More...
 
void dequeue ()
 Removes the entry at the front of the queue. More...
 
void dequeueAt (const size_t index)
 Removes the entry at a given position in the queue. More...
 
void enqueue (dhcp_ddns::NameChangeRequestPtr &ncr)
 Adds a request to the end of the queue. More...
 
size_t getMaxQueueSize () const
 Returns the maximum number of entries allowed in the queue. More...
 
State getMgrState () const
 Returns the current state. More...
 
size_t getQueueSize () const
 Returns the number of entries in the queue. More...
 
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. More...
 
virtual void operator() (const dhcp_ddns::NameChangeListener::Result result, dhcp_ddns::NameChangeRequestPtr &ncr)
 Function operator implementing the NCR receive callback. More...
 
const dhcp_ddns::NameChangeRequestPtrpeek () const
 Returns the entry at the front of the queue. More...
 
const dhcp_ddns::NameChangeRequestPtrpeekAt (const size_t index) const
 Returns the entry at a given position in the queue. More...
 
void removeListener ()
 Deletes the current listener. More...
 
void setMaxQueueSize (const size_t max_queue_size)
 Sets the maximum number of entries allowed in the queue. More...
 
void startListening ()
 Starts actively listening for requests. More...
 
void stopListening (const State target_stop_state=STOPPED)
 Stops listening for requests. More...
 
- Public Member Functions inherited from isc::dhcp_ddns::NameChangeListener::RequestReceiveHandler
virtual ~RequestReceiveHandler ()
 

Static Public Attributes

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

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 131 of file d2_queue_mgr.h.

Member Enumeration Documentation

◆ 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 140 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_serviceIOService instance to be passed into the listener for IO management.
max_queue_sizethe maximum number of entries allowed in the queue. This value must be greater than zero. It defaults to MAX_QUEUE_DEFAULT.
Exceptions
D2QueueMgrErrorif 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 244 of file d2_queue_mgr.cc.

◆ dequeue()

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

Removes the entry at the front of the queue.

Exceptions
D2QueueMgrQueueEmptyif there are no entries in the queue.

Definition at line 229 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
indexthe index of the entry in the queue to remove. Valid values are 0 (front of the queue) to (queue size - 1).
Exceptions
D2QueueMgrInvalidIndexif the given index is beyond the end of the queue.

Definition at line 216 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
ncrpointer to the NameChangeRequest to add to the queue.

Definition at line 239 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 253 of file d2_queue_mgr.h.

Referenced by operator()().

◆ getMgrState()

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

Returns the current state.

Definition at line 267 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 248 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_addressis the network address on which to listen
portis the IP port on which to listen
formatis the wire format of the inbound requests.
reuse_addressenables 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
resultcontains that receive outcome status.
ncris 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
D2QueueMgrQueueEmptyif there are no entries in the queue.

Definition at line 195 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
indexthe 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
D2QueueMgrInvalidIndexif the given index is beyond the end of the queue.

Definition at line 205 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
D2QueueMgrErrorif called when the manager state is RUNNING.

Definition at line 183 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_sizeis the new maximum size of the queue.
Exceptions
D2QueueMgrErrorif 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 249 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
D2QueueMgrErrorif the listener has not been initialized, state is already RUNNING, or the listener fails to actually start.

Definition at line 118 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_stateis one of the three stopped state values.
Exceptions
D2QueueMgrErrorif stop_state is a valid stop state.

Definition at line 146 of file d2_queue_mgr.cc.

References isc::d2::d2_logger, isc::log::DBGLVL_TRACE_BASIC, isc::d2::DHCP_DDNS_QUEUE_MGR_STOPPED, isc_throw, LOG_DEBUG, 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 137 of file d2_queue_mgr.h.


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