chops::net::net_entity Class Reference

The net_entity class provides the primary application interface into the TCP acceptor, TCP connector, and UDP entity functionality. More...

#include <net_entity.hpp>

Public Member Functions
	net_entity ()=default
	Default construct a net_entity object.
	net_entity (const net_entity &)=default
	net_entity (net_entity &&)=default
net_entity &	operator= (const net_entity &)=default
net_entity &	operator= (net_entity &&)=default
template<typename ET >
	net_entity (const std::shared_ptr< ET > &p) noexcept
	Construct with a shared weak pointer to an internal net entity, this is an internal constructor only and not to be used by application code.
bool	is_valid () const noexcept
	Query whether an internal net entity is associated with this object.
auto	is_started () const -> nonstd::expected< bool, std::error_code >
	Query whether the associated net entity is in a started or stopped state.
template<typename F >
auto	visit_socket (F &&func) const -> nonstd::expected< void, std::error_code >
	Call an application supplied function object with a reference to the associated net entity asio socket.
template<typename F >
auto	visit_io_output (F &&func) const -> nonstd::expected< std::size_t, std::error_code >
	Call an application supplied function object with all basic_io_output objects that are active on associated IO handlers for this net entity.
template<typename F1 , typename F2 >
auto	start (F1 &&io_state_chg_func, F2 &&err_func) -> nonstd::expected< void, std::error_code >
	Start network processing on the associated net entity with the application providing IO state change and error function objects.
auto	stop () -> nonstd::expected< void, std::error_code >
	Stop network processing on the associated network entity.
std::string_view	stream_out () const noexcept
	Provide a display string of the internal type, whether for logging or debugging purposes.

Friends
class	net_ip
bool	operator== (const net_entity &lhs, const net_entity &rhs)
	Compare two net_entity objects for equality.
bool	operator< (const net_entity &lhs, const net_entity &rhs)
	Compare two net_entity objects for ordering purposes.

Related Symbols
(Note that these are not member symbols.)
template<typename IOT >
void	empty_error_func (basic_io_interface< IOT >, std::error_code)
	A "do nothing" error function template that can be used in the net_entity start method.
void	tcp_empty_error_func (tcp_io_interface, std::error_code)
	A "do nothing" error function used in the net_entity start method, for TCP basic_io_interface objects.
void	udp_empty_error_func (udp_io_interface, std::error_code)
	A "do nothing" error function used in the net_entity start method, for UDP basic_io_interface objects.

Detailed Description

The net_entity class provides the primary application interface into the TCP acceptor, TCP connector, and UDP entity functionality.

The net_entity class provides methods to start and stop processing on an underlying network entity, such as a TCP acceptor or TCP connector or UDP entity (which may be a UDP unicast sender or receiver, or a UDP multicast receiver).

Calling the stop method on a net_entity object will shutdown the associated network resource. At this point, other net_entity objects copied from the original will be affected.

The net_entity class is a lightweight value class, designed to be easy and efficient to copy and store. Internally it uses a std::weak_ptr to refer to the actual network entity.

A net_entity object is either associated with a network entity (i.e. the std::weak pointer is good), or not. The is_valid method queries if the association is present.

Applications can default construct a net_entity object, but it is not useful until a valid net_entity object is assigned to it (as provided in the make methods of the net_ip class).

Appropriate comparison operators are provided to allow net_entity objects to be used in associative or sequence containers.

All net_entity methods are safe to call concurrently from multiple threads.

Constructor & Destructor Documentation

net_entity()

chops::net::net_entity::net_entity ( )

default

Default construct a net_entity object.

A net_entity object is not useful until an active net_entity is assigned into it.

Member Function Documentation

is_started()

auto chops::net::net_entity::is_started ( ) const -> nonstd::expected<bool, std::error_code>

inline

Query whether the associated net entity is in a started or stopped state.

Returns

nonstd::expected - bool on success, specifying whether start has been called (if false, the network entity has not been started or is in a stopped state); on error (if no associated IO handler), a std::error_code is returned.

is_valid()

bool chops::net::net_entity::is_valid ( ) const

inlinenoexcept

Query whether an internal net entity is associated with this object.

If true, a net entity (TCP acceptor or TCP connector or UDP entity) is associated.

Returns

true if associated with a net entity.

start()

template<typename F1 , typename F2 >

auto chops::net::net_entity::start ( F1 && io_state_chg_func, F2 && err_func ) -> nonstd::expected<void, std::error_code>

inline

Start network processing on the associated net entity with the application providing IO state change and error function objects.

Once a net entity (TCP acceptor, TCP connector, UDP entity) is created through a net_ip make method, calling start on the net_entity causes local port binding and other processing (e.g. TCP listen, TCP connect) to occur.

Input and output processing does not start until the basic_io_interface start_io method is called.

The application provides two function objects to start (the second can be defaulted to a "do nothing" function object):

1) An IO state change callback function object. This callback object is invoked when a TCP connection is created or a UDP socket opened, and then invoked when the TCP connection is destroyed or the UDP socket closed. A basic_io_interface object is provided to the callback which allows IO processing to commence through the start_io method call (when a TCP connection is created or UDP socket opened).

2) An error function object which is invoked whenever an error occurs or when important processing is performed within an IO handler or network entity.

The start method call can only be called once. In other words, once started and stopped, a net entity cannot be restarted (future enhancements may allow restarting a net entity).

Parameters

io_state_chg_func

A function object with the following signature:

// TCP:
void (chops::net::tcp_io_interface, std::size_t, bool);
// UDP:
void (chops::net::udp_io_interface, std::size_t, bool);

The parameters are as follows:

1) A basic_io_interface object providing start_io access (and stop_io access if needed) to the underlying IO handler.

2) A count of the underlying IO handlers associated with this net entity. For a TCP connector or a UDP entity the number is 1 when starting and 0 when stopping, and for a TCP acceptor the number is 0 to N, depending on the number of accepted connections.

3) If true, the basic_io_interface has just been created (i.e. a TCP connection has been created or a UDP socket is ready), and if false, the connection or socket has been destroyed or closed.

In both IO state change function object callback invocations the basic_io_interface object is valid (is_valid returns true). For the second invocation no basic_io_interface methods should be called (since the IO handler is in the process of shutting down), but the basic_io_interface object can be used for associative lookups (if needed).

The IO state change function object must be copyable (it will be stored in a std::function).

Parameters

err_func

A function object with the following signature:

// TCP:
void (chops::net::tcp_io_interface, std::error_code);
// UDP:
void (chops::net::udp_io_interface, std::error_code);

The parameters are as follows:

1) A basic_io_interface object, which may or may not be valid (i.e is_valid may return either true or false), depending on the context of the error. No methods on the basic_io_interface object should be called, as the underlying handler, if present, may be in the process of shutting down. The basic_io_interface object is provided as a key to associate multiple error codes to the same handler.

2) The error code associated with the invocation. There are error codes associated with application initiated closes, shutdowns, and other state changes as well as error codes for network or system errors.

The err_func callback may be invoked in contexts other than a network IO error - for example, if a TCP acceptor or UDP entity cannot bind to a local port, a system error code will be provided. It is also used to notify important state changes, such as a message handler shutdown or TCP connector state changes.

The error function object must be copyable (it will be stored in a std::function).

For use cases that don't care about error codes, a function named empty_error_func is available.

Returns

nonstd::expected - on success network entity is started; on error, a std::error_code is returned.

stop()

auto chops::net::net_entity::stop ( ) -> nonstd::expected<void, std::error_code>

inline

Stop network processing on the associated network entity.

Internally, the network entity will call stop_io (or equivalent) on each associated IO handler.

Stopping the network processing may involve closing connections, deallocating resources, unbinding from ports, and invoking application provided state change function object callbacks.

Returns

nonstd::expected - on success network entity is stopped; on error, a std::error_code is returned.

stream_out()

std::string_view chops::net::net_entity::stream_out ( ) const

inlinenoexcept

Provide a display string of the internal type, whether for logging or debugging purposes.

Returns

A std::string_view containing the network entity type, either UDP, TCP acceptor, or TCP connector.

visit_io_output()

template<typename F >

auto chops::net::net_entity::visit_io_output ( F && func ) const -> nonstd::expected<std::size_t, std::error_code>

inline

Call an application supplied function object with all basic_io_output objects that are active on associated IO handlers for this net entity.

A TCP connector will have 0 or 1 active IO handlers, depending on connection state, while a TCP acceptor will have 0 to N active IO handlers, depending on the number of accepted incoming connections. A UDP entity will either have 0 or 1 active IO handlers depending on whether it has been started or not.

The function object must have one of the following signatures, depending on TCP or UDP:

void (chops::net::tcp_io_output); // TCP
void (chops::net::udp_io_output); // UDP

The function object will be called 0 to N times depending on active IO handlers. An IO handler is active if start_io has been called on it.

Returns

nonstd::expected - on success returns number of times function object has been called; on error (if no associated IO handler), a std::error_code is returned.

visit_socket()

template<typename F >

auto chops::net::net_entity::visit_socket ( F && func ) const -> nonstd::expected<void, std::error_code>

inline

Call an application supplied function object with a reference to the associated net entity asio socket.

The function object must have one of the following signatures, depending on the entity type:

void (asio::ip::tcp::socket&); // TCP connector
void (asio::ip::tcp::acceptor&) // TCP acceptor
void (asio::ip::udp::socket&); // UDP entity

Within the function object socket options can be queried or modified or any valid socket method called.

Returns

nonstd::expected - bool socket has been visited; on error (if no associated IO handler), a std::error_code is returned.

Friends And Related Symbol Documentation

operator<

bool operator< ( const net_entity & lhs, const net_entity & rhs )

friend

Compare two net_entity objects for ordering purposes.

Arbitrarily, a UDP network entity compares less than a TCP acceptor which compares less than a TCP connector. If both network entities are the same then the std::shared_ptr ordering is returned.

All invalid net_entity objects (of the same network entity type) are less than valid ones. If both net_entity objects are invalid and the same network entity type, they are considered equal, so operator< returns false.

Returns

As described in the comments.

operator==

bool operator== ( const net_entity & lhs, const net_entity & rhs )

friend

Compare two net_entity objects for equality.

If the @ net_entity objects are not both pointing to the same type of network entity (TCP connector, TCP acceptor, etc), then they are not equal. If both are the same type of network entity, then both are checked to be valid (i.e. the internal weak_ptr is valid). If both are valid, then a std::shared_ptr comparison is made.

If both net_entity objects are invalid (and both same type of network entity), true is returned (this implies that all invalid net_entity objects are equivalent). If one is valid and the other invalid, false is returned.

Returns

As described in the comments.

---

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

• /github/workspace/include/net_ip/net_entity.hpp