The rsocket multiplexer extends the functionality of the rsocket class primarily for handling multiple sockets that are beyond the scope of the single-socket-focused nature of rsocket. More...

#include <randolf/rsocket_mux>

Collaboration diagram for randolf::rsocket_mux:

Public Member Functions
	rsocket_mux () noexcept
	Instantiate an rsocket multiplexer with no rsocket objects.
template<class R, class... Rs>
	rsocket_mux (const int fd_sets, R r, Rs... rs) noexcept
	Instantiate an rsocket multiplexer with any number of rsocket objects.
	rsocket_mux (const int fd_sets, rsocket *r) noexcept
	Instantiate an rsocket multiplexer with one rsocket object.
rsocket_mux &	erase (const int fd_sets, rsocket *r) noexcept
	Remove an rsocket object from the underlying std::set.
rsocket_mux &	erase (rsocket_mux_fds rmf)
	Remove an rsocket object from the underlying std::set.
template<class R, class... Rs>
rsocket_mux &	insert (const int fd_sets, R r, Rs... rs)
	Add one or more rsocket objects to the underlying std::set.
rsocket_mux &	insert (const int fd_sets, rsocket *r)
	Add one rsocket object to the underlying std::set.
std::vector< rsocket_mux_fds >	poll (const int timeout=0, const bool timeout_behaviour=rsocket::TIMEOUT_EXCEPTION)
	Use the poll() method on the internal set of instantiated rsocket objects.
std::vector< rsocket_mux_fds >	ppoll (const struct timespec tmo_p=nullptr, const sigset_t sigmask=nullptr, const bool timeout_behaviour=rsocket::TIMEOUT_EXCEPTION)
	Use the ppoll() method on the internal set of instantiated rsocket objects.
std::vector< rsocket_mux_fds >	pselect (const struct timespec tmo_p=nullptr, const sigset_t sigmask=nullptr, const bool timeout_behaviour=rsocket::TIMEOUT_EXCEPTION)
	Use the pselect() method on the internal set of instantiated rsocket objects.
std::vector< rsocket_mux_fds >	select (struct timeval *tv=nullptr, const bool timeout_behaviour=rsocket::TIMEOUT_EXCEPTION)
	Use the select() method on the internal set of instantiated rsocket objects.
size_t	size () noexcept
	Find out how many rsocket entries are in this mux.

Detailed Description

The rsocket multiplexer extends the functionality of the rsocket class primarily for handling multiple sockets that are beyond the scope of the single-socket-focused nature of rsocket.

Functionality of select(), poll(), and related socket functions are implemented within this separate rsocket_mux class partly because these specializations are beyond the scope of what the rsocket class is intended for.

Threads: This class is threadsafe.

Author: Randolf Richardson

Version: 1.00

History

2022-Dec-24 v1.00 Initial version
2025-Feb-03 v1.00 Increased use of references and pointers
2025-Apr-05 v1.00 Added some docuemntation

Constructor & Destructor Documentation

◆ rsocket_mux() [1/3]

randolf::rsocket_mux::rsocket_mux ( )

inlinenoexcept

Instantiate an rsocket multiplexer with no rsocket objects.

See also: insert()

Referenced by erase(), erase(), insert(), and insert().

◆ rsocket_mux() [2/3]

randolf::rsocket_mux::rsocket_mux	(	const int	fd_sets,
		rsocket *	r )

inlinenoexcept

Instantiate an rsocket multiplexer with one rsocket object.

The following fd_sets correspond with each respective POSIX select() fd_set, which can be combined to include the specified rsocket in multiple fd_sets:

POLLIN = readfds
POLLOUT = writefds
POLLERR = exceptfds

See also: insert()

Parameters

fd_sets	Must be at least one of `POLLIN`, `POLLOUT`, and `POLLERR`
r	Pointer to instantiated rsocket object

◆ rsocket_mux() [3/3]

template<class R, class... Rs>

randolf::rsocket_mux::rsocket_mux	(	const int	fd_sets,
		R	r,
		Rs...	rs )

inlinenoexcept

Instantiate an rsocket multiplexer with any number of rsocket objects.

The following fd_sets correspond with each respective POSIX select() fd_set, which can be combined to include the specified rsocket in multiple fd_sets:

POLLIN = readfds
POLLOUT = writefds
POLLERR = exceptfds

See also: insert()

Parameters

fd_sets	Must be at least one of `POLLIN`, `POLLOUT`, and `POLLERR`
r	Pointer to instantiated rsocket object
rs	Variadic arguments (any quantity of instantiated rsocket objects)

Member Function Documentation

◆ erase() [1/2]

rsocket_mux & randolf::rsocket_mux::erase	(	const int	fd_sets,
		rsocket *	r )

inlinenoexcept

Remove an rsocket object from the underlying std::set.

Threads: This method is threadsafe.

Returns: The same rsocket_mux object so as to facilitate stacking

Parameters

fd_sets	Must be at least one of `POLLIN`, `POLLOUT`, and `POLLERR`
r	Pointer to instantiated rsocket object

References rsocket_mux().

◆ erase() [2/2]

rsocket_mux & randolf::rsocket_mux::erase ( rsocket_mux_fds rmf )

inline

Remove an rsocket object from the underlying std::set.

Threads: This method is threadsafe.

Returns: The same rsocket_mux object so as to facilitate stacking

Parameters

rmf	Structure that is comprised of an rsocket object and its fd_set flags

References rsocket_mux().

◆ insert() [1/2]

rsocket_mux & randolf::rsocket_mux::insert	(	const int	fd_sets,
		rsocket *	r )

inline

Add one rsocket object to the underlying std::set.

Threads: This method is threadsafe.

Returns: The same rsocket_mux object so as to facilitate stacking

Parameters

fd_sets	Must be at least one of `POLLIN`, `POLLOUT`, and `POLLERR`
r	Pointer to instantiated rsocket object

References rsocket_mux().

◆ insert() [2/2]

template<class R, class... Rs>

rsocket_mux & randolf::rsocket_mux::insert	(	const int	fd_sets,
		R	r,
		Rs...	rs )

inline

Add one or more rsocket objects to the underlying std::set.

Threads: This method is threadsafe.

Returns: The same rsocket_mux object so as to facilitate stacking

Parameters

fd_sets	Must be at least one of `POLLIN`, `POLLOUT`, and `POLLERR`
r	Pointer to instantiated rsocket object
rs	Variadic arguments (any quantity of instantiated rsocket objects)

References rsocket_mux().

◆ poll()

std::vector< rsocket_mux_fds > randolf::rsocket_mux::poll	(	const int	timeout = 0,
		const bool	timeout_behaviour = rsocket::TIMEOUT_EXCEPTION )

inline

Use the poll() method on the internal set of instantiated rsocket objects.

Threads: This method is not threadsafe. Calls to insert() and erase() during this blocking operation will almost certainly yield unpredictable results.

Exceptions

randolf::rex::xEAGAIN	Failure to allocate internal system resources
randolf::rex::xEFAULT	Address structure/memory is not in a writable part of the user address space
randolf::rex::xEINTR	Interrupted by a signal
randolf::rex::xENOMEM	Insufficient memory
randolf::rex::xENOTSOCK	Underlying socket file descriptor (handle) doesn't refer to a socket
randolf::rex::xETIMEDOUT	Timeout period elapsed (even if the `TIMEOUT_BEHAVIOUR` flag is not set to `TIMEOUT_EXCEPTION`, there is a highly improbable chance that a timeout could still occur if the data is read from any of the sockets in this rsocket_mux collection by another thread before the recv(..., MSG_PEEK) call)

Returns: An std::vector<socket_mux_fds> that holds only those sockets that were selected

Parameters

timeout	Number of milliseconds to wait
timeout_behaviour	Timeout behaviour (see rsocket::TIMEOUT_BEHAVIOUR for details)

References poll(), randolf::rex::rex::REX_ALT_EAGAIN, randolf::rex::rex::REX_FIND_ERRNO, and randolf::rsocket::TIMEOUT_EXCEPTION.

Referenced by poll().

◆ ppoll()

std::vector< rsocket_mux_fds > randolf::rsocket_mux::ppoll	(	const struct timespec *	tmo_p = nullptr,
		const sigset_t *	sigmask = nullptr,
		const bool	timeout_behaviour = rsocket::TIMEOUT_EXCEPTION )

inline

Use the ppoll() method on the internal set of instantiated rsocket objects.

Threads: This method is not threadsafe. Calls to insert() and erase() during this blocking operation will almost certainly yield unpredictable results.

Exceptions

randolf::rex::xEAGAIN	Failure to allocate internal system resources
randolf::rex::xEFAULT	Address structure/memory is not in a writable part of the user address space
randolf::rex::xEINTR	Interrupted by a signal
randolf::rex::xENOMEM	Insufficient memory
randolf::rex::xENOTSOCK	Underlying socket file descriptor (handle) doesn't refer to a socket
randolf::rex::xETIMEDOUT	Timeout period elapsed (even if the `TIMEOUT_BEHAVIOUR` flag is not set to `TIMEOUT_EXCEPTION`, there is a highly improbable chance that a timeout could still occur if the data is read from any of the sockets in this rsocket_mux collection by another thread before the recv(..., MSG_PEEK) call)

Returns: An std::vector<socket_mux_fds> that holds only those sockets that were selected

Parameters

tmo_p	Pointer to a `timespec` structure (will not be updated)
sigmask	Signal mask
timeout_behaviour	Timeout behaviour (see rsocket::TIMEOUT_BEHAVIOUR for details)

References ppoll(), randolf::rex::rex::REX_ALT_EAGAIN, randolf::rex::rex::REX_FIND_ERRNO, and randolf::rsocket::TIMEOUT_EXCEPTION.

Referenced by ppoll().

◆ pselect()

std::vector< rsocket_mux_fds > randolf::rsocket_mux::pselect	(	const struct timespec *	tmo_p = nullptr,
		const sigset_t *	sigmask = nullptr,
		const bool	timeout_behaviour = rsocket::TIMEOUT_EXCEPTION )

inline

Use the pselect() method on the internal set of instantiated rsocket objects.

Note: Performance optimization was a major consideration in the design of this method, including only testing the readiness of socket handles that were actually added to the underlying fd_set array(s).

The easier way to use this method is to only add one polling type (such as POLLIN) to the encompassing rsocket_mux object, and then all rsocket_mux_fds records returned will only be for that polling type (and then you won't have to write additional code to confirm the polling type). However, easier doesn't necessarily equate to better, and your needs and use case(s) should normally be considered in determining which approach is the most appropriate to write code for.

Warning: The underlying POSIX pselect() method is not efficient and is known to have a tendency to use a significant amount of stack memory, particularly when monitoring more sockets. The poll() and ppoll() methods serve as improvements to these problems, and are generally known to be better options for monitoring larger numbers of sockets.

Threads: This method is not threadsafe. Calls to insert() and erase() during this blocking operation will almost certainly yield unpredictable results.

Exceptions

randolf::rex::xEAGAIN	Failure to allocate internal system resources
randolf::rex::xEFAULT	Address structure/memory is not in a writable part of the user address space
randolf::rex::xEINTR	Interrupted by a signal
randolf::rex::xENOMEM	Insufficient memory
randolf::rex::xENOTSOCK	Underlying socket file descriptor (handle) doesn't refer to a socket
randolf::rex::xETIMEDOUT	Timeout period elapsed (even if the `TIMEOUT_BEHAVIOUR` flag is not set to `TIMEOUT_EXCEPTION`, there is a highly improbable chance that a timeout could still occur if the data is read from any of the sockets in this rsocket_mux collection by another thread before the recv(..., MSG_PEEK) call)

Returns: An std::vector<socket_mux_fds> that holds only those sockets that were selected

See also: poll(); ppoll(); select()

Parameters

tmo_p	Pointer to a `timespec` structure (will not be updated)
sigmask	Signal mask
timeout_behaviour	Timeout behaviour (see rsocket::TIMEOUT_BEHAVIOUR for details)

References pselect(), randolf::rex::rex::REX_ALT_EAGAIN, randolf::rex::rex::REX_FIND_ERRNO, and randolf::rsocket::TIMEOUT_EXCEPTION.

Referenced by pselect().

◆ select()

std::vector< rsocket_mux_fds > randolf::rsocket_mux::select	(	struct timeval *	tv = nullptr,
		const bool	timeout_behaviour = rsocket::TIMEOUT_EXCEPTION )

inline

Use the select() method on the internal set of instantiated rsocket objects.

Note: Performance optimization was a major consideration in the design of this method, including only testing the readiness of socket handles that were actually added to the underlying fd_set array(s).

The easier way to use this method is to only add one polling type (such as POLLIN) to the encompassing rsocket_mux object, and then all rsocket_mux_fds records returned will only be for that polling type (and then you won't have to write additional code to confirm the polling type). However, easier doesn't necessarily equate to better, and your needs and use case(s) should normally be considered in determining which approach is the most appropriate to write code for.

Warning: The underlying POSIX select() method is not efficient and is known to have a tendency to use a significant amount of stack memory, particularly when monitoring more sockets. The poll() and ppoll() methods serve as improvements to these problems, and are generally known to be better options for monitoring larger numbers of sockets.

Threads: This method is not threadsafe. Calls to insert() and erase() during this blocking operation will almost certainly yield unpredictable results.

Exceptions

randolf::rex::xEAGAIN	Failure to allocate internal system resources
randolf::rex::xEFAULT	Address structure/memory is not in a writable part of the user address space
randolf::rex::xEINTR	Interrupted by a signal
randolf::rex::xENOMEM	Insufficient memory
randolf::rex::xENOTSOCK	Underlying socket file descriptor (handle) doesn't refer to a socket
randolf::rex::xETIMEDOUT	Timeout period elapsed (even if the `TIMEOUT_BEHAVIOUR` flag is not set to `TIMEOUT_EXCEPTION`, there is a highly improbable chance that a timeout could still occur if the data is read from any of the sockets in this rsocket_mux collection by another thread before the recv(..., MSG_PEEK) call)

Returns: An std::vector<socket_mux_fds> that holds only those sockets that were selected

See also: poll(); ppoll(); pselect()

Parameters

tv	Pointer to a `timeval` structure (may also be updated with duration remaining if defined)
timeout_behaviour	Timeout behaviour (see rsocket::TIMEOUT_BEHAVIOUR for details)

References randolf::rex::rex::REX_ALT_EAGAIN, randolf::rex::rex::REX_FIND_ERRNO, select(), and randolf::rsocket::TIMEOUT_EXCEPTION.

Referenced by select().

◆ size()

size_t randolf::rsocket_mux::size ( )

inlinenoexcept

Find out how many rsocket entries are in this mux.

Threads: This method is threadsafe.

Returns: Number of rsocket objects in the underlying std::set

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

randolf/rsocket_mux

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ rsocket_mux() [1/3]

◆ rsocket_mux() [2/3]

◆ rsocket_mux() [3/3]

Member Function Documentation

◆ erase() [1/2]

◆ erase() [2/2]

◆ insert() [1/2]

◆ insert() [2/2]

◆ poll()

◆ ppoll()

◆ pselect()

◆ select()

◆ size()