io_output_delivery.hpp File Reference

Functions that deliver a basic_io_output object, either through std::future objects or through other mechanisms, such as a wait_queue. More...

#include <cstddef>
#include <utility>
#include <system_error>
#include <memory>
#include <exception>
#include <future>
#include "net_ip/net_entity.hpp"
#include "net_ip/basic_io_interface.hpp"
#include "net_ip/basic_io_output.hpp"
#include "net_ip/io_type_decls.hpp"
#include "queue/wait_queue.hpp"

Include dependency graph for io_output_delivery.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	chops::net::io_state_chg_data< IOT >
	Data provided through an IO state change. More...
struct	chops::net::io_output_future_pair< IOT >
	A struct containing two std::future objects that deliver basic_io_output objects corresponding to the creation and destruction (start, stop) of an IO handler (typically used for a UDP socket or the first TCP connection of a TCP connector). More...

Typedefs
template<typename IOT >
using	chops::net::io_wait_q = chops::wait_queue<io_state_chg_data<IOT> >
	wait_queue declaration that provides IO state change data.
using	chops::net::tcp_io_wait_q = io_wait_q<chops::net::tcp_io>
	io_wait_q for tcp_io_interface objects.
using	chops::net::udp_io_wait_q = io_wait_q<chops::net::udp_io>
	io_wait_q for udp_io_interface objects.
template<typename IOT >
using	chops::net::io_output_future = std::future<basic_io_output<IOT> >
	An alias for a std::future containing a basic_io_output.
using	chops::net::tcp_io_output_future = io_output_future<tcp_io>
	io_output_future for TCP IO handlers.
using	chops::net::udp_io_output_future = io_output_future<udp_io>
	io_output_future for UDP IO handlers.
using	chops::net::tcp_io_output_future_pair = io_output_future_pair<tcp_io>
	io_output_future_pair for TCP IO handlers.
using	chops::net::udp_io_output_future_pair = io_output_future_pair<udp_io>
	io_output_future_pair for UDP IO handlers.

Functions
template<typename IOT , typename IOS , typename EF >
auto	chops::net::start_with_io_wait_queue (net_entity ne, IOS &&io_start, io_wait_q< IOT > &wq, EF &&err_func)
	Start the entity with an IO state change function object that calls start_io and also passes basic_io_output data through a wait_queue.
template<typename IOT , typename IOS , typename EF >
io_output_future< IOT >	chops::net::make_io_output_future (net_entity &ent, IOS &&io_start, EF &&err_func)
	Return a std::future object containing a basic_io_output, which will become available after start is called on the passed in net_entity.
template<typename IOT , typename IOS , typename EF >
io_output_future_pair< IOT >	chops::net::make_io_output_future_pair (net_entity &ent, IOS &&io_start, EF &&err_func)
	Return a pair of std::future objects each containing a basic_io_output, which will become available after start is called on the passed in net_entity.

Detailed Description

Functions that deliver a basic_io_output object, either through std::future objects or through other mechanisms, such as a wait_queue.

When all IO processing can be performed in the message handler callback, there is not a need to keep a separate basic_io_output object for sending data (since a basic_io_output object is provided as part of the callback). But when there is a need for non-reply sends, component functions in this header package up much of the needed logic.

All of these functions take a net_entity object and a start_io function object, then call start on the net_entity using the start_io function object and then return a basic_io_output object through various mechanisms.

Empty ("do nothing") error functions are available in the net_entity.hpp header. These can be used for the error function object parameters.

The io_state_change.hpp header provides a collection of functions that create start_io function objects, each packaged with the logic and data needed to call start_io.

There are two ways the basic_io_output object can be delivered - 1) by std::future, or 2) by a wait_queue. While a std::future can be used with any type of net entity (TCP connector, TCP acceptor, UDP) it is of limited use since a std::future can only be satisfied once. This works well for a single open / close UDP session, or the first connect / disconnect lifetime of a TCP connector. It is questionable (at best) when futures are used for a TCP acceptor. basic_io_output objects delivered through a wait_queue are appropriate for any of the network entity types.

Author

Cliff Green

Copyright (c) 2018-2019 by Cliff Green

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Function Documentation

make_io_output_future()

template<typename IOT , typename IOS , typename EF >

io_output_future< IOT > chops::net::make_io_output_future	(	net_entity &	ent,
		IOS &&	io_start,
		EF &&	err_func )

Return a std::future object containing a basic_io_output, which will become available after start is called on the passed in net_entity.

This function returns a single std::future object corresponding to when a TCP connection or UDP socket is created and ready. The std::future will return a basic_io_output object which can be used for sending data.

Parameters

ent	A net_entity object; start is immediately called.
io_start	A function object which will invoke start_io on a basic_io_interface object.
err_func	Error function object.

Returns

An io_output_future, either a tcp_io_output_future or a udp_io_output_future.

Note

For TCP (whether acceptor or connector) this works for only the first connection that is created (once a std::promise is delivered it cannot be delivered again).

make_io_output_future_pair()

template<typename IOT , typename IOS , typename EF >

io_output_future_pair< IOT > chops::net::make_io_output_future_pair	(	net_entity &	ent,
		IOS &&	io_start,
		EF &&	err_func )

Return a pair of std::future objects each containing a basic_io_output, which will become available after start is called on the passed in net_entity.

This function returns two std::future objects. The first allows the application to block until a TCP connection or UDP socket is created and ready. At that point the std::future will return a basic_io_output object, and sends can be invoked as needed.

The second std::future will pop when the corresponding connection or socket is closed.

Parameters

ent	A net_entity object; start is immediately called.
io_start	A function object which will invoke start_io on a basic_io_interface object.
err_func	Error function object.

Returns

An io_output_future_pair, either a tcp_io_output_future_pair or udp_io_output_future_pair.

Note

For TCP (whether acceptor or connector) this works for only the first connection that is created (once a std::promise is delivered it cannot be delivered again).

start_with_io_wait_queue()

template<typename IOT , typename IOS , typename EF >

auto chops::net::start_with_io_wait_queue	(	net_entity	ne,
		IOS &&	io_start,
		io_wait_q< IOT > &	wq,
		EF &&	err_func )

Start the entity with an IO state change function object that calls start_io and also passes basic_io_output data through a wait_queue.

Parameters

ne	A net_entity object, start is immediately called.
io_start	A function object which will invoke start_io on a basic_io_interface object.
wq	A wait_queue which is used to pass the IO state change data.
err_func	Error function object.

Returns

Same as return type from net_entity start.