eq::net::Connection Class Reference

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

#include <connection.h>

Inheritance diagram for eq::net::Connection:

[legend]

Collaboration diagram for eq::net::Connection:

[legend]

List of all members.

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.
Public Member Functions
virtual Notifier	getNotifier () const
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)
	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)=0
	Finish reading data from the connection.
Static Public Member Functions
static ConnectionPtr	create (ConnectionDescriptionPtr description)
	Create a new 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.
Synchronous write to the connection

static bool	send (const ConnectionVector &connections, const Packet &packet, const bool isLocked=false)
	Sends a packaged message to multiple connections.
static bool	send (const ConnectionVector &connections, Packet &packet, const void *data, const uint64_t size, const bool isLocked=false)
	Sends a packaged message including additional data 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 65 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 68 of file connection.h.

Member Function Documentation

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.

Definition at line 72 of file connection.cpp.

References eq::net::CONNECTIONTYPE_IB, eq::net::CONNECTIONTYPE_MCIP, eq::net::CONNECTIONTYPE_NAMEDPIPE, eq::net::CONNECTIONTYPE_PGM, eq::net::CONNECTIONTYPE_PIPE, eq::net::CONNECTIONTYPE_RSP, eq::net::CONNECTIONTYPE_SDP, eq::net::CONNECTIONTYPE_TCPIP, and EQWARN.

Referenced by eq::net::Node::initConnect(), and eq::net::Node::listen().

Here is the caller graph for this function:

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

Returns:: the State of this connection.

Definition at line 92 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 95 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 98 of file connection.h.

References _state, and STATE_CONNECTED.

Referenced by eq::net::UDPConnection::close(), and eq::net::SocketConnection::close().

Here is the caller graph for this function:

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

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

Definition at line 101 of file connection.h.

References _state, and STATE_LISTENING.

Referenced by eq::net::SocketConnection::close().

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.

Definition at line 380 of file connection.cpp.

References _description, and eq::base::RefPtr< T >::isValid().

Here is the call graph for this function:

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

Returns:: the description for this connection.

Definition at line 375 of file connection.cpp.

References _description.

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::EventConnection, eq::net::MCIPConnection, eq::net::NamedPipeConnection, eq::net::PairConnection, eq::net::PipeConnection, eq::net::RSPConnection, eq::net::SocketConnection, and eq::net::UDPConnection.

Definition at line 126 of file connection.h.

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.

Reimplemented in eq::net::MCIPConnection, eq::net::NamedPipeConnection, eq::net::RSPConnection, eq::net::SocketConnection, and eq::net::UDPConnection.

Definition at line 137 of file connection.h.

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

Add a listener for connection state changes.

Definition at line 123 of file connection.cpp.

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

Remove a listener for connection state changes.

Definition at line 128 of file connection.cpp.

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()

Reimplemented in eq::net::MCIPConnection, eq::net::NamedPipeConnection, eq::net::RSPConnection, eq::net::SocketConnection, and eq::net::UDPConnection.

Definition at line 165 of file connection.h.

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

Complete an accept operation.

Returns:: the new connection, 0 on error.

Reimplemented in eq::net::MCIPConnection, eq::net::NamedPipeConnection, eq::net::RSPConnection, eq::net::SocketConnection, and eq::net::UDPConnection.

Definition at line 172 of file connection.h.

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()

Definition at line 149 of file connection.cpp.

References readNB().

Here is the call graph for this function:

bool eq::net::Connection::recvSync	(	void **	buffer,
		uint64_t *	bytes
	)

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.

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

Definition at line 161 of file connection.cpp.

References _state, EQERROR, EQINFO, EQVERB, readNB(), readSync(), and STATE_CONNECTED.

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::X11Connection, eq::net::BufferConnection, eq::net::EventConnection, eq::net::FDConnection, eq::net::MCIPConnection, eq::net::PairConnection, eq::net::RSPConnection, and eq::net::UDPConnection.

Referenced by recvNB(), and recvSync().

Here is the caller graph for this function:

virtual int64_t eq::net::Connection::readSync	(	void *	buffer,
		const uint64_t	bytes
	)			`[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.

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

Implemented in eq::X11Connection, eq::net::BufferConnection, eq::net::EventConnection, eq::net::FDConnection, eq::net::MCIPConnection, eq::net::PairConnection, eq::net::RSPConnection, and eq::net::UDPConnection.

Referenced by recvSync().

Here is the caller graph for this function:

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()

Definition at line 230 of file connection.cpp.

References _sendLock, EQERROR, EQWARN, and write().

Referenced by send(), and eq::net::UDPConnection::write().

Here is the call graph for this function:

Here is the caller graph for this function:

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

Lock the connection, no other thread can send data.

Definition at line 256 of file connection.h.

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

Referenced by send().

Here is the call graph for this function:

Here is the caller graph for this function:

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

Unlock the connection.

Definition at line 258 of file connection.h.

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

Referenced by send().

Here is the call graph for this function:

Here is the caller graph for this function:

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 266 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:

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 281 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:

template<typename T >

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

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 385 of file connection.h.

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.

Definition at line 265 of file connection.cpp.

References lockSend(), send(), and unlockSend().

Here is the call graph for this function:

bool eq::net::Connection::send	(	const ConnectionVector &	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.

Definition at line 302 of file connection.cpp.

bool eq::net::Connection::send	(	const ConnectionVector &	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.