TCP connection port. More...

#include <tcp_connection_port.h>

Inheritance diagram for roc::netio::TcpConnectionPort:

[legend]

Collaboration diagram for roc::netio::TcpConnectionPort:

[legend]

Public Member Functions
	TcpConnectionPort (TcpConnectionType type, uv_loop_t &loop, core::IArena &arena)
	Initialize. More...

virtual	~TcpConnectionPort ()
	Destroy. More...

virtual bool	open ()
	Open TCP connection. More...

virtual AsyncOperationStatus	async_close (ICloseHandler &handler, void *handler_arg)
	Asynchronously close TCP connection. More...

bool	accept (const TcpConnectionConfig &config, const address::SocketAddr &server_address, SocketHandle server_socket)
	Establish conection by accepting it from listening socket. More...

bool	connect (const TcpClientConfig &config)
	Establish connection to remote peer (asynchronously). More...

void	attach_terminate_handler (ITerminateHandler &handler, void *handler_arg)
	Set termination handler and start using it. More...

void	attach_connection_handler (IConnHandler &handler)
	Set connection handler and start reporting events to it. More...

virtual const address::SocketAddr &	local_address () const
	Return address of the local peer. More...

virtual const address::SocketAddr &	remote_address () const
	Return address of the remote peer. More...

virtual bool	is_failed () const
	Return true if there was a failure. More...

virtual bool	is_writable () const
	Return true if the connection is writable. More...

virtual bool	is_readable () const
	Return true if the connection is readable. More...

virtual ssize_t	try_write (const void *buf, size_t len)
	Write `buf` of size `len` to the connection. More...

virtual ssize_t	try_read (void *buf, size_t len)
	Read `len` bytes from the the connection to `buf`. More...

virtual void	async_terminate (TerminationMode mode)
	Initiate asynchronous graceful shutdown. More...

Public Member Functions inherited from roc::netio::BasicPort
	BasicPort (core::IArena &)
	Initialize. More...

virtual	~BasicPort ()
	Destroy. More...

const char *	descriptor () const
	Get a human-readable port description. More...

Public Member Functions inherited from roc::core::RefCounted< BasicPort, core::ArenaAllocation >
	RefCounted ()
	Initialize. More...

	RefCounted (const core::ArenaAllocation &policy)
	Initialize. More...

int	getref () const
	Get reference counter. More...

void	incref () const
	Increment reference counter. More...

void	decref () const
	Decrement reference counter. More...

Public Member Functions inherited from roc::core::ListNode
ListNodeData *	list_node_data () const
	Get list node data. More...

Protected Member Functions
virtual void	format_descriptor (core::StringBuilder &b)
	Format descriptor. More...

Protected Member Functions inherited from roc::netio::BasicPort
void	update_descriptor ()
	Format descriptor and store into internal buffer. More...

Protected Member Functions inherited from roc::core::ArenaAllocation
IArena &	arena () const
	Get arena. More...

	ArenaAllocation (IArena &arena)
	Initialize. More...

template<class T >
void	destroy (T &object)
	Destroy object and return memory to arena. More...

Detailed Description

TCP connection port.

Public interfaces

There are two important interfaces related to TCP connection:

IConn is implemented by TcpConnectionPort. The interface allows to retrieve connection parameters and perform non-blocking I/O.

IConnHandler is implemented by users of netio module. This interface is notified about connection state changes (e.g. connection is established) and availability of I/O (e.g. connection becomes readable).

Thread access

Methods that are not part of IConn interface are called from within other netio classes, e.g. TcpServerPort, on the network loop thread.

Methods from the IConn interface are called by users of netio module from any thread. They are thread-safe and lock-free.

Connection type and lifecycle

Connection can be client-side (connect call) or server-side (accept call).

Client-side connection is created using AddTcpClientPort task of the network loop, and is closed using RemovePort task. Before removing the port, the user must call async_terminate() and wait until termination is completed.

Server-side connection is created by TcpServerPort when it receives a new incoming connection. To remove it, the user should call async_terminate(). When termination is completed, TcpServerPort automatically closes and destroys connection.

Connection workflow

The following rules must be followed:

if you called open(), even if it failed, you're responsible for calling async_close() and waiting for its completion before destroying connection
after calling open(), you should call either accept() or connect() before using connection
if you called connect() or accept(), even if it failed, you're responsible for calling async_terminate() and waiting for its completion before calling async_close()
after connection is established and before it's terminated you can perform I/O
even if connection can't be established, async_terminate() still should be called before closing and destryoing connection

Connection FSM

TcpConnectionPort maintains an FSM and sees each operation or event handler as a transition between states. Each operation is allowed only in certain states and will panic when not used properly.

State switch mostly happens on the network thread, however some limited set of transitions is allowed from other threads. For this reason, state switching is done using atomic operations.

Definition at line 123 of file tcp_connection_port.h.

Constructor & Destructor Documentation

◆ TcpConnectionPort()

roc::netio::TcpConnectionPort::TcpConnectionPort	(	TcpConnectionType	type,
		uv_loop_t &	loop,
		core::IArena &	arena
	)

Initialize.

◆ ~TcpConnectionPort()

virtual roc::netio::TcpConnectionPort::~TcpConnectionPort ( )

virtual

Destroy.

Member Function Documentation

◆ accept()

bool roc::netio::TcpConnectionPort::accept	(	const TcpConnectionConfig &	config,
		const address::SocketAddr &	server_address,
		SocketHandle	server_socket
	)

Establish conection by accepting it from listening socket.

Remarks: Should be called from network loop thread.

◆ async_close()

virtual AsyncOperationStatus roc::netio::TcpConnectionPort::async_close	(	ICloseHandler &	handler,
		void *	handler_arg
	)

virtual

Asynchronously close TCP connection.

Remarks: Should be called from network loop thread.

Implements roc::netio::BasicPort.

◆ async_terminate()

virtual void roc::netio::TcpConnectionPort::async_terminate ( TerminationMode mode )

virtual

Initiate asynchronous graceful shutdown.

Remarks: Can be called from any thread.

Implements roc::netio::IConn.

◆ attach_connection_handler()

void roc::netio::TcpConnectionPort::attach_connection_handler ( IConnHandler & handler )

Set connection handler and start reporting events to it.

Remarks: Should be called from network loop thread.

◆ attach_terminate_handler()

void roc::netio::TcpConnectionPort::attach_terminate_handler	(	ITerminateHandler &	handler,
		void *	handler_arg
	)

Set termination handler and start using it.

Remarks: Should be called from network loop thread.

◆ connect()

bool roc::netio::TcpConnectionPort::connect ( const TcpClientConfig & config )

Establish connection to remote peer (asynchronously).

Remarks: Should be called from network loop thread.

◆ format_descriptor()

virtual void roc::netio::TcpConnectionPort::format_descriptor ( core::StringBuilder & b )

protectedvirtual

Format descriptor.

Implements roc::netio::BasicPort.

◆ is_failed()

virtual bool roc::netio::TcpConnectionPort::is_failed ( ) const

virtual

Return true if there was a failure.

Remarks: Can be called from any thread.

Implements roc::netio::IConn.

◆ is_readable()

virtual bool roc::netio::TcpConnectionPort::is_readable ( ) const

virtual

Return true if the connection is readable.

Remarks: Can be called from any thread.

Implements roc::netio::IConn.

◆ is_writable()

virtual bool roc::netio::TcpConnectionPort::is_writable ( ) const

virtual

Return true if the connection is writable.

Remarks: Can be called from any thread.

Implements roc::netio::IConn.

◆ local_address()

virtual const address::SocketAddr& roc::netio::TcpConnectionPort::local_address ( ) const

virtual

Return address of the local peer.

Remarks: Can be called from any thread.

Implements roc::netio::IConn.

◆ open()

virtual bool roc::netio::TcpConnectionPort::open ( )

virtual

Open TCP connection.

Remarks: Should be called from network loop thread.

Implements roc::netio::BasicPort.

◆ remote_address()

virtual const address::SocketAddr& roc::netio::TcpConnectionPort::remote_address ( ) const

virtual

Return address of the remote peer.

Remarks: Can be called from any thread.

Implements roc::netio::IConn.

◆ try_read()

virtual ssize_t roc::netio::TcpConnectionPort::try_read	(	void *	buf,
		size_t	len
	)

virtual

Read len bytes from the the connection to buf.

Remarks: Can be called from any thread.

Implements roc::netio::IConn.

◆ try_write()

virtual ssize_t roc::netio::TcpConnectionPort::try_write	(	const void *	buf,
		size_t	len
	)

virtual

Write buf of size len to the connection.

Remarks: Can be called from any thread.

Implements roc::netio::IConn.

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

roc_netio/target_libuv/roc_netio/tcp_connection_port.h

Public Member Functions

Protected Member Functions

Detailed Description

Public interfaces

Thread access

Connection type and lifecycle

Connection workflow

Connection FSM

Constructor & Destructor Documentation

◆ TcpConnectionPort()

◆ ~TcpConnectionPort()

Member Function Documentation

◆ accept()

◆ async_close()

◆ async_terminate()

◆ attach_connection_handler()

◆ attach_terminate_handler()

◆ connect()

◆ format_descriptor()

◆ is_failed()

◆ is_readable()

◆ is_writable()

◆ local_address()

◆ open()

◆ remote_address()

◆ try_read()

◆ try_write()