Kea  2.1.7-git
isc::util::io::SocketSessionForwarder Class Reference

The forwarder of socket sessions. More...

#include <socketsession.h>

+ Inheritance diagram for isc::util::io::SocketSessionForwarder:

Classes

struct  ForwarderImpl
 

Public Member Functions

 SocketSessionForwarder (const std::string &unix_file)
 The constructor. More...
 
virtual ~SocketSessionForwarder ()
 The destructor. More...
 
virtual void close ()
 Close the connection to the receiver. More...
 
virtual void connectToReceiver ()
 Establish a connection to the receiver. More...
 
virtual void push (int sock, int family, int type, int protocol, const struct sockaddr &local_end, const struct sockaddr &remote_end, const void *data, size_t data_len)
 Forward a socket session to the receiver. More...
 
- Public Member Functions inherited from isc::util::io::BaseSocketSessionForwarder
virtual ~BaseSocketSessionForwarder ()
 

Additional Inherited Members

- Protected Member Functions inherited from isc::util::io::BaseSocketSessionForwarder
 BaseSocketSessionForwarder ()
 

Detailed Description

The forwarder of socket sessions.

An object of this class maintains a UNIX domain socket (normally expected to be connected to a SocketSessionReceiver object) and forwards socket sessions to the receiver.

See the description of Socket session utility for other details of how the session forwarding works.

Definition at line 194 of file socketsession.h.

Constructor & Destructor Documentation

◆ SocketSessionForwarder()

isc::util::io::SocketSessionForwarder::SocketSessionForwarder ( const std::string &  unix_file)
explicit

The constructor.

It's constructed with path information of the intended receiver, but does not immediately establish a connection to the receiver; connectToReceiver() must be called to establish it. These are separated so that an object of class can be initialized (possibly as an attribute of a higher level application class object) without knowing the receiver is ready for accepting new forwarders. The separate connect interface allows the object to be reused when it detects connection failure and tries to re-establish it after closing the failed one.

On construction, it also installs a signal filter for SIGPIPE to ignore it. Since this class uses a stream-type connected UNIX domain socket, if the receiver (abruptly) closes the connection a subsequent write operation on the socket would trigger a SIGPIPE signal, which kills the caller process by default. This behavior would be undesirable in many cases, so this implementation always disables the signal.

This approach has some drawbacks, however; first, since signal handling is process (or thread) wide, ignoring it may not what the application wants. On the other hand, if the application changes how the signal is handled after instantiating this class, the new behavior affects the class operation. Secondly, even if ignoring the signal is the desired operation, it's a waste to set the filter every time this class object is constructed. It's sufficient to do it once. We still adopt this behavior based on the observation that in most cases applications would like to ignore SIGPIPE (or simply doesn't care about it) and that this class is not instantiated so often (so the wasteful setting overhead should be marginal). On the other hand, doing it every time is beneficial if the application is threaded and different threads create different forwarder objects (and if signals work per thread).

Exceptions
SocketSessionErrorunix_file is invalid as a path name of a UNIX domain socket.
UnexpectedError in setting a filter for SIGPIPE (see above)
std::bad_allocresource allocation failure
Parameters
unix_filePath name of the receiver.

Definition at line 89 of file socketsession.cc.

References isc::util::io::SocketSessionForwarder::ForwarderImpl::fd_, isc::flex_option::impl, isc_throw, isc_throw_assert, isc::util::io::SocketSessionForwarder::ForwarderImpl::sock_un_, and isc::util::io::SocketSessionForwarder::ForwarderImpl::sock_un_len_.

◆ ~SocketSessionForwarder()

isc::util::io::SocketSessionForwarder::~SocketSessionForwarder ( )
virtual

The destructor.

If a connection has been established, it's automatically closed in the destructor.

Definition at line 123 of file socketsession.cc.

References close(), and isc::util::io::SocketSessionForwarder::ForwarderImpl::fd_.

+ Here is the call graph for this function:

Member Function Documentation

◆ close()

void isc::util::io::SocketSessionForwarder::close ( )
virtual

Close the connection to the receiver.

The connection must have been established by connectToReceiver(). As long as it's met this method is exception free.

Exceptions
BadValueThe connection hasn't been established.

Implements isc::util::io::BaseSocketSessionForwarder.

Definition at line 179 of file socketsession.cc.

References isc::util::io::SocketSessionForwarder::ForwarderImpl::fd_, and isc_throw.

Referenced by connectToReceiver(), and ~SocketSessionForwarder().

◆ connectToReceiver()

void isc::util::io::SocketSessionForwarder::connectToReceiver ( )
virtual

Establish a connection to the receiver.

This method establishes a connection to the receiver at the path given on construction. It makes the underlying UNIX domain socket non blocking, so this method (or subsequent push() calls) does not block.

Exceptions
BadValueThe method is called while an already established connection is still active.
SocketSessionErrorA system error in socket operation.

Implements isc::util::io::BaseSocketSessionForwarder.

Definition at line 131 of file socketsession.cc.

References close(), isc::util::io::internal::convertSockAddr(), isc::util::io::SocketSessionForwarder::ForwarderImpl::fd_, isc_throw, isc::util::io::SocketSessionForwarder::ForwarderImpl::sock_un_, isc::util::io::SocketSessionForwarder::ForwarderImpl::sock_un_len_, and isc::util::io::SOCKSESSION_BUFSIZE.

+ Here is the call graph for this function:

◆ push()

void isc::util::io::SocketSessionForwarder::push ( int  sock,
int  family,
int  type,
int  protocol,
const struct sockaddr &  local_end,
const struct sockaddr &  remote_end,
const void *  data,
size_t  data_len 
)
virtual

Forward a socket session to the receiver.

This method takes a set of parameters that represent a single socket session, renders them in the "wire" format according to the internal protocol (see Socket session utility) and forwards them to the receiver through the UNIX domain connection.

The connection must have been established by connectToReceiver().

For simplicity and for the convenience of detecting application errors, this method imposes some restrictions on the parameters:

  • Socket family must be either AF_INET or AF_INET6
  • The address family (sa_family) member of the local and remote end points must be equal to the family parameter
  • Socket session data must not be empty (data_len must not be 0 and data must not be NULL)
  • Data length must not exceed 65535 These are not architectural limitation, and might be loosened in future versions as we see the need for flexibility.

Since the underlying UNIX domain socket is non blocking (see the description for the constructor), a call to this method should either return immediately or result in exception (in case of "would block").

Exceptions
BadValueThe method is called before establishing a connection or given parameters are invalid.
SocketSessionErrorA system error in socket operation, including the case where the write operation would block.
Parameters
sockThe socket file descriptor
familyThe address family (such as AF_INET6) of the socket
typeThe socket type (such as SOCK_DGRAM) of the socket
protocolThe transport protocol (such as IPPROTO_UDP) of the socket
local_endThe local end point of the session in the form of sockaddr.
remote_endThe remote end point of the session in the form of sockaddr.
dataA pointer to the beginning of the memory region for the session data
data_lenThe size of the session data in bytes.

Implements isc::util::io::BaseSocketSessionForwarder.

Definition at line 188 of file socketsession.cc.

References isc::util::io::SocketSessionForwarder::ForwarderImpl::buf_, isc::util::OutputBuffer::clear(), isc::util::io::SocketSessionForwarder::ForwarderImpl::fd_, isc::util::OutputBuffer::getData(), isc::util::OutputBuffer::getLength(), isc::util::io::internal::getSALength(), isc_throw, isc_throw_assert, isc::util::io::send_fd(), isc::util::OutputBuffer::skip(), isc::util::OutputBuffer::writeData(), isc::util::OutputBuffer::writeUint16At(), and isc::util::OutputBuffer::writeUint32().

+ Here is the call graph for this function:

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