Stream interface for network connections. More...

#include <Stream.hpp>

Inheritance diagram for Sirikata::Network::Stream:

Classes
class	SetCallbacks
	Functor which allows the user to set callbacks for the stream. More...
class	StreamID
	Unique identifier for streams backed by the same connection. More...
Public Types
enum	ConnectionStatus { Connected, ConnectionFailed, Disconnected }
	Specifies the current state of a connection. More...
typedef std::tr1::function < void(void)>	PauseReceiveCallback
	Callback which is passed to a ReceivedCallback, allowing it to pause receiving data.
typedef std::tr1::function < void(ConnectionStatus, const std::string &reason)>	ConnectionCallback
	Callback generated when the current state of the underlying connection changes.
typedef std::tr1::function < void(Stream *, SetCallbacks &)	SubstreamCallback )
	Callback generated when a new substream is initiated by the remote endpoint.
typedef std::tr1::function < void(Chunk &, const PauseReceiveCallback &)>	ReceivedCallback
	Callback generated when another chunk of data is ready.
typedef std::tr1::function< void()>	ReadySendCallback
	Callback generated when the previous send failed and the stream is now ready to accept a message the same size as the message that caused the failure.
Public Member Functions
virtual	~Stream ()
virtual void	connect (const Address &addr, const SubstreamCallback &substreamCallback, const ConnectionCallback &connectionCallback, const ReceivedCallback &receivedCallback, const ReadySendCallback &readySendCallback)=0
	Connect the the specified address and use the callbacks for the new stream.
virtual Stream *	factory ()=0
	Create a new Stream of the same type as this stream.
virtual Stream *	clone (const SubstreamCallback &cb)=0
	Create a new substream backed by the same connection as this stream.
virtual Stream *	clone (const ConnectionCallback &connectionCallback, const ReceivedCallback &chunkReceivedCallback, const ReadySendCallback &readySendCallback)=0
	Create a new substream backed by the same connection as this stream.
virtual void	readyRead ()=0
	Indicate to the Stream that the user is ready to accept more received data.
virtual void	requestReadySendCallback ()=0
virtual bool	send (MemoryReference msg, StreamReliability reliability)=0
	Enqueue a message to be sent, using the specified level of reliability.
virtual bool	send (MemoryReference first_msg, MemoryReference second_msg, StreamReliability reliability)=0
	Enqueue a message which is split in two pieces to be sent, using the specified level of reliability.
virtual bool	send (const Chunk &data, StreamReliability reliability)=0
	Enqueue a message to be sent, using the specified level of reliability.
virtual bool	canSend (size_t dataSize) const =0
	Determine if a message of the specified size could be enqueued to be sent.
virtual Address	getRemoteEndpoint () const =0
	Get the remote endpoint's address.
virtual Address	getLocalEndpoint () const =0
	Get the local endpoint's address.
virtual void	close ()=0
	Close this Stream, notifying the remote endpoint.
virtual Duration	averageSendLatency () const
	Get the average latency spent in queues in the stream.
virtual Duration	averageReceiveLatency () const
	Get the average latency spent in queues in the stream, waiting for deliver to the user.
Static Public Member Functions
static void	ignoreSubstreamCallback (Stream *stream, SetCallbacks &)
	Default SubstreamCallback which ignores the incoming stream.
static void	ignoreConnectionCallback (ConnectionStatus status, const std::string &reason)
	Default ConnectionCallback which ignores the update.
static void	ignoreReceivedCallback (const Chunk &, const PauseReceiveCallback &)
	Default ReceivedCallback which accepts, but ignores, the data.
static void	ignoreReadySendCallback ()
	Default ReadySendCallback which ignores the update.
Protected Member Functions
	Stream ()

Detailed Description

Stream interface for network connections.

Streams are lightweight communication primitives, backed by a shared connection. An individual stream is a reliable, ordered stream of arbitrarily sized messages. The stream only returns full messages to the user.

Streams can be created or cloned efficiently and can start accepting data without having to first go through a connection procedure. When substreams are created by the remote endpoint, the user is notified via a callback. Data can be sent from any thread. Data is received via a callback, but the user can pause callbacks if they cannot handle the rate of callbacks provided by the Stream.

Note that substreams may outlast their parent streams. In this case, further substream callbacks are dispatched to the original callback.

Member Typedef Documentation

typedef std::tr1::function<void(ConnectionStatus,const std::string&reason)> Sirikata::Network::Stream::ConnectionCallback

Callback generated when the current state of the underlying connection changes.

The parameters are a ConnectionStatus indicating the event and a string specifying the reason for the event, if any.

typedef std::tr1::function<void(void)> Sirikata::Network::Stream::PauseReceiveCallback

Callback which is passed to a ReceivedCallback, allowing it to pause receiving data.

