Kea: isc::ping_check::PingChannel Class Reference

| Kea 3.2.0-git

isc::ping_check::PingChannel Class Reference

Provides thread-safe ICMP ECHO REQUEST/ECHO REPLY service. More...

`#include <ping_channel.h>`

Inheritance diagram for isc::ping_check::PingChannel:
[legend]

## Public Member Functions
| PingChannel (asiolink::IOServicePtr &io_service, NextToSendCallback next_to_send_cb, UpdateToSendCallback update_to_send_cb, EchoSentCallback echo_sent_cb, ReplyReceivedCallback reply_received_cb, ShutdownCallback shutdown_cb=ShutdownCallback())
| Constructor.
virtual | ~PingChannel ()
| Destructor.
void | close ()
| Closes the channel's socket.
asiolink::IOServicePtr | getIOService ()
| Fetches the channel's IOService.
bool | isOpen () const
| Indicates whether or not the channel socket is open.
void | open ()
| Opens the socket for communications.
void | startRead ()
virtual void | startSend ()

## Protected Member Functions
virtual void | asyncReceive (void *data, size_t length, size_t offset, asiolink::IOEndpoint *endpoint, SocketCallback &callback)
| Receive data on the socket asynchronously.
virtual void | asyncSend (void *data, size_t length, asiolink::IOEndpoint *endpoint, SocketCallback &callback)
| Send data on the socket asynchronously.
bool | canRead ()
| Indicates whether or not a read can be initiated.
bool | canSend ()
| Indicates whether or not a send can be initiated.
void | doRead ()
| Initiates an asynchronous socket read.
unsigned char * | getInputBufData ()
| Returns pointer to the first byte of the input buffer.
size_t | getInputBufSize () const
| Returns input buffer size.
virtual void | sendNext ()
| Initiates sending the next ECHO REQUEST.
void | socketReadCallback (boost::system::error_code ec, size_t length)
| Socket read completion callback.
void | socketWriteCallback (ICMPMsgPtr echo_sent, boost::system::error_code ec, size_t length)
| Socket write completion callback.
void | stopChannel ()
| Closes the socket channel and invokes the shutdown callback.

## Static Protected Member Functions
static uint32_t | nextEchoInstanceNum ()
| returns the next unique ECHO instance number.

## Protected Attributes
EchoSentCallback | echo_sent_cb_
| Callback to invoke when an ECHO write has completed.
std::vector< uint8_t > | input_buf_
| Buffer to hold the contents for most recent socket read.
asiolink::IOServicePtr | io_service_
| IOService instance the drives socket IO.
const boost::scoped_ptr< std::mutex > | mutex_
| The mutex used to protect internal state.
NextToSendCallback | next_to_send_cb_
| Callback to invoke to fetch the next context with target address to ping.
bool | reading_
| Indicates whether or not the socket has a read in progress.
int | registered_read_fd_
| ICMPSocket fd registered with IfaceMgr.
int | registered_write_fd_
| WatchSocket fd registered with IfaceMgr.
ICMPEndpoint | reply_endpoint_
| Retains the endpoint from which the most recent reply was received.
ReplyReceivedCallback | reply_received_cb_
| Callback to invoke when an ICMP reply has been received.
const boost::scoped_ptr< std::mutex > | send_mutex_
| The mutex used to protect internal state on send events.
bool | sending_
| Indicates whether or not the socket has a write in progress.
ShutdownCallback | shutdown_cb_
| Callback to invoke when the channel has shutdown.
bool | single_threaded_
| True if channel was opened in single-threaded mode, false otherwise.
PingSocketPtr | socket_
| Socket through which to ping.
bool | stopping_
| Indicates whether or not the channel has been told to stop.
UpdateToSendCallback | update_to_send_cb_
| Callback to invoke to update selected context to SENDING state.
util::WatchSocketPtr | watch_socket_
| Pointer to WatchSocket instance supplying the "select-fd".

## Detailed Description

Provides thread-safe ICMP ECHO REQUEST/ECHO REPLY service.

PingChannel uses a PingSocket to send out ECHO REQUESTs and receive ICMP replies. It is thread-safe and can be driven either with a single-threaded IOService or a multi-threaded IOServiceThreadPool. It uses series of callbacks to perpetually send requests to target addresses and feed back replies received:

1. next_to_send_cb_ - callback to invoke to fetch the next address to ping
2. echo_sent_cb_ - callback to invoke when an ECHO REQUEST has been sent out
3. reply_received_cb_ - callback to invoke when an ICMP reply has been received.
4. channel_shutdown_cb_ - callback to invoke when the channel has shutdown

Callback handlers are supplied via the PingChannel constructor. Higher order functions are provided, that once instantiated, can be used by calling layers to control the channel (e.g. open the channel, initiate reading, initiate writing, and close the channel).

Note
  Callbacks handlers must be thread-safe if the channel is driven by an IOServiceThreadPool.

Definition at line 107 of file ping_channel.h.

## Constructor & Destructor Documentation

## ◆ PingChannel()

isc::ping_check::PingChannel::PingChannel | ( | asiolink::IOServicePtr & | io_service,
|  | NextToSendCallback | next_to_send_cb,
|  | UpdateToSendCallback | update_to_send_cb,
|  | EchoSentCallback | echo_sent_cb,
|  | ReplyReceivedCallback | reply_received_cb,
|  | ShutdownCallback | shutdown_cb = ShutdownCallback() )

Constructor.

Instantiates the channel with its socket closed.

Parameters

  io_service | pointer to the IOService instance that will manage the channel's IO. Must not be empty
  next_to_send_cb | callback to invoke to fetch the next context and its target address to ping (called outside the mutex)
  update_to_send_cb | callback to invoke to update the selected context to SENDING (called inside the mutex)
  echo_sent_cb | callback to invoke when an ECHO send has completed
  reply_received_cb | callback to invoke when an ICMP reply has been received. This callback is passed all inbound ICMP messages (e.g. ECHO REPLY, UNREACHABLE, etc...)
  shutdown_cb | callback to invoke when the channel has shutdown due to an error

Exceptions

  BadValue | if io_service is empty.

Definition at line 37 of file ping_channel.cc.

References echo_sent_cb_, input_buf_, io_service_, isc_throw, mutex_, next_to_send_cb_, reading_, registered_read_fd_, registered_write_fd_, reply_received_cb_, send_mutex_, sending_, shutdown_cb_, single_threaded_, socket_, stopping_, update_to_send_cb_, and watch_socket_.

## ◆ ~PingChannel()

isc::ping_check::PingChannel::~PingChannel | ( |  | ) |
| virtual

Destructor.

Closes the socket if its open.

Definition at line 59 of file ping_channel.cc.

References close().

Here is the call graph for this function:

## Member Function Documentation

## ◆ asyncReceive()

void isc::ping_check::PingChannel::asyncReceive | ( | void * | data,
|  | size_t | length,
|  | size_t | offset,
|  | asiolink::IOEndpoint * | endpoint,
|  | SocketCallback & | callback )
| protectedvirtual

Receive data on the socket asynchronously.

Calls the underlying socket's asyncReceive() method to read a packet of data from a remote endpoint. Arrival of the data is signaled via a call to the callback function.

This virtual function is provided as means to inject errors during read operations to facilitate testing.

Parameters

  data | buffer to receive incoming message
  length | length of the data buffer
  offset | offset into buffer where data is to be put
  endpoint | source of the communication
  callback | callback object

Definition at line 180 of file ping_channel.cc.

References socket_.

Referenced by doRead().

## ◆ asyncSend()

void isc::ping_check::PingChannel::asyncSend | ( | void * | data,
|  | size_t | length,
|  | asiolink::IOEndpoint * | endpoint,
|  | SocketCallback & | callback )
| protectedvirtual

Send data on the socket asynchronously.

Calls the underlying socket's asyncSend() method to send a packet of data from a remote endpoint. Arrival of the data is signalled via a call to the callback function.

This virtual function is provided as means to inject errors during write operations to facilitate testing.

Parameters

  data | buffer containing the data to send
  length | length of the data buffer
  endpoint | destination of the communication
  callback | callback object

Definition at line 186 of file ping_channel.cc.

References single_threaded_, socket_, and watch_socket_.

Referenced by sendNext().

## ◆ canRead()

bool isc::ping_check::PingChannel::canRead | ( |  | ) |
| inlineprotected

Indicates whether or not a read can be initiated.

Must be called in a thread-safe context

Returns
  True if the socket is open, is not attempting to stop, and is not currently reading.

Definition at line 303 of file ping_channel.h.

References reading_, socket_, and stopping_.

Referenced by doRead(), and startRead().

## ◆ canSend()

bool isc::ping_check::PingChannel::canSend | ( |  | ) |
| inlineprotected

Indicates whether or not a send can be initiated.

Must be called in a thread-safe context

Returns
  True if the socket is open, is not attempting to stop, and is not currently sending.

Definition at line 293 of file ping_channel.h.

References sending_, socket_, and stopping_.

Referenced by sendNext(), and startSend().

## ◆ close()

void isc::ping_check::PingChannel::close | ( |  | ) |

Closes the channel's socket.

Definition at line 117 of file ping_channel.cc.

References isc::log::DBGLVL_TRACE_BASIC, isc::dhcp::IfaceMgr::deleteExternalSocket(), isc::dhcp::IfaceMgr::instance(), LOG_DEBUG, LOG_ERROR, mutex_, PING_CHECK_CHANNEL_SOCKET_CLOSE_ERROR, PING_CHECK_CHANNEL_SOCKET_CLOSED, PING_CHECK_CHANNEL_WATCH_SOCKET_CLOSE_ERROR, isc::ping_check::ping_check_logger, registered_read_fd_, registered_write_fd_, single_threaded_, socket_, and watch_socket_.

Referenced by ~PingChannel(), and stopChannel().

Here is the call graph for this function:

## ◆ doRead()

void isc::ping_check::PingChannel::doRead | ( |  | ) |
| protected

Initiates an asynchronous socket read.

If the channel is able to read (is open, not stopping and not currently reading) it invokes isc::ping_check::ICMPSocket<SocketCallback>::asyncReceive() otherwise it simply returns. If the call to asyncReceive() fails it calls `stopChannel()` otherwise, when it completes it will invoke `socketReadCallback()`.

Definition at line 197 of file ping_channel.cc.

References asyncReceive(), canRead(), getInputBufData(), getInputBufSize(), LOG_ERROR, mutex_, isc::ping_check::ping_check_logger, PING_CHECK_UNEXPECTED_READ_ERROR, reading_, reply_endpoint_, socketReadCallback(), and stopChannel().

Referenced by socketReadCallback().

Here is the call graph for this function:

## ◆ getInputBufData()

unsigned char * isc::ping_check::PingChannel::getInputBufData | ( |  | ) |
| protected

Returns pointer to the first byte of the input buffer.

Must be called in a thread-safe context

Returns
  pointer to the data buffer

Exceptions

  InvalidOperation | if called when the buffer is empty.

Definition at line 475 of file ping_channel.cc.

References input_buf_, and isc_throw.

Referenced by doRead(), and socketReadCallback().

## ◆ getInputBufSize()

size_t isc::ping_check::PingChannel::getInputBufSize | ( |  | ) | const
| protected

Returns input buffer size.

Must be called in a thread-safe context

Returns
  size of the input buf

Definition at line 470 of file ping_channel.cc.

References input_buf_.

Referenced by doRead(), and socketReadCallback().

## ◆ getIOService()

asiolink::IOServicePtr isc::ping_check::PingChannel::getIOService | ( |  | ) |
| inline

Fetches the channel's IOService.

Returns
  pointer to the IOService.

Definition at line 169 of file ping_channel.h.

References io_service_.

## ◆ isOpen()

bool isc::ping_check::PingChannel::isOpen | ( |  | ) | const

Indicates whether or not the channel socket is open.

Returns
  true if the socket is open.

Definition at line 111 of file ping_channel.cc.

References mutex_, and socket_.

## ◆ nextEchoInstanceNum()

uint32_t isc::ping_check::PingChannel::nextEchoInstanceNum | ( |  | ) |
| staticprotected

returns the next unique ECHO instance number.

This method generates and returns the next ECHO instance number by incrementing the current value. It is a strictly monotonously increasing value beginning at 0x00010001. At roll over it resets to 0x00010001.

Must be called in a thread-safe context

Returns
  the next unique instance number.

Definition at line 26 of file ping_channel.cc.

References UINT32_MAX.

Referenced by sendNext().

## ◆ open()

void isc::ping_check::PingChannel::open | ( |  | ) |

Opens the socket for communications.

(Re)Creates the PingSocket instance and opens it.

Exceptions

  Unexpected | if the open fails.

Definition at line 64 of file ping_channel.cc.

References isc::dhcp::IfaceMgr::addExternalSocket(), isc::log::DBGLVL_TRACE_BASIC, isc::dhcp::IfaceMgr::instance(), io_service_, isc::asiolink::IOAddress::IPV4_ZERO_ADDRESS(), isc_throw, LOG_DEBUG, mutex_, PING_CHECK_CHANNEL_SOCKET_OPENED, isc::ping_check::ping_check_logger, reading_, registered_read_fd_, registered_write_fd_, sending_, single_threaded_, socket_, startRead(), stopping_, and watch_socket_.

Here is the call graph for this function:

## ◆ sendNext()

void isc::ping_check::PingChannel::sendNext | ( |  | ) |
| protectedvirtual

Initiates sending the next ECHO REQUEST.

If the channel is able to send (i.e is open, not stopping and not currently writing):

1. Invoke next to send callback to fetch the next target IP address
2. If there is no next target, return
3. Construct the ECHO REQUEST for the target and pack it into wire form
4. Begin sending the request by passing to `PingSocket::asyncSend()`
5. If the asyncSend() call fails shutdown the channel, otherwise when it completes it invokes `socketWriteCallback()`.

Definition at line 316 of file ping_channel.cc.

References asyncSend(), canSend(), isc::ping_check::ICMPMsg::ECHO_REQUEST, LOG_ERROR, mutex_, next_to_send_cb_, nextEchoInstanceNum(), isc::ping_check::ping_check_logger, PING_CHECK_UNEXPECTED_WRITE_ERROR, send_mutex_, sending_, socketWriteCallback(), stopChannel(), and update_to_send_cb_.

Referenced by socketWriteCallback().

Here is the call graph for this function:

## ◆ socketReadCallback()

void isc::ping_check::PingChannel::socketReadCallback | ( | boost::system::error_code | ec,
|  | size_t | length )
| protected

Socket read completion callback.

Invoked when PingSocket::asyncRead() completes. Upon read success and data received:

1. Unpacks the wire data
2. Pass the resultant ICMPMsg to reply received callback
3. start next read

On error conditions:

1. Operation aborted: socket is shutting down, simply return
2. Operation would block/try again: start a new read
3. Any other error, shut down the channel

Parameters

  ec | error code indicating either success or the error encountered
  length | number of bytes read

Definition at line 225 of file ping_channel.cc.

References isc::log::DBGLVL_TRACE_BASIC, isc::log::DBGLVL_TRACE_DETAIL, doRead(), isc::ping_check::ICMPMsg::ECHO_REPLY, getInputBufData(), getInputBufSize(), LOG_DEBUG, LOG_ERROR, mutex_, PING_CHECK_CHANNEL_ECHO_REPLY_RECEIVED, PING_CHECK_CHANNEL_MALFORMED_PACKET_RECEIVED, PING_CHECK_CHANNEL_SOCKET_READ_FAILED, isc::ping_check::ping_check_logger, reading_, reply_received_cb_, stopChannel(), stopping_, and isc::ping_check::ICMPMsg::unpack().

Referenced by doRead().

Here is the call graph for this function:

## ◆ socketWriteCallback()

void isc::ping_check::PingChannel::socketWriteCallback | ( | ICMPMsgPtr | echo_sent,
|  | boost::system::error_code | ec,
|  | size_t | length )
| protected

Socket write completion callback.

Invoked when PingSocket::asyncWrite() completes. Upon write success:

1. Pass the ECHO REQUEST (i.e. echo_sent) to echo sent callback
2. start next write

On error conditions:

1. Operation aborted: socket is shutting down, simply return
2. Operation would block/try again: start a new write
3. Any other error, shut down the channel

Parameters

  echo_sent | ECHO REQUEST that was written (or attempted to be written)
  ec | error code indicating either success or the error encountered
  length | number of bytes written

Definition at line 380 of file ping_channel.cc.

References isc::log::DBGLVL_TRACE_DETAIL, echo_sent_cb_, LOG_DEBUG, LOG_ERROR, mutex_, PING_CHECK_CHANNEL_ECHO_REQUEST_SENT, PING_CHECK_CHANNEL_NETWORK_WRITE_ERROR, PING_CHECK_CHANNEL_SOCKET_WRITE_FAILED, PING_CHECK_CHANNEL_WATCH_SOCKET_CLEAR_ERROR, isc::ping_check::ping_check_logger, sending_, sendNext(), single_threaded_, stopChannel(), stopping_, and watch_socket_.

Referenced by sendNext().

Here is the call graph for this function:

## ◆ startRead()

void isc::ping_check::PingChannel::startRead | ( |  | ) |

Definition at line 303 of file ping_channel.cc.

References canRead(), io_service_, and mutex_.

Referenced by open().

Here is the call graph for this function:

## ◆ startSend()

void isc::ping_check::PingChannel::startSend | ( |  | ) |
| virtual

Definition at line 290 of file ping_channel.cc.

References canSend(), io_service_, and mutex_.

Here is the call graph for this function:

## ◆ stopChannel()

void isc::ping_check::PingChannel::stopChannel | ( |  | ) |
| protected

Closes the socket channel and invokes the shutdown callback.

This function is invoked to notify the calling layer that the socket has encountered an unrecoverable error and is stopping operations.

Definition at line 161 of file ping_channel.cc.

References close(), isc::log::DBGLVL_TRACE_BASIC, LOG_DEBUG, mutex_, PING_CHECK_CHANNEL_STOP, isc::ping_check::ping_check_logger, shutdown_cb_, and stopping_.

Referenced by doRead(), sendNext(), socketReadCallback(), and socketWriteCallback().

Here is the call graph for this function:

## Member Data Documentation

## ◆ echo_sent_cb_

EchoSentCallback isc::ping_check::PingChannel::echo_sent_cb_
| protected

Callback to invoke when an ECHO write has completed.

Definition at line 332 of file ping_channel.h.

Referenced by PingChannel(), and socketWriteCallback().

## ◆ input_buf_

std::vector<uint8_t> isc::ping_check::PingChannel::input_buf_
| protected

Buffer to hold the contents for most recent socket read.

Definition at line 344 of file ping_channel.h.

Referenced by PingChannel(), getInputBufData(), and getInputBufSize().

## ◆ io_service_

asiolink::IOServicePtr isc::ping_check::PingChannel::io_service_
| protected

IOService instance the drives socket IO.

Definition at line 323 of file ping_channel.h.

Referenced by PingChannel(), getIOService(), open(), startRead(), and startSend().

## ◆ mutex_

const boost::scoped_ptr<std::mutex> isc::ping_check::PingChannel::mutex_
| protected

The mutex used to protect internal state.

Definition at line 359 of file ping_channel.h.

Referenced by PingChannel(), close(), doRead(), isOpen(), open(), sendNext(), socketReadCallback(), socketWriteCallback(), startRead(), startSend(), and stopChannel().

## ◆ next_to_send_cb_

NextToSendCallback isc::ping_check::PingChannel::next_to_send_cb_
| protected

Callback to invoke to fetch the next context with target address to ping.

Definition at line 326 of file ping_channel.h.

Referenced by PingChannel(), and sendNext().

## ◆ reading_

bool isc::ping_check::PingChannel::reading_
| protected

Indicates whether or not the socket has a read in progress.

Definition at line 350 of file ping_channel.h.

Referenced by PingChannel(), canRead(), doRead(), open(), and socketReadCallback().

## ◆ registered_read_fd_

int isc::ping_check::PingChannel::registered_read_fd_
| protected

ICMPSocket fd registered with IfaceMgr.

Definition at line 382 of file ping_channel.h.

Referenced by PingChannel(), close(), and open().

## ◆ registered_write_fd_

int isc::ping_check::PingChannel::registered_write_fd_
| protected

WatchSocket fd registered with IfaceMgr.

Definition at line 379 of file ping_channel.h.

Referenced by PingChannel(), close(), and open().

## ◆ reply_endpoint_

ICMPEndpoint isc::ping_check::PingChannel::reply_endpoint_
| protected

Retains the endpoint from which the most recent reply was received.

Definition at line 347 of file ping_channel.h.

Referenced by doRead().

## ◆ reply_received_cb_

ReplyReceivedCallback isc::ping_check::PingChannel::reply_received_cb_
| protected

Callback to invoke when an ICMP reply has been received.

Definition at line 335 of file ping_channel.h.

Referenced by PingChannel(), and socketReadCallback().

## ◆ send_mutex_

const boost::scoped_ptr<std::mutex> isc::ping_check::PingChannel::send_mutex_
| protected

The mutex used to protect internal state on send events.

Mutex used to do atomic read of the store entry using PingContextStore::getNextToSend and update the context from WAITING_TO_SEND state to SENDING state using PingContext::setState. Both functions (when transitioning from WAITING_TO_SEND state to SENDING state) should be called only with this mutex locked.

Definition at line 369 of file ping_channel.h.

Referenced by PingChannel(), and sendNext().

## ◆ sending_

bool isc::ping_check::PingChannel::sending_
| protected

Indicates whether or not the socket has a write in progress.

Definition at line 353 of file ping_channel.h.

Referenced by PingChannel(), canSend(), open(), sendNext(), and socketWriteCallback().

## ◆ shutdown_cb_

ShutdownCallback isc::ping_check::PingChannel::shutdown_cb_
| protected

Callback to invoke when the channel has shutdown.

Definition at line 338 of file ping_channel.h.

Referenced by PingChannel(), and stopChannel().

## ◆ single_threaded_

bool isc::ping_check::PingChannel::single_threaded_
| protected

True if channel was opened in single-threaded mode, false otherwise.

Definition at line 373 of file ping_channel.h.

Referenced by PingChannel(), asyncSend(), close(), open(), and socketWriteCallback().

## ◆ socket_

PingSocketPtr isc::ping_check::PingChannel::socket_
| protected

Socket through which to ping.

Definition at line 341 of file ping_channel.h.

Referenced by PingChannel(), asyncReceive(), asyncSend(), canRead(), canSend(), close(), isOpen(), and open().

## ◆ stopping_

bool isc::ping_check::PingChannel::stopping_
| protected

Indicates whether or not the channel has been told to stop.

Definition at line 356 of file ping_channel.h.

Referenced by PingChannel(), canRead(), canSend(), open(), socketReadCallback(), socketWriteCallback(), and stopChannel().

## ◆ update_to_send_cb_

UpdateToSendCallback isc::ping_check::PingChannel::update_to_send_cb_
| protected

Callback to invoke to update selected context to SENDING state.

Definition at line 329 of file ping_channel.h.

Referenced by PingChannel(), and sendNext().

## ◆ watch_socket_

util::WatchSocketPtr isc::ping_check::PingChannel::watch_socket_
| protected

Pointer to WatchSocket instance supplying the "select-fd".

Definition at line 376 of file ping_channel.h.

Referenced by PingChannel(), asyncSend(), close(), open(), and socketWriteCallback().

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

- ping_channel.h
- ping_channel.cc