Kea: isc::util::WatchSocket Class Reference

| Kea 3.2.0-git

isc::util::WatchSocket Class Reference

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

## 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 27 of file watch_socket.cc.

References isc_throw, and SOCKET_NOT_VALID.

## ◆ ~WatchSocket()

isc::util::WatchSocket::~WatchSocket | ( |  | ) |
| virtual

Destructor.

Closes all internal resources, including the select-fd.

Definition at line 58 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 102 of file watch_socket.cc.

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

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 120 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 159 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 88 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 63 of file watch_socket.cc.

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

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 55 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 WatchSocket(), closeSocket(), isReady(), and isc::dhcp::D2ClientMgr::stopSender().

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

- watch_socket.h
- watch_socket.cc