Kea: isc::d2::D2QueueMgr Class Reference

| Kea 3.2.0-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:
[legend]

## Public Types
enum | State : uint16_t { NOT_INITTED = 0 , INITTED = 1 , RUNNING = 2 , STOPPING = 3 , STOPPED_QUEUE_FULL = 4 , STOPPED_RECV_ERROR = 5 , STOPPED = 6 }
| 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 ()

## Static Public Member Functions
static std::string const & | stateToText (State const &state)
| Convert enum to string.

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

## Member Enumeration Documentation

## ◆ State

enum isc::d2::D2QueueMgr::State : uint16_t

Defines the list of possible states for D2QueueMgr.

Enumerator
NOT_INITTED |
INITTED |
RUNNING |
STOPPING |
STOPPED_QUEUE_FULL |
STOPPED_RECV_ERROR |
STOPPED |

Definition at line 139 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 21 of file d2_queue_mgr.cc.

References isc_throw, NOT_INITTED, and setMaxQueueSize().

Here is the call graph for this function:

## ◆ ~D2QueueMgr()

isc::d2::D2QueueMgr::~D2QueueMgr | ( |  | ) |
| virtual

Destructor.

Definition at line 32 of file d2_queue_mgr.cc.

## Member Function Documentation

## ◆ clearQueue()

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

Removes all entries from the queue.

Definition at line 245 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 230 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 218 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 240 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 270 of file d2_queue_mgr.h.

Referenced by operator()().

## ◆ getMgrState()

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

Returns the current state.

Definition at line 284 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 265 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 103 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 36 of file d2_queue_mgr.cc.

References isc::stats::StatsMgr::addValue(), 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(), isc::stats::StatsMgr::instance(), LOG_DEBUG, LOG_ERROR, stateToText(), 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 197 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 207 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 185 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 250 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 121 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:

## ◆ stateToText()

std::string const & isc::d2::D2QueueMgr::stateToText | ( | State const & | state | ) |
| inlinestatic

Convert enum to string.

Parameters

  state | input enum

Returns
  reference to static string

Definition at line 154 of file d2_queue_mgr.h.

Referenced by operator()().

## ◆ 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 149 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 136 of file d2_queue_mgr.h.

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

- d2_queue_mgr.h
- d2_queue_mgr.cc