Pausing is guaranteed to have finished when the method returns.

typedef std::tr1::function<void()> Sirikata::Network::Stream::ReadySendCallback

Callback generated when the previous send failed and the stream is now ready to accept a message the same size as the message that caused the failure.

typedef std::tr1::function<void(Chunk&, const PauseReceiveCallback&)> Sirikata::Network::Stream::ReceivedCallback

Callback generated when another chunk of data is ready.

The chunk is an entire chunk provided by the sender and will not be fragmented.

The second parameter is a callback which the receiver can invoke to pause the receive stream. If this is invoked, the stream maintains ownership of the data. The stream will resume receive callbacks when the user calls readyRead(). This callback is only valid while the ReceivedCallback is still executing.

The chunk is mutable. It may be destroyed by the user during the callback, but if it is, the user must be sure not to invoke the PauseReceiveCallback.

typedef std::tr1::function<void(Stream*,SetCallbacks&) Sirikata::Network::Stream::SubstreamCallback)

Callback generated when a new substream is initiated by the remote endpoint.

The parameters are a pointer to the new Stream and a functor which allows the user to set the callbacks for the new Stream. The substream's callbacks may only be set in this callback. The user may start sending on the stream as soon as the callbacks have been set.

Member Enumeration Documentation

enum Sirikata::Network::Stream::ConnectionStatus

Specifies the current state of a connection.

Enumerator:

Connected
ConnectionFailed
Disconnected

Constructor & Destructor Documentation

Sirikata::Network::Stream::Stream ( ) [inline, protected]

virtual Sirikata::Network::Stream::~Stream ( ) [inline, virtual]

Member Function Documentation

virtual Duration Sirikata::Network::Stream::averageReceiveLatency ( ) const [inline, virtual]

Get the average latency spent in queues in the stream, waiting for deliver to the user.

This does not include time spent locally in the underlying network library or OS.

Reimplemented in Sirikata::Network::TCPStream.

virtual Duration Sirikata::Network::Stream::averageSendLatency ( ) const [inline, virtual]

Get the average latency spent in queues in the stream.

This does not include time spent locally but buffered in an underlying network library or the OS.

Reimplemented in Sirikata::Network::TCPStream.

virtual bool Sirikata::Network::Stream::canSend ( size_t dataSize ) const [pure virtual]

Determine if a message of the specified size could be enqueued to be sent.

Returns:: true if a message of the specified size could be successfully enqueued

Implemented in Sirikata::Network::TCPStream.

virtual Stream* Sirikata::Network::Stream::clone	(	const ConnectionCallback &	connectionCallback,
		const ReceivedCallback &	chunkReceivedCallback,
		const ReadySendCallback &	readySendCallback
	)		`[pure virtual]`

Create a new substream backed by the same connection as this stream.

Parameters:

connectionCallback	callback to invoke on connection events
chunkReceivedCallback	callback to invoke when messages are received
readySendCallback	callback to invoke when the Stream is ready to accept more data to send

Returns:: a new Stream, or NULL if the Stream cannot be created

Implemented in Sirikata::Network::TCPStream.

virtual Stream* Sirikata::Network::Stream::clone ( const SubstreamCallback & cb ) [pure virtual]

Create a new substream backed by the same connection as this stream.

Parameters:

cb	callback which is called during this method's invocation to allow the user to set the callbacks on the new Stream

Returns:: a new Stream, or NULL if the Stream cannot be created

Implemented in Sirikata::Network::TCPStream.

virtual void Sirikata::Network::Stream::close ( ) [pure virtual]

Close this Stream, notifying the remote endpoint.

If this is the last substream surviving from the original Stream, the underlying connection is closed as well.

Implemented in Sirikata::Network::TCPStream.

Referenced by Sirikata::PintoManagerBase::handleClientReceived(), Sirikata::SpaceNodeConnection::shutdown(), and Sirikata::MasterPintoServerQuerierBase::stop().

virtual void Sirikata::Network::Stream::connect	(	const Address &	addr,
		const SubstreamCallback &	substreamCallback,
		const ConnectionCallback &	connectionCallback,
		const ReceivedCallback &	receivedCallback,
		const ReadySendCallback &	readySendCallback
	)		`[pure virtual]`

Connect the the specified address and use the callbacks for the new stream.

Parameters:

addr	remote endpoint to connect to
substreamCallback	callback to invoke when new substreams are created, including the first stream that will result from this connection
connectionCallback	callback to invoke on connection events
receivedCallback	callback to invoke when a full message has been received
readySendCallback	callback to invoke when the stream is able to send again after previously failing to accept a message

Implemented in Sirikata::Network::TCPStream.

Referenced by Sirikata::MasterPintoServerQuerierBase::connect(), and Sirikata::SpaceNodeConnection::connect().

