RAII helper class that manages a socket and closes it automatically when it goes out of scope. More...

#include <sock.h>

Inheritance diagram for Sock:

Classes
struct	EqualSharedPtrSock

struct	Events
	Auxiliary requested/occurred events to wait for in `WaitMany()`. More...

struct	HashSharedPtrSock

Public Types
using	Event = uint8_t

using	EventsPerSock = std::unordered_map< std::shared_ptr< const Sock >, Events, HashSharedPtrSock, EqualSharedPtrSock >
	On which socket to wait for what events in `WaitMany()`. More...

Public Member Functions
	Sock ()=delete

	Sock (SOCKET s)
	Take ownership of an existent socket. More...

	Sock (const Sock &)=delete
	Copy constructor, disabled because closing the same socket twice is undesirable. More...

	Sock (Sock &&other)
	Move constructor, grab the socket from another object and close ours (if set). More...

virtual	~Sock ()
	Destructor, close the socket or do nothing if empty. More...

Sock &	operator= (const Sock &)=delete
	Copy assignment operator, disabled because closing the same socket twice is undesirable. More...

virtual Sock &	operator= (Sock &&other)
	Move assignment operator, grab the socket from another object and close ours (if set). More...

virtual ssize_t	Send (const void *data, size_t len, int flags) const
	send(2) wrapper. More...

virtual ssize_t	Recv (void *buf, size_t len, int flags) const
	recv(2) wrapper. More...

virtual int	Connect (const sockaddr *addr, socklen_t addr_len) const
	connect(2) wrapper. More...

virtual int	Bind (const sockaddr *addr, socklen_t addr_len) const
	bind(2) wrapper. More...

virtual int	Listen (int backlog) const
	listen(2) wrapper. More...

virtual std::unique_ptr< Sock >	Accept (sockaddr addr, socklen_t addr_len) const
	accept(2) wrapper. More...

virtual int	GetSockOpt (int level, int opt_name, void opt_val, socklen_t opt_len) const
	getsockopt(2) wrapper. More...

virtual int	SetSockOpt (int level, int opt_name, const void *opt_val, socklen_t opt_len) const
	setsockopt(2) wrapper. More...

virtual int	GetSockName (sockaddr name, socklen_t name_len) const
	getsockname(2) wrapper. More...

virtual bool	SetNonBlocking () const
	Set the non-blocking option on the socket. More...

virtual bool	IsSelectable () const
	Check if the underlying socket can be used for `select(2)` (or the `Wait()` method). More...

virtual bool	Wait (std::chrono::milliseconds timeout, Event requested, Event *occurred=nullptr) const
	Wait for readiness for input (recv) or output (send). More...

virtual bool	WaitMany (std::chrono::milliseconds timeout, EventsPerSock &events_per_sock) const
	Same as `Wait()`, but wait on many sockets within the same timeout. More...

virtual void	SendComplete (Span< const unsigned char > data, std::chrono::milliseconds timeout, CThreadInterrupt &interrupt) const
	Send the given data, retrying on transient errors. More...

virtual void	SendComplete (Span< const char > data, std::chrono::milliseconds timeout, CThreadInterrupt &interrupt) const
	Convenience method, equivalent to `SendComplete(MakeUCharSpan(data), timeout, interrupt)`. More...

virtual std::string	RecvUntilTerminator (uint8_t terminator, std::chrono::milliseconds timeout, CThreadInterrupt &interrupt, size_t max_data) const
	Read from socket until a terminator character is encountered. More...

virtual bool	IsConnected (std::string &errmsg) const
	Check if still connected. More...

bool	operator== (SOCKET s) const
	Check if the internal socket is equal to `s`. More...

Static Public Attributes
static constexpr Event	RECV = 0b001
	If passed to `Wait()`, then it will wait for readiness to read from the socket. More...

static constexpr Event	SEND = 0b010
	If passed to `Wait()`, then it will wait for readiness to send to the socket. More...

static constexpr Event	ERR = 0b100
	Ignored if passed to `Wait()`, but could be set in the occurred events if an exceptional condition has occurred on the socket or if it has been disconnected. More...

Protected Attributes
SOCKET	m_socket
	Contained socket. More...

Private Member Functions
void	Close ()
	Close `m_socket` if it is not `INVALID_SOCKET`. More...

Detailed Description

RAII helper class that manages a socket and closes it automatically when it goes out of scope.

Definition at line 26 of file sock.h.

Member Typedef Documentation

◆ Event

using Sock::Event = uint8_t

Definition at line 138 of file sock.h.

◆ EventsPerSock

using Sock::EventsPerSock = std::unordered_map<std::shared_ptr<const Sock>, Events, HashSharedPtrSock, EqualSharedPtrSock>

On which socket to wait for what events in WaitMany().

The shared_ptr is copied into the map to ensure that the Sock object is not destroyed (its destructor would close the underlying socket). If this happens shortly before or after we call poll(2) and a new socket gets created under the same file descriptor number then the report from WaitMany() will be bogus.

Definition at line 208 of file sock.h.

Constructor & Destructor Documentation

◆ Sock() [1/4]

Sock::Sock ( )

delete

◆ Sock() [2/4]

Sock::Sock ( SOCKET s )

explicit

Take ownership of an existent socket.

Definition at line 27 of file sock.cpp.

◆ Sock() [3/4]

Sock::Sock ( const Sock & )

delete

Copy constructor, disabled because closing the same socket twice is undesirable.

◆ Sock() [4/4]

Sock::Sock ( Sock && other )

Move constructor, grab the socket from another object and close ours (if set).

Definition at line 29 of file sock.cpp.

◆ ~Sock()

Sock::~Sock ( )

virtual

Destructor, close the socket or do nothing if empty.

Definition at line 35 of file sock.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ Accept()

std::unique_ptr< Sock > Sock::Accept	(	sockaddr *	addr,
		socklen_t *	addr_len
	)		const

virtual

accept(2) wrapper.

Equivalent to std::make_unique<Sock>(accept(m_socket, addr, addr_len)). Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation. The returned unique_ptr is empty if accept() failed in which case errno will be set.

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 70 of file sock.cpp.

◆ Bind()

int Sock::Bind	(	const sockaddr *	addr,
		socklen_t	addr_len
	)		const

virtual

bind(2) wrapper.

Equivalent to bind(m_socket, addr, addr_len). Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 60 of file sock.cpp.

Here is the caller graph for this function:

◆ Close()

void Sock::Close ( )

private

Close m_socket if it is not INVALID_SOCKET.

Definition at line 401 of file sock.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Connect()

int Sock::Connect	(	const sockaddr *	addr,
		socklen_t	addr_len
	)		const

virtual

connect(2) wrapper.

Equivalent to connect(m_socket, addr, addrlen). Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 55 of file sock.cpp.

Here is the caller graph for this function:

◆ GetSockName()

int Sock::GetSockName	(	sockaddr *	name,
		socklen_t *	name_len
	)		const

virtual

getsockname(2) wrapper.

Equivalent to getsockname(m_socket, name, name_len). Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 106 of file sock.cpp.

Here is the caller graph for this function:

◆ GetSockOpt()

int Sock::GetSockOpt	(	int	level,
		int	opt_name,
		void *	opt_val,
		socklen_t *	opt_len
	)		const

virtual

getsockopt(2) wrapper.

Equivalent to getsockopt(m_socket, level, opt_name, opt_val, opt_len). Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 96 of file sock.cpp.

Here is the caller graph for this function:

◆ IsConnected()

bool Sock::IsConnected ( std::string & errmsg ) const

virtual

Check if still connected.

Parameters

[out] errmsg The error string, if the socket has been disconnected.

Returns: true if connected

Reimplemented in StaticContentsSock, and FuzzedSock.

Definition at line 376 of file sock.cpp.

Here is the call graph for this function:

◆ IsSelectable()

bool Sock::IsSelectable ( ) const

virtual

Check if the underlying socket can be used for select(2) (or the Wait() method).

Returns: true if selectable

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 130 of file sock.cpp.

◆ Listen()

int Sock::Listen ( int backlog ) const

virtual

listen(2) wrapper.

Equivalent to listen(m_socket, backlog). Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 65 of file sock.cpp.

◆ operator=() [1/2]

Sock & Sock::operator= ( const Sock & )

delete

Copy assignment operator, disabled because closing the same socket twice is undesirable.

◆ operator=() [2/2]

Sock & Sock::operator= ( Sock && other )

virtual

Move assignment operator, grab the socket from another object and close ours (if set).

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 37 of file sock.cpp.

Here is the call graph for this function:

◆ operator==()

bool Sock::operator== ( SOCKET s ) const

Check if the internal socket is equal to s.

Use only in tests.

Definition at line 417 of file sock.cpp.

◆ Recv()

ssize_t Sock::Recv	(	void *	buf,
		size_t	len,
		int	flags
	)		const

virtual

recv(2) wrapper.

Equivalent to recv(m_socket, buf, len, flags);. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 50 of file sock.cpp.

Here is the caller graph for this function:

◆ RecvUntilTerminator()

std::string Sock::RecvUntilTerminator	(	uint8_t	terminator,
		std::chrono::milliseconds	timeout,
		CThreadInterrupt &	interrupt,
		size_t	max_data
	)		const

virtual

Read from socket until a terminator character is encountered.

Will never consume bytes past the terminator from the socket.

Parameters

[in]	terminator	Character up to which to read from the socket.
[in]	timeout	Timeout for the entire operation.
[in]	interrupt	If this is signaled then the operation is canceled.
[in]	max_data	The maximum amount of data (in bytes) to receive. If this many bytes are received and there is still no terminator, then this method will throw an exception.

Returns: The data that has been read, without the terminating character.

Exceptions

std::runtime_error if the operation cannot be completed. In this case some bytes may have been consumed from the socket.

Definition at line 293 of file sock.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Send()

ssize_t Sock::Send	(	const void *	data,
		size_t	len,
		int	flags
	)		const

virtual

send(2) wrapper.

Equivalent to send(m_socket, data, len, flags);. Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.

Reimplemented in StaticContentsSock, and FuzzedSock.

Definition at line 45 of file sock.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SendComplete() [1/2]

void Sock::SendComplete	(	Span< const char >	data,
		std::chrono::milliseconds	timeout,
		CThreadInterrupt &	interrupt
	)		const

virtual

Convenience method, equivalent to SendComplete(MakeUCharSpan(data), timeout, interrupt).

Definition at line 286 of file sock.cpp.

Here is the call graph for this function:

◆ SendComplete() [2/2]

void Sock::SendComplete	(	Span< const unsigned char >	data,
		std::chrono::milliseconds	timeout,
		CThreadInterrupt &	interrupt
	)		const

virtual

Send the given data, retrying on transient errors.

Parameters

[in]	data	Data to send.
[in]	timeout	Timeout for the entire operation.
[in]	interrupt	If this is signaled then the operation is canceled.

Exceptions

std::runtime_error if the operation cannot be completed. In this case only some of the data will be written to the socket.

Definition at line 245 of file sock.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SetNonBlocking()

bool Sock::SetNonBlocking ( ) const

virtual

Set the non-blocking option on the socket.

Returns: true if set successfully

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 111 of file sock.cpp.

◆ SetSockOpt()

int Sock::SetSockOpt	(	int	level,
		int	opt_name,
		const void *	opt_val,
		socklen_t	opt_len
	)		const

virtual

setsockopt(2) wrapper.

Equivalent to setsockopt(m_socket, level, opt_name, opt_val, opt_len). Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock implementation.

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 101 of file sock.cpp.

◆ Wait()

bool Sock::Wait	(	std::chrono::milliseconds	timeout,
		Event	requested,
		Event *	occurred = `nullptr`
	)		const

virtual

Wait for readiness for input (recv) or output (send).

Parameters

[in]	timeout	Wait this much for at least one of the requested events to occur.
[in]	requested	Wait for those events, bitwise-or of `RECV` and `SEND`.
[out]	occurred	If not nullptr and the function returns `true`, then this indicates which of the requested events occurred (`ERR` will be added, even if not requested, if an exceptional event occurs on the socket). A timeout is indicated by return value of `true` and `occurred` being set to 0.

Returns: true on success (or timeout, if occurred of 0 is returned), false otherwise

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 139 of file sock.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ WaitMany()

bool Sock::WaitMany	(	std::chrono::milliseconds	timeout,
		EventsPerSock &	events_per_sock
	)		const

virtual

Same as Wait(), but wait on many sockets within the same timeout.

Parameters

[in]	timeout	Wait this long for at least one of the requested events to occur.
[in,out]	events_per_sock	Wait for the requested events on these sockets and set `occurred` for the events that actually occurred.

Returns: true on success (or timeout, if all what[].occurred are returned as 0), false otherwise

Reimplemented in FuzzedSock, and StaticContentsSock.

Definition at line 159 of file sock.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ ERR

constexpr Event Sock::ERR = 0b100

staticconstexpr

Ignored if passed to Wait(), but could be set in the occurred events if an exceptional condition has occurred on the socket or if it has been disconnected.

Definition at line 154 of file sock.h.

◆ m_socket

SOCKET Sock::m_socket

protected

Contained socket.

INVALID_SOCKET designates the object is empty.

Definition at line 275 of file sock.h.

◆ RECV

constexpr Event Sock::RECV = 0b001

staticconstexpr

If passed to Wait(), then it will wait for readiness to read from the socket.

Definition at line 143 of file sock.h.

◆ SEND

constexpr Event Sock::SEND = 0b010

staticconstexpr

If passed to Wait(), then it will wait for readiness to send to the socket.

Definition at line 148 of file sock.h.

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

src/util/sock.h
src/util/sock.cpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Attributes

Private Member Functions

Detailed Description

Member Typedef Documentation

◆ Event

◆ EventsPerSock

Constructor & Destructor Documentation

◆ Sock() [1/4]

◆ Sock() [2/4]

◆ Sock() [3/4]

◆ Sock() [4/4]

◆ ~Sock()

Member Function Documentation

◆ Accept()

◆ Bind()

◆ Close()

◆ Connect()

◆ GetSockName()

◆ GetSockOpt()

◆ IsConnected()

◆ IsSelectable()

◆ Listen()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ Recv()

◆ RecvUntilTerminator()

◆ Send()

◆ SendComplete() [1/2]

◆ SendComplete() [2/2]

◆ SetNonBlocking()

◆ SetSockOpt()

◆ Wait()

◆ WaitMany()

Member Data Documentation

◆ ERR

◆ m_socket

◆ RECV

◆ SEND