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

#include <connection.h>

Inheritance diagram for co::Connection:

Collaboration diagram for co::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.

Public Member Functions
virtual Notifier	getNotifier () const =0

Data Access
CO_API State	getState () const

bool	isClosed () const

bool	isClosing () const

bool	isConnected () const

bool	isListening () const

CO_API bool	isMulticast () const

CO_API ConstConnectionDescriptionPtr	getDescription () const

bool	operator== (const Connection &rhs) const

Connection State Changes
virtual bool	connect ()
	Connect to the remote peer. More...

virtual bool	listen ()
	Put the connection into the listening state. More...

virtual void	close ()
	Close a connected or listening connection. More...


void	addListener (ConnectionListener *listener)

void	removeListener (ConnectionListener *listener)

Asynchronous accept
virtual void	acceptNB ()
	Start an accept operation. More...

virtual ConnectionPtr	acceptSync ()
	Complete an accept operation. More...

Asynchronous read
CO_API void	recvNB (BufferPtr buffer, const uint64_t bytes)
	Start a read operation on the connection. More...

CO_API bool	recvSync (BufferPtr &buffer, const bool block=true)
	Finish reading data from the connection. More...

BufferPtr	resetRecvData ()

Synchronous write to the connection
CO_API bool	send (const void *buffer, const uint64_t bytes, const bool isLocked=false)
	Send data using the connection. More...

CO_API void	lockSend () const
	Lock the connection, no other thread can send data. More...

CO_API void	unlockSend () const
	Unlock the connection. More...

virtual void	finish ()

Static Public Member Functions
static CO_API ConnectionPtr	create (ConnectionDescriptionPtr desc)
	Create a new connection. More...

Protected Member Functions
	Connection ()
	Construct a new connection. More...

virtual	~Connection ()
	Destruct this connection. More...


CO_API void	_setDescription (ConnectionDescriptionPtr description)

CO_API void	_setState (const State state)

CO_API ConnectionDescriptionPtr	_getDescription ()

Low-level IO methods
enum	ReadStatus { READ_TIMEOUT = -2, READ_ERROR = -1 }
	< error codes for readSync()

virtual void	readNB (void *buffer, const uint64_t bytes)=0
	Start a read operation on the connection. More...

virtual int64_t	readSync (void *buffer, const uint64_t bytes, const bool block)=0
	Finish reading data from the connection. More...

virtual int64_t	write (const void *buffer, const uint64_t bytes)=0
	Write data to the connection. More...

Detailed Description

An interface definition for communication between hosts.

Connections are stream-oriented communication lines. The parameters of a Connection are described in a ConnectionDescription, which is used in create(), listen() and connect(). A Connection has a Connection::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 the low-level communication protocols, e.g., SocketConnection for TCP/IP or RSPConnection for UDP-based reliable multicast. An implementation may not implement all the functionality defined in this interface.

The Connection is used reference-counted throughout the Collage API.

Definition at line 59 of file connection.h.

Member Enumeration Documentation

enum co::Connection::State

The current state of the Connection.

Version: 1.0

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

Constructor & Destructor Documentation

co::Connection::Connection ( )

protected

Construct a new connection.

virtual co::Connection::~Connection ( )

protectedvirtual

Destruct this connection.

Member Function Documentation

CO_API ConnectionDescriptionPtr co::Connection::_getDescription ( )

protected

Returns: the description for this connection.

virtual void co::Connection::acceptNB ( )

inlinevirtual

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. Only one accept operation might be outstanding, that is, acceptSync() has to be called before the next acceptNB().

See also: acceptSync()

Version: 1.0

Definition at line 156 of file connection.h.

virtual ConnectionPtr co::Connection::acceptSync ( )

inlinevirtual

Complete an accept operation.

Returns: the new connection, 0 on error.

Version: 1.0

Definition at line 163 of file connection.h.

virtual void co::Connection::close ( )

inlinevirtual

Close a connected or listening connection.

Version: 1.0

Definition at line 131 of file connection.h.

virtual bool co::Connection::connect ( )

inlinevirtual

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.

Version: 1.0

Definition at line 118 of file connection.h.

static CO_API ConnectionPtr co::Connection::create ( ConnectionDescriptionPtr desc )

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

desc	the connection parameters.

Returns: the connection.

Version: 1.0

CO_API ConstConnectionDescriptionPtr co::Connection::getDescription ( ) const

Returns: the description for this connection.

Version: 1.0

virtual Notifier co::Connection::getNotifier ( ) const

pure virtual

Returns: the notifier signaling events.

Version: 1.0

Implemented in co::BufferConnection.

CO_API State co::Connection::getState ( ) const

Returns: the State of this connection.

Version: 1.0

bool co::Connection::isClosed ( ) const

inline

Returns: true if the connection is closed.

Version: 1.0

Definition at line 89 of file connection.h.

bool co::Connection::isClosing ( ) const

inline

Returns: true if the connection is about to close.

Version: 1.0

Definition at line 91 of file connection.h.

bool co::Connection::isConnected ( ) const

inline

Returns: true if the connection is connected.

Version: 1.0

Definition at line 93 of file connection.h.

bool co::Connection::isListening ( ) const

inline

Returns: true if the connection is listening.

Version: 1.0

Definition at line 95 of file connection.h.

CO_API bool co::Connection::isMulticast ( ) const

Returns: true if this is a multicast connection.

Version: 1.0

virtual bool co::Connection::listen ( )

inlinevirtual

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.

Version: 1.0

Definition at line 129 of file connection.h.

CO_API void co::Connection::lockSend ( ) const

Lock the connection, no other thread can send data.

Version: 1.0

virtual void co::Connection::readNB	(	void *	buffer,
		const uint64_t	bytes
	)

protectedpure virtual

Start a read operation on the connection.

This method is the low-level counterpart used by recvNB(), implemented by the concrete connection.

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

Parameters

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

See also: readSync()

Implemented in co::BufferConnection.

virtual int64_t co::Connection::readSync	(	void *	buffer,
		const uint64_t	bytes,
		const bool	block
	)

protectedpure virtual

Finish reading data from the connection.

This method is the low-level counterpart used by recvSync(), implemented by the concrete connection. 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 co::BufferConnection.

CO_API void co::Connection::recvNB	(	BufferPtr	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. The data will be appended to the given buffer. Only one read operation might be outstanding, that is, readSync() has to be called before the next readNB().

Parameters

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

See also: recvSync()

Version: 1.0

CO_API bool co::Connection::recvSync	(	BufferPtr &	buffer,
		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 received data is appended to the buffer, at most the number of bytes given to recvNB(). This method uses readNB() and readSync() to fill a buffer, potentially by using multiple reads.

Parameters

buffer	return value, the buffer passed to recvNB().
block	internal workaround parameter, do not use unless you know exactly why.

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

Version: 1.0

CO_API bool co::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()

Version: 1.0

CO_API void co::Connection::unlockSend ( ) const

Unlock the connection.

Version: 1.0

virtual int64_t co::Connection::write	(	const void *	buffer,
		const uint64_t	bytes
	)

protectedpure virtual

Write data to the connection.

This method is the low-level counterpart used by send(), implemented by the concrete connection. It may return with a partial write.

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 co::BufferConnection.

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

connection.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Low-level IO methods

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation