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

#include <connection.h>

Inheritance diagram for co::Connection:

Collaboration diagram for co::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
CO_API void	setDescription (ConnectionDescriptionPtr description)
	Set the connection parameter description.
CO_API ConnectionDescriptionPtr	getDescription () const
bool	operator== (const Connection &rhs) 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
CO_API void	recvNB (void *buffer, const uint64_t bytes)
	Start a read operation on the connection.
CO_API 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 CO_API 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 CO_API bool	send (const Connections &connections, const Packet &packet, const bool isLocked=false)
	Sends a packaged message to multiple connections.
static CO_API 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 CO_API	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.
CO_API 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.
CO_API 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.
virtual void	finish ()

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 co, since it has multiple owners, such as the ConnectionSet and Node.

Definition at line 63 of file connection.h.

Member Enumeration Documentation

enum co::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 66 of file connection.h.

Member Function Documentation

virtual void co::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 co::Connection::acceptSync ( ) [inline, virtual]

Complete an accept operation.

Returns:: the new connection, 0 on error.

Definition at line 173 of file connection.h.

void co::Connection::addListener ( ConnectionListener * listener )

Add a listener for connection state changes.

virtual bool co::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.

Definition at line 127 of file connection.h.

static CO_API ConnectionPtr co::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.

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

Returns:: the description for this connection.

virtual Notifier co::Connection::getNotifier ( ) const [pure virtual]

Returns:: the notifier signaling events on the connection.

Implemented in co::BufferConnection.

State co::Connection::getState ( ) const [inline]

Returns:: the State of this connection.

Definition at line 90 of file connection.h.

References _state.

bool co::Connection::isClosed ( ) const [inline]

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

Definition at line 93 of file connection.h.

References _state, and STATE_CLOSED.

bool co::Connection::isConnected ( ) const [inline]

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

Definition at line 96 of file connection.h.

References _state, and STATE_CONNECTED.

bool co::Connection::isListening ( ) const [inline]

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

Definition at line 99 of file connection.h.

References _state, and STATE_LISTENING.

virtual bool co::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 co::Connection::lockSend ( ) const [inline]

Lock the connection, no other thread can send data.

Definition at line 263 of file connection.h.

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

Here is the call graph for this function:

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

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

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

CO_API bool co::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 co::Connection::removeListener ( ConnectionListener * listener )

Remove a listener for connection state changes.

static CO_API bool co::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.

static bool CO_API co::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.

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

bool co::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: