Provides an IO "ready" semaphore for use with select() or poll() WatchSocket exposes a single open file descriptor, the "select-fd" which can be marked as being ready to read (i.e. More...

#include <watch_socket.h>

Inheritance diagram for isc::util::WatchSocket:

Public Member Functions
	WatchSocket ()
	Constructor.

virtual	~WatchSocket ()
	Destructor.

void	clearReady ()
	Clears the socket's ready to read marker.

bool	closeSocket (std::string &error_string)
	Closes the descriptors associated with the socket.

int	getSelectFd ()
	Returns the file descriptor to use to monitor the socket.

bool	isReady ()
	Returns true the if socket is marked as ready.

void	markReady ()
	Marks the select-fd as ready to read.

Static Public Attributes
static const uint32_t	MARKER = 0xDEADBEEF
	Value written to the source when marking the socket as ready.

static const int	SOCKET_NOT_VALID = -1
	Value used to signify an invalid descriptor.

Detailed Description

Provides an IO "ready" semaphore for use with select() or poll() WatchSocket exposes a single open file descriptor, the "select-fd" which can be marked as being ready to read (i.e.

!EWOULDBLOCK) and cleared (i.e. EWOULDBLOCK). The select-fd can be used with select(), poll(), or their variants alongside other file descriptors.

Internally, WatchSocket uses a pipe. The select-fd is the "read" end of pipe. To mark the socket as ready to read, an integer marker is written to the pipe. To clear the socket, the marker is read from the pipe. Note that WatchSocket will only write the marker if it is not already marked. This prevents the socket's pipe from filling endlessly.

Warning: Because the read or "sink" side of the pipe is used as the select_fd, it is possible for that fd to be interfered with, albeit only from within the process space which owns it. Performing operations that may alter the fd's state such as close, read, or altering behavior flags with fcntl or ioctl can have unpredictable results. It is intended strictly use with functions such as select() poll() or their variants.

Definition at line 47 of file watch_socket.h.

Constructor & Destructor Documentation

◆ WatchSocket()

isc::util::WatchSocket::WatchSocket ( )

Constructor.

Constructs an instance of the WatchSocket in the cleared (EWOULDBLOCK) state.

Definition at line 28 of file watch_socket.cc.

References isc_throw.

◆ ~WatchSocket()

isc::util::WatchSocket::~WatchSocket ( )

virtual

Destructor.

Closes all internal resources, including the select-fd.

Definition at line 59 of file watch_socket.cc.

References closeSocket().

Here is the call graph for this function:

Member Function Documentation

◆ clearReady()

void isc::util::WatchSocket::clearReady ( )

Clears the socket's ready to read marker.

Clears the socket if it is currently marked as ready to read. If an error occurs, closeSocket is called. This will force any further use of the select_fd to fail rather than show the fd as READY. Such an error is almost surely a programmatic error which has corrupted the select_fd.

Exceptions

WatchSocketError if an error occurs clearing the socket marker.

Definition at line 103 of file watch_socket.cc.

References closeSocket(), isc_throw, isReady(), and MARKER.

Referenced by isc::util::WatchedThread::clearReady().

Here is the call graph for this function:

◆ closeSocket()

bool isc::util::WatchSocket::closeSocket ( std::string & error_string )

Closes the descriptors associated with the socket.

This method is used to close the socket and capture errors that may occur during this operation.

Parameters

[out] error_string Holds the error string if closing the socket failed. It will hold empty string otherwise.

Returns: true if the operation was successful, false otherwise.

Definition at line 121 of file watch_socket.cc.

References SOCKET_NOT_VALID.

Referenced by ~WatchSocket(), clearReady(), and markReady().

◆ getSelectFd()

int isc::util::WatchSocket::getSelectFd ( )

Returns the file descriptor to use to monitor the socket.

Note: Using this file descriptor as anything other than an argument to select() or similar methods can have unpredictable results.

Returns: The file descriptor associated with read end of the socket's pipe.

Definition at line 160 of file watch_socket.cc.

◆ isReady()

bool isc::util::WatchSocket::isReady ( )

Returns true the if socket is marked as ready.

This method uses a non-blocking call to select() to test read state of the select_fd. Rather than track what the status "should be" it tests the status. This should eliminate conditions where the select-fd appear to be perpetually ready.

Returns: Returns true if select_fd is not SOCKET_NOT_VALID and select() reports it as !EWOULDBLOCK, otherwise it returns false. This method is guaranteed NOT to throw.

Definition at line 89 of file watch_socket.cc.

References SOCKET_NOT_VALID.

Referenced by clearReady(), and markReady().

◆ markReady()

void isc::util::WatchSocket::markReady ( )

Marks the select-fd as ready to read.

Marks the socket as ready to read, if is not already so marked. If an error occurs, closeSocket is called. This will force any further use of the select_fd to fail rather than show the fd as READY. Such an error is almost surely a programmatic error which has corrupted the select_fd.

Exceptions

WatchSocketError if an error occurs marking the socket.

Definition at line 64 of file watch_socket.cc.

References closeSocket(), isc_throw, isReady(), and MARKER.

Referenced by isc::util::WatchedThread::markReady().

Here is the call graph for this function:

Member Data Documentation

◆ MARKER

const uint32_t isc::util::WatchSocket::MARKER = 0xDEADBEEF

static

Value written to the source when marking the socket as ready.

The value itself is arbitrarily chosen as one that is unlikely to occur otherwise and easy to debug.

Definition at line 54 of file watch_socket.h.

Referenced by clearReady(), and markReady().

◆ SOCKET_NOT_VALID

const int isc::util::WatchSocket::SOCKET_NOT_VALID = -1

static

Value used to signify an invalid descriptor.

Definition at line 50 of file watch_socket.h.

Referenced by closeSocket(), isReady(), and isc::dhcp::D2ClientMgr::stopSender().

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

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ WatchSocket()

◆ ~WatchSocket()

Member Function Documentation

◆ clearReady()

◆ closeSocket()

◆ getSelectFd()

◆ isReady()

◆ markReady()

Member Data Documentation

◆ MARKER

◆ SOCKET_NOT_VALID