Flow module containing the API and implementation of the Flow network protocol, a TCP-inspired stream protocol that uses UDP as underlying transport. More...

Namespaces
namespace	asio
	Contains classes that add boost.asio integration to the main Flow-protocol classes such as net_flow::Node and net_flow::Peer_socket, so that `net_flow` sockets can be easily used in boost.asio-driven event loops, e.g., ones also performing TCP networking and scheduling timers.

namespace	error
	Namespace containing the net_flow module's extension of boost.system error conventions, so that Flow network protocol API can return codes/messages from within its own new set of error codes/messages.

Classes
struct	Ack_packet
	Internal `net_flow` `struct` that encapsulates the Flow-protocol low-level ACK packet. More...

class	Congestion_control_classic
	Classic congestion control, based on Reno (TCP RFC 5681), with congestion avoidance, slow start, and congestion window halving (etc.) upon a loss event. More...

class	Congestion_control_classic_data
	Utility class for use by Congestion_control_strategy implementations that implements congestion window and slow start threshold storage and classic Reno-style "slow start" and "congestion avoidance" algorithms. More...

class	Congestion_control_classic_with_bandwidth_est
	Classic congestion control but with backoff to bandwidth estimate-based pipe size. More...

class	Congestion_control_selector
	Namespace-like class that enables an `enum`-based selection of the Congestion_control_strategy interface implementation to use for a given socket (for programmatic socket options) and facilitates stream I/O of these enums (allowing parsing and outputting these socket options). More...

class	Congestion_control_strategy
	The abstract interface for a per-socket module that determines the socket's congestion control behavior. More...

struct	Data_packet
	Internal `net_flow` `struct` that encapsulates the Flow-protocol low-level DATA packet. More...

class	Drop_timer
	Internal `net_flow` class that maintains the Drop Timer for DATA packet(s) to have been sent out over a connection but not yet acknowledged by the receiver. More...

class	Event_set
	A user-set collection of sockets and desired conditions on those sockets (such as: "socket has data to read"), with the ability to wait for those conditions to become true and signal the user when so. More...

struct	Low_lvl_packet
	Internal `net_flow` `struct` that encapsulates the Flow-protocol low-level packet structure and serves as the super-type for all specific packet types, represented by derived `struct`s like Ack_packet, Rst_packet, etc. More...

class	Net_env_simulator
	Objects of this class can be fed to Node to make it internally simulate network conditions like loss, latency, and data duplication. More...

class	Node
	An object of this class is a single Flow-protocol networking node, in the sense that: (1) it has a distinct IP address and UDP port; and (2) it speaks the Flow protocol over a UDP transport layer. More...

struct	Node_options
	A set of low-level options affecting a single Flow Node, including Peer_socket objects and other objects subsequently generated by that Flow Node. More...

class	Peer_socket
	A peer (non-server) socket operating over the Flow network protocol, with optional stream-of-bytes and reliability support. More...

struct	Peer_socket_info
	A data store that keeps stats about the a Peer_socket connection. More...

struct	Peer_socket_options
	A set of low-level options affecting a single Peer_socket. More...

struct	Peer_socket_receive_stats
	A data store that keeps stats about the incoming direction of a Peer_socket connection to another Flow-protocol Peer_socket. More...

class	Peer_socket_receive_stats_accumulator
	A class that keeps a Peer_socket_receive_stats data store, includes methods to conveniently accumulate data in it, and provides output to `ostream`. More...

class	Peer_socket_send_stats
	A data store that keeps stats about the outgoing direction of a Peer_socket connection to another Flow-protocol Peer_socket. More...

class	Peer_socket_send_stats_accumulator
	A class that keeps a Peer_socket_send_stats data store, includes methods to conveniently accumulate data in it, and provides output to `ostream`. More...

class	Port_space
	Internal `net_flow` class that maintains the available Flow-protocol port space, somewhat similarly to the classic TCP or UDP port scheme. More...

struct	Remote_endpoint
	Represents the remote endpoint of a Flow-protocol connection; identifies the UDP endpoint of the remote Node and the logical Flow-protocol port within that Node. More...

struct	Rst_packet
	Internal `net_flow` `struct` that encapsulates the Flow-protocol low-level RST packet. More...

class	Send_bandwidth_estimator
	A per-Peer_socket module that tries to estimate the bandwidth available to the outgoing flow. More...

struct	Send_pacing_data
	The current outgoing packet pacing state, including queue of low-level packets to be sent, for a given Peer_socket. More...

class	Sequence_number
	An internal `net_flow` sequence number identifying a piece of data. More...

class	Server_socket
	A server socket able to listen on a single Flow port for incoming connections and return peer sockets (Peer_socket objects) to the local user once such connections are established. More...

class	Socket_buffer
	Internal `net_flow` class that implements a socket buffer, as used by Peer_socket for Send and Receive buffers. More...

struct	Syn_ack_ack_packet
	Internal `net_flow` `struct` that encapsulates the Flow-protocol low-level SYN_ACK_ACK packet. More...

struct	Syn_ack_packet
	Internal `net_flow` `struct` that encapsulates the Flow-protocol low-level SYN_ACK packet. More...

struct	Syn_packet
	Internal `net_flow` `struct` that encapsulates the Flow-protocol low-level SYN packet. More...

Typedefs
using	flow_port_t = uint16_t
	Logical Flow port type (analogous to a UDP/TCP port in spirit but in no way relevant to UDP/TCP). More...

Enumerations
enum class	Xfer_op_result { S_FULLY_XFERRED , S_PARTIALLY_XFERRED , S_ERROR }
	Result of a send or receive operation, used at least in stat reporting. More...

Functions
std::istream &	operator>> (std::istream &is, Peer_socket_options::Congestion_control_strategy_choice &strategy_choice)
	Deserializes a Peer_socket_options::Congestion_control_strategy_choice `enum` from a standard input stream. More...

std::ostream &	operator<< (std::ostream &os, const Peer_socket_options::Congestion_control_strategy_choice &strategy_choice)
	Serializes a Peer_socket_options::Congestion_control_strategy_choice `enum` to a standard `ostream` – the reverse of operator>>(). More...

std::ostream &	operator<< (std::ostream &os, const Function< std::ostream &(std::ostream &)> &os_manip)
	Applies the given `ostream` manipulator function to the given `ostream` – just like standard streams already allow, but with the function given as a flow::Function object instead of a raw function pointer. More...

std::ostream &	operator<< (std::ostream &os, const Socket_buffer &sock_buf)
	Prints a printable representation of the data in `sock_buf` to the given standard `ostream`. More...

std::ostream &	operator<< (std::ostream &os, const Sequence_number &seq_num)
	Prints given sequence number to given `ostream`. More...

size_t	hash_value (const Sequence_number &seq_num)
	Free function that returns `seq_num.hash()`; has to be a free function named `hash_value` for boost.hash to pick it up. More...

bool	operator== (const Remote_endpoint &lhs, const Remote_endpoint &rhs)
	Whether `lhs` is equal to `rhs`. More...

std::ostream &	operator<< (std::ostream &os, const Remote_endpoint &endpoint)
	Prints string representation of the given Remote_endpoint to the given `ostream`. More...

size_t	hash_value (const Remote_endpoint &remote_endpoint)
	Free function that returns `remote_endpoint.hash()`; has to be a free function named `hash_value` for boost.hash to pick it up. More...

std::ostream &	operator<< (std::ostream &os, Event_set::State state)
	Prints string representation of given Event_set state to given standard `ostream` and returns the latter. More...

std::ostream &	operator<< (std::ostream &os, Event_set::Event_type ev_type)
	Prints string representation of given event type to given standard `ostream` and returns the latter. More...

std::ostream &	operator<< (std::ostream &os, const Peer_socket_receive_stats &stats)
	Prints string representation of the stats in the given stats object to the standard `ostream` and returns the latter. More...

std::ostream &	operator<< (std::ostream &os, const Peer_socket_send_stats &stats)
	Prints string representation of the stats in the given stats object to the standard `ostream` and returns the latter. More...

std::ostream &	operator<< (std::ostream &os, const Peer_socket_info &stats)
	Prints string representation of the stats in the given stats object to the standard `ostream` and returns the latter. More...

std::ostream &	operator<< (std::ostream &os, const Peer_socket *sock)
	Prints string representation of given socket to given standard `ostream` and returns the latter. More...

std::ostream &	operator<< (std::ostream &os, const Server_socket *serv)
	Prints string representation of given socket to given standard `ostream` and returns the latter. More...

std::ostream &	operator<< (std::ostream &os, const Node_options &opts)
	Prints the name of each option in the given Node_options, along with its current value, to the given `ostream`. More...

std::ostream &	operator<< (std::ostream &os, const Peer_socket_options &opts)
	Prints the name of each option in the given Peer_socket_options, along with its current value, to the given `ostream`. More...

bool	operator== (const Node::Socket_id &lhs, const Node::Socket_id &rhs)

size_t	hash_value (const Node::Socket_id &socket_id)

std::ostream &	operator<< (std::ostream &os, Peer_socket::Int_state state)

std::ostream &	operator<< (std::ostream &os, Server_socket::State state)
	Prints string representation of given socket state to given standard `ostream` and returns the latter. More...

Variables
const flow_port_t	S_PORT_ANY = 0
	Special Flow port value used to indicate "invalid port" or "please pick a random available ephemeral port," depending on the context. More...

Detailed Description

Flow module containing the API and implementation of the Flow network protocol, a TCP-inspired stream protocol that uses UDP as underlying transport.

See the large doc header on class net_flow::Node for the "root" of all documentation w/r/t net_flow, beyond the present brief sentences.

Historical note

Historically, the Flow project only existed in the first place to deliver the functionality now in this namespace flow::net_flow. However, since then, net_flow has become merely one of several Flow modules, each providing functionality independent of the others'. In the past, all/most net_flow{} contents resided directly in namespace flow, but now it has been segregated into its own namespace.

net_flow may still be, by volume, the largest module (hence also perhaps the largest user of general-use modules like flow::log and flow::util). Nevertheless, it is no longer "special."

See also: Main class net_flow::Node.

Typedef Documentation

◆ flow_port_t

using flow::net_flow::flow_port_t = typedef uint16_t

Logical Flow port type (analogous to a UDP/TCP port in spirit but in no way relevant to UDP/TCP).

Definition at line 54 of file net_flow_fwd.hpp.

Enumeration Type Documentation

◆ Xfer_op_result

enum class flow::net_flow::Xfer_op_result

strong

Result of a send or receive operation, used at least in stat reporting.

Enumerator
S_FULLY_XFERRED	Bytes transferred equals bytes expected.
S_PARTIALLY_XFERRED	Bytes transferred less than bytes expected.
S_ERROR	Error occurred – probably no bytes transferred.

Definition at line 43 of file net_flow_fwd.hpp.

Function Documentation

◆ hash_value() [1/3]

size_t hash_value ( const Node::Socket_id & socket_id )

Free function that returns socket_id.hash(); has to be a free function named hash_value() for boost.hash to pick it up.

Parameters

socket_id Socket ID to hash.

Returns: socket_id.hash().

Definition at line 1162 of file node.cpp.

◆ hash_value() [2/3]

size_t hash_value ( const Remote_endpoint & remote_endpoint )

Free function that returns remote_endpoint.hash(); has to be a free function named hash_value for boost.hash to pick it up.

Parameters

remote_endpoint Object to hash.

Returns: remote_endpoint.hash().

Definition at line 70 of file endpoint.cpp.

◆ hash_value() [3/3]

size_t flow::net_flow::hash_value ( const Sequence_number & seq_num )

Free function that returns seq_num.hash(); has to be a free function named hash_value for boost.hash to pick it up.

Parameters

seq_num Object to hash.

Returns: seq_num.hash().

Definition at line 275 of file seq_num.cpp.

Referenced by flow::net_flow::Sequence_number::hash().

Here is the caller graph for this function:

◆ operator<<() [1/16]

std::ostream & flow::net_flow::operator<<	(	std::ostream &	os,
		const Function< std::ostream &(std::ostream &)> &	os_manip
	)

Applies the given ostream manipulator function to the given ostream – just like standard streams already allow, but with the function given as a flow::Function object instead of a raw function pointer.

Without this, the flow::Function is usually converted to a bool or something and just printed out as "1" – which is not useful.

Much like with standard function manipulators (std::endl, for example), the idea is for this to work:

cout << print_something_to_ostream << ":" << xyz;
// ...
// But in this case, print_something_to_stream is of type: Function<ostream& (ostream&)>.
// E.g., ahead of the `cout` this could have been done, assuming: ostream& func(ostream& os, bool some_flag):
flow::Function<ostream& (ostream&)> print_something_to_stream
  = [](ostream& os) -> ostream& { return func(os, false); };
// Or with a non-static class member function: class Some_class { ostream& func(ostream& os, bool some_flag); }.
Some_class some_instance;
flow::Function<ostream& (ostream&)> print_something_to_stream
  = [some_instance](ostream& os) -> ostream& { return some_instance->func(os, false); };

Warning: It is important for this to be in namespace flow::net_flow, not higher (such as flow) or lower. Otherwise the places needing this overload to be used won't, and it will either not compile; or compile but invoke some other, useless overload. Unfortunately placing it into a containing namespace makes it not work from within a contained namespace.

Note: You may note the above technique is not used for argument-bearing std stream manipulators; for example std::setw(). The technique used to make that work is that setw() would return some internal struct (of unknown-to-user type T), in which it has stored the argument to setw(); and an operator<<(ostream, T) overload is defined; this overload would actually set the field width (or whatever setw() is supposed to do) on the ostream – using the arg value stored in the T. That works, and it may be somewhat more performant than our solution; but our solution is much more elegant and concise; it lets one build stream manipulators out of any function at all, the only requirements on it being that it returns an ostream& and takes same as an argument. The std technique allows the same, but we can do it with a single and expressive bind() call instead of a hidden internal struct type, explicitly storing arguments, documenting that stuff, etc. (We can change individual cases to use the std-style solution, if performance needs call for it, but so far there has been no such needs.) To be fair, the std solution is ALSO easier/more expressive at the actual call site. That is, in the above examples, one could just do: cout << func(false) << ":" << xyz; or cout << some_instance.func(false) << ":" << xyz;, respectively. That's easier to read than the bind() constructs above; but the code elsewhere that makes those func()s work is a huge mess that our solution completely avoids. For us, all that is needed behind the scenes is the present operator<< overload.

Parameters

os	Stream to write to/mutate.
os_manip	A flow::Function object that points to a manipulator, which is a function that takes a mutable `ostream`, writes something to it and/or acts on it in some other non-`const` way; and returns the original reference to mutable `ostream`.

Returns: os.

Definition at line 25 of file net_flow_util.cpp.

◆ operator<<() [2/16]

std::ostream & flow::net_flow::operator<<	(	std::ostream &	os,
		const Node_options &	opts
	)

Prints the name of each option in the given Node_options, along with its current value, to the given ostream.

Parameters

os	Stream to which to serialize.
opts	Object to serialize.

Returns: os.

Definition at line 152 of file options.cpp.

◆ operator<<() [3/16]

std::ostream & flow::net_flow::operator<<	(	std::ostream &	os,
		const Peer_socket *	sock
	)

Prints string representation of given socket to given standard ostream and returns the latter.

The representation includes the local and remote endpoints and the hex pointer value.

Note: shared_ptr forwards ostream output to the underlying pointer type, so this will affect Ptr output as well.

Parameters

os	Stream to print to.
sock	Object to serialize. May be null.

Returns: os.

Definition at line 6508 of file peer_socket.cpp.

◆ operator<<() [4/16]

std::ostream & operator<<	(	std::ostream &	os,
		const Peer_socket_info &	stats
	)

Prints string representation of the stats in the given stats object to the standard ostream and returns the latter.

The representation is multi-line but ends in no newline.

Parameters

os	Stream to which to print.
stats	Value to serialize.

Returns: os.

Definition at line 514 of file info.cpp.

◆ operator<<() [5/16]

std::ostream & flow::net_flow::operator<<	(	std::ostream &	os,
		const Peer_socket_options &	opts
	)

Prints the name of each option in the given Peer_socket_options, along with its current value, to the given ostream.

Parameters

os	Stream to which to serialize.
opts	Object to serialize.

Returns: os.

Definition at line 484 of file options.cpp.

◆ operator<<() [6/16]

std::ostream & operator<<	(	std::ostream &	os,
		const Peer_socket_options::Congestion_control_strategy_choice &	strategy_choice
	)

Serializes a Peer_socket_options::Congestion_control_strategy_choice enum to a standard ostream – the reverse of operator>>().

Writes a space-less token to the given stream based on the given strategy enum value. This enables a few key things to work, including output of defaults and values in the help via Peer_socket_options, and conversion to string via boost::lexical_cast.

Parameters

os	Stream to which to serialize.
strategy_choice	Value to serialize.

Returns: os.

Definition at line 146 of file cong_ctl.cpp.

◆ operator<<() [7/16]

std::ostream & operator<<	(	std::ostream &	os,
		const Peer_socket_receive_stats &	stats
	)

Prints string representation of the stats in the given stats object to the standard ostream and returns the latter.

The representation is multi-line but ends in no newline.

Parameters

os	Stream to which to print.
stats	Value to serialize.

Returns: os.

Definition at line 157 of file info.cpp.

◆ operator<<() [8/16]

std::ostream & operator<<	(	std::ostream &	os,
		const Peer_socket_send_stats &	stats
	)

Prints string representation of the stats in the given stats object to the standard ostream and returns the latter.

The representation is multi-line but ends in no newline.

Parameters

os	Stream to which to print.
stats	Value to serialize.

Returns: os.

Definition at line 287 of file info.cpp.

◆ operator<<() [9/16]

std::ostream & operator<<	(	std::ostream &	os,
		const Remote_endpoint &	endpoint
	)

Prints string representation of the given Remote_endpoint to the given ostream.

Parameters

os	Stream to which to write.
endpoint	Endpoint to serialize.

Returns: os.

Definition at line 65 of file endpoint.cpp.

◆ operator<<() [10/16]

std::ostream & flow::net_flow::operator<<	(	std::ostream &	os,
		const Sequence_number &	seq_num
	)

Prints given sequence number to given ostream.

set_metadata()'s effects are felt here; see Sequence_number class doc header for details.

Parameters

os	Stream to which to print.
seq_num	Object to serialize.

Returns: os.

Definition at line 169 of file seq_num.cpp.

◆ operator<<() [11/16]

std::ostream & flow::net_flow::operator<<	(	std::ostream &	os,
		const Server_socket *	serv
	)

Prints string representation of given socket to given standard ostream and returns the latter.

The representation includes the local endpoint and the hex pointer value.

Note: shared_ptr forwards ostream output to the underlying pointer type, so this will affect Ptr output as well.

Parameters

os	Stream to print to.
serv	Object to serialize. May be null.

Returns: os.

Definition at line 881 of file server_socket.cpp.

◆ operator<<() [12/16]

std::ostream & flow::net_flow::operator<<	(	std::ostream &	os,
		const Socket_buffer &	sock_buf
	)

Prints a printable representation of the data in sock_buf to the given standard ostream.

Exactly one line per block is used. This implementation is slow; use only in DATA logging, or where performance does not matter.

Parameters

os	Stream to which to write.
sock_buf	Object to serialize.

Returns: os.

Definition at line 176 of file socket_buffer.cpp.

◆ operator<<() [13/16]

std::ostream & operator<<	(	std::ostream &	os,
		Event_set::Event_type	ev_type
	)

Prints string representation of given event type to given standard ostream and returns the latter.

Parameters

os	Stream to print to.
ev_type	Value to serialize.

Returns: os.

Definition at line 1532 of file event_set.cpp.

◆ operator<<() [14/16]

std::ostream & operator<<	(	std::ostream &	os,
		Event_set::State	state
	)

Prints string representation of given Event_set state to given standard ostream and returns the latter.

Parameters

os	Stream to print to.
state	Value to serialize.

Returns: os.

Definition at line 1509 of file event_set.cpp.

◆ operator<<() [15/16]

std::ostream & flow::net_flow::operator<<	(	std::ostream &	os,
		Peer_socket::Int_state	state
	)

Todo:: There are a few guys like this which are marked @internal (Doxygen command) to hide from generated public documentation, and that works, but really they should not be visible in the publicly-exported (not in detail/) header source code; so this should be reorganized for cleanliness. The prototypes like this one can be moved to a detail/ header or maybe directly into .cpp that uses them (for those where it's only one).

Prints string representation of given socket state to given standard ostream and returns the latter.

Parameters

os	Stream to print to.
state	Value to serialize.

Returns: os.

Definition at line 6531 of file peer_socket.cpp.

◆ operator<<() [16/16]

std::ostream & operator<<	(	std::ostream &	os,
		Server_socket::State	state
	)

Prints string representation of given socket state to given standard ostream and returns the latter.

Parameters

os	Stream to print to.
state	Value to serialize.

Returns: os.

Definition at line 902 of file server_socket.cpp.

◆ operator==() [1/2]

bool operator==	(	const Node::Socket_id &	lhs,
		const Node::Socket_id &	rhs
	)

Whether lhs is equal to rhs.

Parameters

lhs	Object to compare.
rhs	Object to compare.

Returns: See above.

Definition at line 1157 of file node.cpp.

◆ operator==() [2/2]

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

Whether lhs is equal to rhs.

Parameters

lhs	Object to compare.
rhs	Object to compare.

Returns: See above.

Definition at line 60 of file endpoint.cpp.

◆ operator>>()

std::istream & operator>>	(	std::istream &	is,
		Peer_socket_options::Congestion_control_strategy_choice &	strategy_choice
	)

Deserializes a Peer_socket_options::Congestion_control_strategy_choice enum from a standard input stream.

Reads a single space-delimited token from the given stream. Maps that token to an aforementioned enumeration value. If the token is not recognized or cannot be read, some reasonable default strategy is chosen. This enables a few key things to work, including parsing from config file/command line via and conversion from string via boost::lexical_cast.

Parameters

is	Stream from which to deserialize.
strategy_choice	Reference to `enum` value which to set to the mapped strategy.

Returns: is.

Todo:: Peer_socket_options::Congestion_control_strategy_choice stream inserter << and >> operators should use the flow::util::istream_to_enum() pattern which is much easier than the overwrought old thing in there now involving two maps. Perhaps add a generic enum_to_strings() to provide the body for net_flow::Congestion_control_selector::get_ids().

Definition at line 124 of file cong_ctl.cpp.

Variable Documentation

◆ S_PORT_ANY

const flow_port_t flow::net_flow::S_PORT_ANY = 0

Special Flow port value used to indicate "invalid port" or "please pick a random available ephemeral port," depending on the context.

This is spiritually equivalent to TCP's port 0.

Definition at line 33 of file port_space.cpp.

Referenced by flow::net_flow::Node::connect_worker(), flow::net_flow::Node::handle_incoming(), flow::net_flow::Node::listen_worker(), flow::net_flow::Port_space::Port_space(), flow::net_flow::Port_space::reserve_ephemeral_port(), and flow::net_flow::Port_space::reserve_port().

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Historical note

Typedef Documentation

◆ flow_port_t

Enumeration Type Documentation

◆ Xfer_op_result

Function Documentation

◆ hash_value() [1/3]

◆ hash_value() [2/3]

◆ hash_value() [3/3]

◆ operator<<() [1/16]

◆ operator<<() [2/16]

◆ operator<<() [3/16]

◆ operator<<() [4/16]

◆ operator<<() [5/16]

◆ operator<<() [6/16]

◆ operator<<() [7/16]

◆ operator<<() [8/16]

◆ operator<<() [9/16]

◆ operator<<() [10/16]

◆ operator<<() [11/16]

◆ operator<<() [12/16]

◆ operator<<() [13/16]

◆ operator<<() [14/16]

◆ operator<<() [15/16]

◆ operator<<() [16/16]

◆ operator==() [1/2]

◆ operator==() [2/2]

◆ operator>>()

Variable Documentation

◆ S_PORT_ANY