virtual Stream* Sirikata::Network::Stream::factory ( ) [pure virtual]

Create a new Stream of the same type as this stream.

Returns:: a new Stream, completely independent of this one, of the same type and implementation.

Implemented in Sirikata::Network::TCPStream.

virtual Address Sirikata::Network::Stream::getLocalEndpoint ( ) const [pure virtual]

Get the local endpoint's address.

Returns:: the local endpoint's address, or Address::null() if this Stream has not fully connected yet

Implemented in Sirikata::Network::TCPStream.

virtual Address Sirikata::Network::Stream::getRemoteEndpoint ( ) const [pure virtual]

Get the remote endpoint's address.

Returns:: the remote endpoint's address, or Address::null() if this Stream has not fully connected yet

Implemented in Sirikata::Network::TCPStream.

Referenced by Sirikata::TCPSpaceNetwork::newStreamCallback().

void Sirikata::Network::Stream::ignoreConnectionCallback	(	Stream::ConnectionStatus	status,
		const std::string &	reason
	)		`[static]`

Default ConnectionCallback which ignores the update.

Referenced by Sirikata::Network::MultiplexedSocket::connectionFailureOrSuccessCallback().

void Sirikata::Network::Stream::ignoreReadySendCallback ( ) [static]

Default ReadySendCallback which ignores the update.

Referenced by Sirikata::SpaceNodeConnection::connect(), and Sirikata::ObjectHostConnectionManager::handleNewConnection().

void Sirikata::Network::Stream::ignoreReceivedCallback	(	const Chunk &	c,
		const PauseReceiveCallback &
	)		`[static]`

Default ReceivedCallback which accepts, but ignores, the data.

void Sirikata::Network::Stream::ignoreSubstreamCallback	(	Stream *	stream,
		SetCallbacks &
	)		`[static]`

Default SubstreamCallback which ignores the incoming stream.

The stream is destroyed, causing the remote endpoint to receive a disconnect.

Referenced by Sirikata::MasterPintoServerQuerierBase::connect(), Sirikata::SpaceNodeConnection::connect(), Sirikata::TCPSpaceNetwork::finishOpenConnection(), and Sirikata::Network::MultiplexedSocket::~MultiplexedSocket().

virtual void Sirikata::Network::Stream::readyRead ( ) [pure virtual]

Indicate to the Stream that the user is ready to accept more received data.

This should be called when the user is ready to receive more data after having returned PauseReceive from a ReceivedCallback.

Implemented in Sirikata::Network::TCPStream.

Referenced by Sirikata::TCPSpaceNetwork::RemoteStream::pop().

virtual void Sirikata::Network::Stream::requestReadySendCallback ( ) [pure virtual]

Implemented in Sirikata::Network::TCPStream.

virtual bool Sirikata::Network::Stream::send	(	MemoryReference	msg,
		StreamReliability	reliability
	)		`[pure virtual]`

Enqueue a message to be sent, using the specified level of reliability.

Parameters:

msg	the message to send
reliability	the reliability and ordering to send the message with

Returns:: true if the message was accepted, false if the send failed due to a lost connection or insufficient queue space

Implemented in Sirikata::Network::TCPStream.

Referenced by Sirikata::SpaceNodeConnection::push(), Sirikata::PintoManager::queryHasEvents(), Sirikata::ManualPintoManager::queryHasEvents(), Sirikata::ObjectHostConnectionManager::sendHelper(), Sirikata::ManualPintoManager::sendLocUpdate(), Sirikata::MasterPintoServerQuerierBase::sendQueryUpdate(), and Sirikata::MasterPintoServerQuerierBase::tryServerUpdate().

virtual bool Sirikata::Network::Stream::send	(	MemoryReference	first_msg,
		MemoryReference	second_msg,
		StreamReliability	reliability
	)		`[pure virtual]`

Enqueue a message which is split in two pieces to be sent, using the specified level of reliability.

Parameters:

first_msg	the first part of the message to send
second_msg	the second part of the message to send
reliability	the reliability and ordering to send the message with

Returns:: true if the message was accepted, false if the send failed due to a lost connection or insufficient queue space

Implemented in Sirikata::Network::TCPStream.

virtual bool Sirikata::Network::Stream::send	(	const Chunk &	data,
		StreamReliability	reliability
	)		`[pure virtual]`

Enqueue a message to be sent, using the specified level of reliability.

Parameters:

data	the message to send
reliability	the reliability and ordering to send the message with

Returns:: true if the message was accepted, false if the send failed due to a lost connection or insufficient queue space

Implemented in Sirikata::Network::TCPStream.

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

libcore/include/sirikata/core/network/Stream.hpp
libcore/src/network/Stream.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation