chops::net::net_ip Class Reference

Primary class for the Chops Net IP library and the initial API point for providing TCP acceptor, TCP connector, UDP unicast, and UDP multicast capabilities. More...

#include <net_ip.hpp>

Public Member Functions
	net_ip (asio::io_context &ioc)
	Construct a net_ip object without starting any network processing.
net_entity	make_tcp_acceptor (std::string_view local_port_or_service, std::string_view listen_intf="", bool reuse_addr=true)
	Create a TCP acceptor net_entity, which will listen on a port for incoming connections (once started).
net_entity	make_tcp_acceptor (const asio::ip::tcp::endpoint &endp, bool reuse_addr=true)
	Create a TCP acceptor net_entity, using an already created endpoint.
template<typename F = simple_timeout>
net_entity	make_tcp_connector (std::string_view remote_port_or_service, std::string_view remote_host, const F &timeout_func=simple_timeout { }, bool reconn_on_err=false)
	Create a TCP connector net_entity, which will perform an active TCP connect to the specified host and port (once started).
template<typename Iter , typename F = simple_timeout>
auto	make_tcp_connector (Iter beg, Iter end, const F &timeout_func=simple_timeout { }, bool reconn_on_err=false) -> std::enable_if_t< std::is_same_v< std::decay< decltype(*beg)>, asio::ip::tcp::endpoint >, net_entity >
	Create a TCP connector net_entity with the endpoints already created, passing in iterators to the endpoint container.
template<typename F = simple_timeout>
net_entity	make_tcp_connector (const asio::ip::tcp::endpoint &endp, const F &timeout_func=simple_timeout { }, bool reconn_on_err=false)
	Create a TCP connector net_entity using a single remote endpoint.
net_entity	make_udp_unicast (std::string_view local_port_or_service, std::string_view local_intf="")
	Create a UDP unicast net_entity that allows receiving as well as sending.
net_entity	make_udp_unicast (const asio::ip::udp::endpoint &endp)
	Create a UDP unicast net_entity for receiving and sending, using an already created endpoint.
net_entity	make_udp_sender ()
	Create a UDP unicast net_entity for sending only (no local bind is performed).
void	remove (net_entity ent)
	Remove a net_entity from the internal list of net_entity objects.
void	remove_all ()
	Remove all acceptors, connectors, and UDP entities.
void	stop_all ()
	Call stop on all acceptors, connectors, and UDP entities.

Detailed Description

Primary class for the Chops Net IP library and the initial API point for providing TCP acceptor, TCP connector, UDP unicast, and UDP multicast capabilities.

A net_ip object creates and manages network related objects. It is the initial API point for creating a TCP acceptor, TCP connector, UDP unicast, or UDP multicast network entity. Once one of these network objects is created internal to the net_ip object, a net_entity object is returned to the application, allowing further operations to occur.

Applications perform operations with the net_entity and basic_io_interface and basic_io_output objects. The net_ip object creates facade-like objects of type net_entity, which allow further operations.

The general application usage pattern for the @ net_ip, @ net_entity, basic_io_interface and basic_io_output classes is:

1. Instantiate a net_ip object.
2. Create a net_entity object, through one of the net_ip make methods. A net_entity interacts with one of a TCP acceptor, TCP connector, UDP unicast receiver or sender, or UDP multicast receiver (a UDP multicast sender is the same as a UDP unicast sender).
3. Call the start method on the net_entity object. This performs name resolution (if needed), a local bind (if needed) and (for TCP) a connect or a listen.

Local host and port and interface name lookups are performed immediately using direct (synchronous) lookups when the net_entity start method is called. Remote host and port name lookups are performed asynchronously (since these may take longer) and are only needed for TCP connectors. If this is not acceptable, the application can perform the lookup and the endpoint (or endpoint sequence) can be passed in through the make method.

State change function objects are invoked when network IO can be started as well as when an error or shutdown occurs.

1. When a basic_io_interface object is supplied to the application through the IO state change callback, input processing is started through a start_io call. For outbound data, a basic_io_output object can be created from the basic_io_interface object, allowing data to be sent through send methods.

There are no executor operations available through the net_ip class. In other words, no event loop or run methods are available. Instead, the net_ip class takes an asio io_context as a constructor parameter and application code will use the asio executor methods for invoking the underlying asynchronous operations. The most current (as of early 2025) asio executor class, matching the C++ 26 standard executor, is the asio any_io_executor class.

For convenience, a class named worker in the net_ip_component directory combines an executor with a work guard and creates a thread to invoke the asynchronous operations. Example usage:

chops::net::worker wk;
wk.start();
chops::net::net_ip my_nip(wk.get_io_context());
// ...
wk.reset(); // or wk.stop();

The net_ip class is safe for multiple threads to use concurrently.

It should be noted, however, that race conditions are possible, especially for similar operations invoked between net_entity and basic_io_interface objects. For example, starting and stopping network entities concurrently between separate objects or threads could cause unexpected behavior.

Constructor & Destructor Documentation

net_ip()

chops::net::net_ip::net_ip ( asio::io_context & ioc )

inlineexplicit

Construct a net_ip object without starting any network processing.

Parameters

ioc	IO context for asynchronous operations.

Member Function Documentation

make_tcp_acceptor() [1/2]

net_entity chops::net::net_ip::make_tcp_acceptor ( const asio::ip::tcp::endpoint & endp, bool reuse_addr = true )

inline

Create a TCP acceptor net_entity, using an already created endpoint.

This make method allows flexibility in creating an endpoint for the acceptor to use, such as directly specifying ipV4 or ipV6 in name resolving, or directly creating the endpoint without using name resolving.

Parameters

endp	A asio::ip::tcp::endpoint that the acceptor uses for the local bind (when start is called).
reuse_addr	If true (default), the reuse_address socket option is set upon socket open.

Returns

net_entity object instantiated for a TCP acceptor.

make_tcp_acceptor() [2/2]

net_entity chops::net::net_ip::make_tcp_acceptor ( std::string_view local_port_or_service, std::string_view listen_intf = "", bool reuse_addr = true )

inline

Create a TCP acceptor net_entity, which will listen on a port for incoming connections (once started).

The port (and optional listen interface) passed in to this constructor will be resolved (name lookup) when start is called on the net_entity.

Parameters

local_port_or_service	Port number or service name to bind to for incoming TCP connects.
listen_intf	If this parameter is supplied, the bind (when start is called) will be performed on this specific interface. Otherwise, the bind is for "any" IP interface (which is the typical usage).
reuse_addr	If true (default), the reuse_address socket option is set upon socket open.

Returns

net_entity object instantiated for a TCP acceptor.

make_tcp_connector() [1/3]

template<typename F = simple_timeout>

net_entity chops::net::net_ip::make_tcp_connector ( const asio::ip::tcp::endpoint & endp, const F & timeout_func = simple_timeout { }, bool reconn_on_err = false )

inline

Create a TCP connector net_entity using a single remote endpoint.

Parameters

endp	Remote asio::ip::tcp::endpoint to use for the connect attempt.
timeout_func	tcp_connector_timeout_func, which must be copyable, returns a timeout value for retries on connect failures.
reconn_on_err	When a TCP connection has been established and a network error occurs, this flag specifies whether to start a reconnect attempt; this allows connectors that run until explicitly stopped.

Returns

net_entity object instantiated for a TCP connector.

make_tcp_connector() [2/3]

template<typename Iter , typename F = simple_timeout>

auto chops::net::net_ip::make_tcp_connector ( Iter beg, Iter end, const F & timeout_func = simple_timeout { }, bool reconn_on_err = false ) -> std::enable_if_t<std::is_same_v<std::decay<decltype(*beg)>, asio::ip::tcp::endpoint>, net_entity>

inline

Create a TCP connector net_entity with the endpoints already created, passing in iterators to the endpoint container.

This method allows flexibility in creating the remote endpoints for the connector to use. It also bypasses the name lookups (DNS lookups) that happen when a remote host and port is used.

Parameters

beg	A begin iterator to a sequence of remote asio::ip::tcp::endpoint objects.
end	An end iterator to the sequence of endpoints.
timeout_func	tcp_connector_timeout_func, which must be copyable, returns a timeout value for retries on connect failures.
reconn_on_err	When a TCP connection has been established and a network error occurs, this flag specifies whether to start a reconnect attempt; this allows connectors that run until explicitly stopped.

Returns

net_entity object instantiated for a TCP connector.

Note

To prevent selection of this method when two const char* parameters are provided for the first two parameters, this method is conditionally enabled. const char* or char* should match the make_tcp_connector method taking std::string_view parameters, not this method.

make_tcp_connector() [3/3]

template<typename F = simple_timeout>

net_entity chops::net::net_ip::make_tcp_connector ( std::string_view remote_port_or_service, std::string_view remote_host, const F & timeout_func = simple_timeout { }, bool reconn_on_err = false )

inline

Create a TCP connector net_entity, which will perform an active TCP connect to the specified host and port (once started).

Internally a sequence of remote endpoints will be looked up through a name resolver, (after start on the net_entity is called), and each endpoint will be tried in succession.

Parameters

remote_port_or_service	Port number or service name on remote host.
remote_host	Remote host name or IP address.
timeout_func	tcp_connector_timeout_func, which must be copyable, returns a timeout value for retries on connect failures.
reconn_on_err	When a TCP connection has been established and a network error occurs, this flag specifies whether to start a reconnect attempt; this allows connectors that run until explicitly stopped.

Returns

net_entity object instantiated for a TCP connector.

Note

The name and port lookup to create a sequence of remote TCP endpoints is performed when the net_entity start method is called. If this is not acceptable, the endpoints can be looked up by the application and the alternate make_tcp_connector method called.

make_udp_sender()

net_entity chops::net::net_ip::make_udp_sender ( )

inline

Create a UDP unicast net_entity for sending only (no local bind is performed).

This make method is used when no UDP reads are desired, only sends.

Returns

net_entity object instantiated for UDP.

make_udp_unicast() [1/2]

net_entity chops::net::net_ip::make_udp_unicast ( const asio::ip::udp::endpoint & endp )

inline

Create a UDP unicast net_entity for receiving and sending, using an already created endpoint.

This make method allows flexibility in creating an endpoint for the UDP unicast net_entity to use.

Parameters

endp	A asio::ip::udp::endpoint used for the local bind (when start is called).

Returns

net_entity object instantiated for UDP.

make_udp_unicast() [2/2]

net_entity chops::net::net_ip::make_udp_unicast ( std::string_view local_port_or_service, std::string_view local_intf = "" )

inline

Create a UDP unicast net_entity that allows receiving as well as sending.

This make method is used when incoming UDP (unicast) datagrams will be received. A local port is used for binding, and an optional local host address can also be used as part of the bind (e.g. if binding to a specific interface is needed).

If there is a need to determine whether an incoming UDP datagram was originally sent as unicast, multicast, or broadcast this can be performed by inspecting the remote endpoint address as supplied through the message handler callback.

Names are resolved and a bind to the local endpoint started when the net_entity start method is called, and a read is not started until the io_interface start_io method is called.

Parameters

local_port_or_service	Port number or service name for local binding.
local_intf	Local interface name, otherwise the default is "any address".

Returns

net_entity object instantiated for UDP.

Note

Common socket options on UDP datagram sockets, such as increasing the "time to live" (hop limit), allowing UDP broadcast, or setting the socket reuse flag can be set by using the net_entity visit_socket method (or basic_io_interface visit_socket method, which returns the same reference).

remove()

void chops::net::net_ip::remove ( net_entity ent )

inline

Remove a net_entity from the internal list of net_entity objects.

stop should first be called by the application, or the stop_all method can be called to stop all net entities.

Parameters

ent	net_entity to be removed.

remove_all()

void chops::net::net_ip::remove_all ( )

inline

Remove all acceptors, connectors, and UDP entities.

stop_all (or the equivalent) should first be called to stop all net entities.

stop_all()

void chops::net::net_ip::stop_all ( )

inline

Call stop on all acceptors, connectors, and UDP entities.

This method allows for a more measured shutdown, if needed.

---

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

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