eq::net::Connection Class Reference

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

#include <connection.h>

Inheritance diagram for eq::net::Connection:

Collaboration diagram for eq::net::Connection:

List of all members.

Public Types

enum State { STATE_CLOSED, STATE_CONNECTING, STATE_CONNECTED, STATE_LISTENING }

The current state of the Connection. More...

typedef int Notifier

The Notifier used by the ConnectionSet to dedect readyness 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 ()

Input/Output

virtual int64_t write (const void *buffer, const uint64_t bytes)=0

Write data to the connection.

Protected Attributes

State _state

The connection state.

ConnectionDescriptionPtr _description

The connection parameters.

base::Lock _sendLock

The lock used to protect multiple write calls.

Friends

class PairConnection

for access to read/write

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.

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 69 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.

Definition at line 72 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 59 of file connection.cpp.

References eq::net::CONNECTIONTYPE_NAMEDPIPE, eq::net::CONNECTIONTYPE_PIPE, 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 95 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 98 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 101 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 104 of file connection.h.

References _state, and STATE_LISTENING.

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

Set the connection parameter description.

Parameters:

description

the connection parameters.

Definition at line 341 of file connection.cpp.

References _description, eq::net::CONNECTIONTYPE_NAMEDPIPE, eq::net::CONNECTIONTYPE_SDP, eq::net::CONNECTIONTYPE_TCPIP, 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 336 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::NamedPipeConnection, eq::net::PairConnection, eq::net::PipeConnection, and eq::net::SocketConnection.

Definition at line 129 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::NamedPipeConnection, and eq::net::SocketConnection.

Definition at line 140 of file connection.h.

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

Add a listener for connection state changes.

Definition at line 85 of file connection.cpp.

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

Remove a listener for connection state changes.

Definition at line 90 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::NamedPipeConnection, and eq::net::SocketConnection.

Definition at line 168 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::NamedPipeConnection, and eq::net::SocketConnection.

Definition at line 175 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 111 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 123 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::FDConnection, and eq::net::PairConnection.

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::FDConnection, and eq::net::PairConnection.

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 192 of file connection.cpp.

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

Referenced by send(), eq::net::ObjectInstanceDataOStream::sendBuffer(), eq::net::ObjectDeltaDataOStream::sendBuffer(), eq::net::ObjectInstanceDataOStream::sendFooter(), and eq::net::ObjectDeltaDataOStream::sendFooter().

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 260 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 262 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 270 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:

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 285 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 394 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 226 of file connection.cpp.

References lockSend(), send(), eq::net::Packet::size, 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 263 of file connection.cpp.

References eq::net::Packet::size.

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.

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

Definition at line 279 of file connection.cpp.

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

Here is the call graph for this function:

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

Returns:: the notifier signalling events on the connection.

Reimplemented in eq::X11Connection, eq::net::FDConnection, and eq::net::PairConnection.

Definition at line 349 of file connection.h.

virtual int64_t eq::net::Connection::write	(	const void *	buffer,
		const uint64_t	bytes
	)			`[protected, 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::X11Connection, eq::net::BufferConnection, eq::net::FDConnection, and eq::net::PairConnection.

Referenced by send().

Here is the caller graph for this function:

Member Data Documentation

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

The lock used to protect multiple write calls.

Definition at line 373 of file connection.h.

Referenced by lockSend(), send(), and unlockSend().

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


Public Types
enum	State { STATE_CLOSED, STATE_CONNECTING, STATE_CONNECTED, STATE_LISTENING }
	The current state of the Connection. More...
typedef int	Notifier
	The Notifier used by the ConnectionSet to dedect readyness 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 ()
Input/Output
virtual int64_t	write (const void *buffer, const uint64_t bytes)=0
	Write data to the connection.
Protected Attributes
State	_state
	The connection state.
ConnectionDescriptionPtr	_description
	The connection parameters.
base::Lock	_sendLock
	The lock used to protect multiple write calls.
Friends
class	PairConnection
	for access to read/write
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.