An interface definition for communication between hosts. More...

#include <connection.h>

Inheritance diagram for eq::net::Connection:

Collaboration diagram for eq::net::Connection:

Public Member Functions
virtual Notifier	getNotifier () const =0
template<typename T >
bool	send (Packet &packet, const std::vector< T > &data)
Data Access
State	getState () const
bool	isClosed () const
bool	isConnected () const
bool	isListening () const
void	setDescription (ConnectionDescriptionPtr description)
	Set the connection parameter description.
ConnectionDescriptionPtr	getDescription () const
Connection State Changes
virtual bool	connect ()
	Connect to the remote peer.
virtual bool	listen ()
	Put the connection into the listening state.
virtual void	close ()
	Close a connected or listening connection.
Listener Interface
void	addListener (ConnectionListener *listener)
	Add a listener for connection state changes.
void	removeListener (ConnectionListener *listener)
	Remove a listener for connection state changes.
Asynchronous accept
virtual void	acceptNB ()
	Start an accept operation.
virtual ConnectionPtr	acceptSync ()
	Complete an accept operation.
Asynchronous read
void	recvNB (void *buffer, const uint64_t bytes)
	Start a read operation on the connection.
bool	recvSync (void *buffer, uint64_t bytes, const bool block=true)
	Finish reading data from the connection.
void	getRecvData (void *buffer, uint64_t bytes)
virtual void	readNB (void *buffer, const uint64_t bytes)=0
	Start a read operation on the connection.
virtual int64_t	readSync (void *buffer, const uint64_t bytes, const bool block)=0
	Finish reading data from the connection.
Static Public Member Functions
static ConnectionPtr	create (ConnectionDescriptionPtr description)
	Create a new connection.
Public Types
enum	State { STATE_CLOSED, STATE_CONNECTING, STATE_CONNECTED, STATE_LISTENING, STATE_CLOSING }
	The current state of the Connection. More...
typedef int	Notifier
	The Notifier used by the ConnectionSet to detect readiness of a Connection.
Protected Member Functions
void	_fireStateChanged ()
Protected Attributes
State	_state
	The connection state.
ConnectionDescriptionPtr	_description
	The connection parameters.
base::Lock	_sendLock
	The lock used to protect multiple write calls.
Protected Types
enum	ReadStatus { READ_TIMEOUT = -2, READ_ERROR = -1 }
Synchronous write to the connection
static bool	send (const Connections &connections, const Packet &packet, const bool isLocked=false)
	Sends a packaged message to multiple connections.
static bool	send (const Connections &connections, Packet &packet, const void *data, const uint64_t size, const bool isLocked=false)
	Sends a packaged message including additional data to multiple connections.
static bool	send (const Connections &connections, Packet &packet, const void const items, const uint64_t *itemSizes, const size_t nItems)
	Sends a packaged message including additional, multiple data items to multiple connections.
bool	send (const void *buffer, const uint64_t bytes, const bool isLocked=false)
	Send data using the connection.
void	lockSend () const
	Lock the connection, no other thread can send data.
void	unlockSend () const
	Unlock the connection.
bool	send (const Packet &packet)
	Sends a packaged message using the connection.
bool	send (Packet &packet, const std::string &string)
	Sends a packaged message including a string using the connection.
template<typename T >
bool	send (Packet &packet, const std::vector< T > &data)
	Sends a packaged message including additional data.
bool	send (Packet &packet, const void *data, const uint64_t size)
	Sends a packaged message including additional data using the connection.
virtual int64_t	write (const void *buffer, const uint64_t bytes)=0
	Write data to the connection.

Detailed Description

An interface definition for communication between hosts.

Connections are stream-oriented point-to-point communications. The parameters of a Connection are described in a ConnectionDescription, which is used in listen() and connect(). A Connection has a State, which changes when calling listen(), connect() or close(), or whenever the underlying connection is closed by the operating system.

The Connection class defines the interface for connections, various derived classes implement it for various low-level communication protocols, e.g., SocketConnection for TCP/IP. An implementation may not implement all the functionality defined in this interface.

The Connection is used reference-counted in eq::net, since it has multiple owners, such as the ConnectionSet and Node.

Definition at line 66 of file connection.h.

Member Enumeration Documentation

enum eq::net::Connection::State

The current state of the Connection.

Enumerator:

STATE_CLOSED	Closed, initial state.
STATE_CONNECTING	A connect() or listen() is in progress.
STATE_CONNECTED	The connection has been connected and is open.
STATE_LISTENING	The connection is listening for connects.
STATE_CLOSING	A close() is in progress.

Definition at line 69 of file connection.h.

Member Function Documentation

virtual void eq::net::Connection::acceptNB ( ) [inline, virtual]

Start an accept operation.

This method returns immediately. The Notifier will signal a new connection request, upon which acceptSync() should be used to finish the accept operation.

See also:: acceptSync()

Definition at line 166 of file connection.h.

virtual ConnectionPtr eq::net::Connection::acceptSync ( ) [inline, virtual]

Complete an accept operation.

Returns:: the new connection, 0 on error.

Definition at line 173 of file connection.h.

void eq::net::Connection::addListener ( ConnectionListener * listener )

Add a listener for connection state changes.

virtual bool eq::net::Connection::connect ( ) [inline, virtual]

Connect to the remote peer.

The ConnectionDescription of this connection is used to identify the peer's parameters.

Returns:: true if the connection was successfully connected, false if not.

Reimplemented in eq::net::PairConnection.

Definition at line 127 of file connection.h.

static ConnectionPtr eq::net::Connection::create ( ConnectionDescriptionPtr description ) [static]

Create a new connection.

This factory method creates a new concrete connection for the requested type. The description is set on the created Connection.

Parameters:

description the connection parameters.

Returns:: the connection.

ConnectionDescriptionPtr eq::net::Connection::getDescription ( ) const

Returns:: the description for this connection.

virtual Notifier eq::net::Connection::getNotifier ( ) const [pure virtual]

Returns:: the notifier signaling events on the connection.

Implemented in eq::net::BufferConnection, and eq::net::PairConnection.

State eq::net::Connection::getState ( ) const [inline]

Returns:: the State of this connection.

Definition at line 93 of file connection.h.

References _state.

bool eq::net::Connection::isClosed ( ) const [inline]

Returns:: true if the connection is in the closed state.

Definition at line 96 of file connection.h.

References _state, and STATE_CLOSED.

bool eq::net::Connection::isConnected ( ) const [inline]

Returns:: true if the connection is in the connected state.

Definition at line 99 of file connection.h.

References _state, and STATE_CONNECTED.

bool eq::net::Connection::isListening ( ) const [inline]

Returns:: true if the connection is in the listening state.

Definition at line 102 of file connection.h.

References _state, and STATE_LISTENING.

virtual bool eq::net::Connection::listen ( ) [inline, virtual]

Put the connection into the listening state.

The ConnectionDescription of this connection is used to identify the listening parameters.

Returns:: true if the connection is listening for new incoming connections, false if not.

Definition at line 138 of file connection.h.

void eq::net::Connection::lockSend ( ) const [inline]

Lock the connection, no other thread can send data.

Definition at line 263 of file connection.h.

References _sendLock, and eq::base::Lock::set().

Here is the call graph for this function:

virtual void eq::net::Connection::readNB	(	void *	buffer,
		const uint64_t	bytes
	)		`[pure virtual]`

Start a read operation on the connection.

This method is the low-level counterpart to recvNB().

This function returns immediately. The operation's Notifier will signal data availability, upon which readSync() should be used to finish the operation.

Parameters:

buffer	the buffer receiving the data.
bytes	the number of bytes to read.

See also:: readSync()

Implemented in eq::net::BufferConnection, and eq::net::PairConnection.

virtual int64_t eq::net::Connection::readSync	(	void *	buffer,
		const uint64_t	bytes,
		const bool	block
	)		`[pure virtual]`

Finish reading data from the connection.

This method is the low-level counterpart to recvSync(). It may return with a partial read.

Parameters:

buffer	the buffer receiving the data.
bytes	the number of bytes to read.
block	internal WAR parameter, ignore it in the implementation unless you know exactly why not.

Returns:: the number of bytes read, or -1 upon error.

Implemented in eq::net::BufferConnection, and eq::net::PairConnection.

void eq::net::Connection::recvNB	(	void *	buffer,
		const uint64_t	bytes
	)

Start a read operation on the connection.

This function returns immediately. The Notifier will signal data availability, upon which recvSync() should be used to finish the operation.

Parameters:

buffer	the buffer receiving the data.
bytes	the number of bytes to read.

See also:: recvSync()

bool eq::net::Connection::recvSync	(	void **	buffer,
		uint64_t *	bytes,
		const bool	block = `true`
	)

Finish reading data from the connection.

This function may block even if data availability was signaled, i.e., when only a part of the data requested has been received. The buffer and bytes return value pointers can be 0. This method uses readNB() and readSync() to fill a buffer, potentially by using multiple reads.

Parameters:

buffer	return value, the buffer pointer passed to recvNB().
bytes	return value, the number of bytes read.
block	internal WAR parameter, do not use unless you know exactly why.

Returns:: true if all requested data has been read, false otherwise.

void eq::net::Connection::removeListener ( ConnectionListener * listener )

