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

#include <ping_channel.h>

Inheritance diagram for isc::ping_check::PingChannel:

Public Member Functions
	PingChannel (asiolink::IOServicePtr &io_service, NextToSendCallback next_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 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.

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.

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:

next_to_send_cb_ - callback to invoke to fetch the next address to ping
echo_sent_cb_ - callback to invoke when an ECHO REQUEST has been sent out
reply_received_cb_ - callback to invoke when an ICMP reply has been received.
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 103 of file ping_channel.h.

Constructor & Destructor Documentation

◆ PingChannel()

isc::ping_check::PingChannel::PingChannel	(	asiolink::IOServicePtr &	io_service,
		NextToSendCallback	next_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 IOAddress to ping
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_, sending_, shutdown_cb_, single_threaded_, socket_, stopping_, and watch_socket_.

◆ ~PingChannel()

isc::ping_check::PingChannel::~PingChannel ( )

virtual

Destructor.

Closes the socket if its open.

Definition at line 57 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 signalled 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 175 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 181 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 296 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 286 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 112 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 192 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 456 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 451 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 162 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 106 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 62 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_, 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):

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

Definition at line 311 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, sending_, socketWriteCallback(), and stopChannel().

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:

Unpacks the wire data
Pass the resultant ICMPMsg to reply received callback
start next read

On error conditions:

Operation aborted: socket is shutting down, simply return
Operation would block/try again: start a new read
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 220 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:

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

On error conditions:

Operation aborted: socket is shutting down, simply return
Operation would block/try again: start a new write
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 361 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 298 of file ping_channel.cc.

References canRead(), io_service_, and mutex_.

Here is the call graph for this function:

◆ startSend()

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

virtual

Definition at line 285 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 156 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 322 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 334 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 316 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 349 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 address to ping.

Definition at line 319 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 340 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 362 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 359 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 337 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 325 of file ping_channel.h.

Referenced by PingChannel(), and socketReadCallback().

◆ sending_

bool isc::ping_check::PingChannel::sending_

protected

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

Definition at line 343 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 328 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 353 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 331 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 346 of file ping_channel.h.

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

◆ watch_socket_

util::WatchSocketPtr isc::ping_check::PingChannel::watch_socket_

protected

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

Definition at line 356 of file ping_channel.h.

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

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

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PingChannel()

◆ ~PingChannel()

Member Function Documentation

◆ asyncReceive()

◆ asyncSend()

◆ canRead()

◆ canSend()

◆ close()

◆ doRead()

◆ getInputBufData()

◆ getInputBufSize()

◆ getIOService()

◆ isOpen()

◆ nextEchoInstanceNum()

◆ open()

◆ sendNext()

◆ socketReadCallback()

◆ socketWriteCallback()

◆ startRead()

◆ startSend()

◆ stopChannel()

Member Data Documentation

◆ echo_sent_cb_

◆ input_buf_

◆ io_service_

◆ mutex_

◆ next_to_send_cb_

◆ reading_

◆ registered_read_fd_

◆ registered_write_fd_

◆ reply_endpoint_

◆ reply_received_cb_

◆ sending_

◆ shutdown_cb_

◆ single_threaded_

◆ socket_

◆ stopping_

◆ watch_socket_