Remove a listener for connection state changes.

bool eq::net::Connection::send	(	Packet &	packet,
		const void *	data,
		const uint64_t	size
	)

Sends a packaged message including additional data using the connection.

Parameters:

packet	the message packet.
data	the data.
size	the data size in bytes.

Returns:: true if all data has been read, false if not.

static bool eq::net::Connection::send	(	const Connections &	connections,
		Packet &	packet,
		const void *	data,
		const uint64_t	size,
		const bool	isLocked = `false`
	)		`[static]`

Sends a packaged message including additional data to multiple connections.

Parameters:

connections	The connections.
packet	the message packet.
data	the data.
size	the data size in bytes.
isLocked	true if the connection is locked externally.

Returns:: true if the packet was sent successfully to all receivers.

bool eq::net::Connection::send ( const Packet & packet ) [inline]

Sends a packaged message using the connection.

Parameters:

packet the message packet.

Returns:: true if all data has been read, false if not.

Definition at line 273 of file connection.h.

References send(), and eq::net::Packet::size.

Referenced by send().

Here is the call graph for this function:

Here is the caller graph for this function:

template<typename T >

bool eq::net::Connection::send	(	Packet &	packet,
		const std::vector< T > &	data
	)

Sends a packaged message including additional data.

The last item of the packet has to be able to hold one item or eight bytes of the data, whatever is bigger.

Parameters:

packet	the message packet.
data	the vector containing the data.

Returns:: true if all data has been read, false if not.

Definition at line 9 of file connection.h.

static bool eq::net::Connection::send	(	const Connections &	connections,
		Packet &	packet,
		const void const	items,
		const uint64_t *	itemSizes,
		const size_t	nItems
	)		`[static]`

Sends a packaged message including additional, multiple data items to multiple connections.

Automatically locks each individual connection during send. The data items are appended to the packet individually as a 8-byte size token followed by size bytes data. The packet.size is updated to the size of all data send (packet + sizes + items).

Parameters:

connections	The connections.
packet	the message packet.
items	a pointer array to the data items.
itemSizes	an array containing the size of each item.
nItems	the number of data elements.

Returns:: true if the packet was sent successfully to all receivers.

bool eq::net::Connection::send	(	const void *	buffer,
		const uint64_t	bytes,
		const bool	isLocked = `false`
	)

Send data using the connection.

A send may be performed using multiple write() operations. For thread-safe sending from multiple threads it is therefore crucial to protect the send() operation internally. If the connection is not already locked externally, it will use an internal mutex.

Parameters:

buffer	the buffer containing the message.
bytes	the number of bytes to send.
isLocked	true if the connection is locked externally.

Returns:: true if all data has been read, false if not.

See also:: lockSend(), unlockSend()

static bool eq::net::Connection::send	(	const Connections &	connections,
		const Packet &	packet,
		const bool	isLocked = `false`
	)		`[static]`

Sends a packaged message to multiple connections.

Parameters:

connections	The connections.
packet	the message packet.
isLocked	true if the connection is locked externally.

Returns:: true if the packet was sent successfully to all connections.

bool eq::net::Connection::send	(	Packet &	packet,
		const std::string &	string
	)		`[inline]`

Sends a packaged message including a string using the connection.

The packet has to define a 8-byte-aligned, 8-char string at the end of the packet. When the packet is sent the whole string is appended to the packet, so that the receiver has to do nothing special to receive and use the full packet.

Parameters:

packet	the message packet.
string	the string.

Returns:: true if all data has been read, false if not.

Definition at line 288 of file connection.h.

References send().

Referenced by send().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Connection::setDescription ( ConnectionDescriptionPtr description )

Set the connection parameter description.

Parameters:

description the connection parameters.

void eq::net::Connection::unlockSend ( ) const [inline]

Unlock the connection.

Definition at line 265 of file connection.h.

References _sendLock, and eq::base::Lock::unset().

Here is the call graph for this function:

virtual int64_t eq::net::Connection::write	(	const void *	buffer,
		const uint64_t	bytes
	)		`[pure virtual]`

Write data to the connection.

Parameters:

buffer	the buffer containing the message.
bytes	the number of bytes to write.

Returns:: the number of bytes written, or -1 upon error.

Implemented in eq::net::BufferConnection, and eq::net::PairConnection.

Member Data Documentation

base::Lock eq::net::Connection::_sendLock [mutable, protected]

The lock used to protect multiple write calls.

Definition at line 395 of file connection.h.

Referenced by lockSend(), and unlockSend().

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

eq::net::Connection Class Reference

Public Member Functions

Static Public Member Functions

Public Types

Protected Member Functions

Protected Attributes

Protected Types

Synchronous write to the connection

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation