G3D::NetConnection Class Reference

A network connection between two machines that can send and receive messages. More...

Inherits G3D::NetSendConnection.

Public Types
enum	{   UNLIMITED_BANDWIDTH = NetServer::UNLIMITED_BANDWIDTH,   MAX_CHANNELS = NetServer::MAX_CHANNELS }
enum	NetworkStatus {   WAITING_TO_CONNECT,   JUST_CONNECTED,   CONNECTED,   WAITING_TO_DISCONNECT,   DISCONNECTED }

Public Member Functions
	~NetConnection ()
	To catch accidental dropping of connections that are likely bugs, it is an error to destruct when not DISCONNECTED. More...
virtual NetAddress	address () const
	Address of the other side of the connection. More...
bool	createMessageIterator (const NetChannel &channel, const shared_ptr< _internal::NetServerSideConnection > client=nullptr)
virtual void	disconnect (bool waitForOtherSide=true)
const Array< NetChannel >	getIncomingChannels () const
NetMessageIterator &	incomingMessageIterator (const NetChannel &channel)
	Check the network for new messages and return an iterator over them. More...
RealTime	latency () const
	Estimated one-way latency measured from a large number of round trip times. More...
RealTime	latencyVariance () const
	A measure of variance for latency(). More...
bool	queueMessage (const NetChannel &channel, _ENetPacket *packet)
void	send (NetMessageType type, const void *bytes, size_t size, NetChannel channel=0, const shared_ptr< MemoryManager > &memoryManager=shared_ptr< MemoryManager >())
	Schedule for sending across this connection. More...
void	send (NetMessageType type, const void *bytes, size_t size, BinaryOutput &header, NetChannel channel=0, const shared_ptr< MemoryManager > &memoryManager=shared_ptr< MemoryManager >())
void	send (NetMessageType type, BinaryOutput &bo, NetChannel channel=0)
	Send the contents of this BinaryOutput. More...
void	send (NetMessageType type, BinaryOutput &bo, BinaryOutput &header, NetChannel channel=0)
	Includes a header. More...
void	shutdownSenderThreads ()
NetworkStatus	status ()
	Invoking this can change the status of the connection, so that it may be used in a loop condition. More...
void	submitToSendQueues (const _internal::NetMessage &message)

Static Public Member Functions
static shared_ptr< NetConnection >	connectToServer (const NetAddress &server, uint32 numChannels=1, size_t incomingBytesPerSecondThrottle=UNLIMITED_BANDWIDTH, size_t outgoingBytesPerSecondThrottle=UNLIMITED_BANDWIDTH)
	Return a connection to a server. More...

Protected Types
typedef Table< NetChannel, shared_ptr< NetMessageIterator > >	ChannelMessageIteratorTable

Protected Member Functions
	NetConnection (_ENetPeer *p, _ENetHost *h)
virtual void	beforeSend () override
virtual void	enetsend (NetChannel channel, _ENetPacket *packet)
	Acutally send the packet with enet. More...
void	processFreeQueue ()
virtual void	serviceHost ()=0
	Called from serviceNetwork() on the network thread. More...
void	updateLatencyEstimate ()

Static Protected Member Functions
template<class T , class ... ArgTypes>
static shared_ptr< T >	createShared (ArgTypes &&... args)
	Like std::make_shared, but works for protected constructors. More...

Protected Attributes
_ENetHost *	m_enetHost
_ENetPeer *	m_enetPeer
	nullptr for a NetSendConnection, non-null for a NetConnection More...
ThreadsafeQueue< _internal::NetworkCallbackInfo >	m_freeQueue
	Callbacks to be run the next time any method is invoked. More...
std::atomic< float >	m_latency
	This is a float stored in an int to make it atomic. More...
std::atomic< float >	m_latencyVariance
ChannelMessageIteratorTable	m_netMessageIteratorTable
	Contains the incoming message queue. More...
std::atomic_bool	m_sentRecently
std::atomic< NetworkStatus >	m_status
	This is a NetworkStatus. More...

Friends
class	NetMessageIterator
class	NetServer
void	serviceNetwork ()
	If NOT using G3D's internal threaded networking, you must invoke this periodically to service the receiving side network connections. More...

Detailed Description

A network connection between two machines that can send and receive messages.

By default, the connection is sequenced and reliable.

See also

NetSendConnection, NetServer

Member Typedef Documentation

ChannelMessageIteratorTable

typedef Table<NetChannel, shared_ptr<NetMessageIterator> > G3D::NetConnection::ChannelMessageIteratorTable

protected

Member Enumeration Documentation

anonymous enum

anonymous enum

See also

connectToServer

Enumerator
UNLIMITED_BANDWIDTH
MAX_CHANNELS

NetworkStatus

enum G3D::NetConnection::NetworkStatus

Enumerator
WAITING_TO_CONNECT
JUST_CONNECTED	Connected to the server and the send() or incomingMessageIterator() methods have not yet been invoked.
CONNECTED
WAITING_TO_DISCONNECT	disconnect() has been invoked and no new messages can be sent, but remaining messages are still in transit and will be lost if this process terminates or status() is not invoked repeatedly until the DISCONNECTED state is reached.
DISCONNECTED	connectToServer() never succeeded in establishing a connection, or one end of an established connection was terminated.

Constructor & Destructor Documentation

NetConnection()

G3D::NetConnection::NetConnection ( _ENetPeer *  p, _ENetHost *  h  )

protected

~NetConnection()

G3D::NetConnection::~NetConnection

(

)

To catch accidental dropping of connections that are likely bugs, it is an error to destruct when not DISCONNECTED.

Note that disconnect(false) is guaranteed to immediately disconnect but may drop pending messages.

Member Function Documentation

address()

virtual NetAddress G3D::NetSendConnection::address ( ) const

virtualinherited

Address of the other side of the connection.

beforeSend()

virtual void G3D::NetConnection::beforeSend ( )

overrideprotectedvirtual

Reimplemented from G3D::NetSendConnection.

connectToServer()

static shared_ptr<NetConnection> G3D::NetConnection::connectToServer ( const NetAddress &  server, uint32  numChannels = 1, size_t  incomingBytesPerSecondThrottle = UNLIMITED_BANDWIDTH, size_t  outgoingBytesPerSecondThrottle = UNLIMITED_BANDWIDTH  )

static

Return a connection to a server.

This does not immediately establish the connection– Periodically poll its status() allow it to progrees and to see when the connection succeeds (which may never occur).

Parameters

numChannels

Number of channels (asynchronous message queues) to allocate for communication with the server. See MAX_CHANNELS.

Setting the bandwidth throttles to the actual bandwidth available on the connection may improve performance because optimal packet fragmenting is possible. Setting them lower allows giving preference to another NetConnection; setting them higher may result in slightly decreased performance.

Referenced by G3D::VideoStreamClient::create().

createMessageIterator()

bool G3D::NetConnection::createMessageIterator	(	const NetChannel &	channel,
		const shared_ptr< _internal::NetServerSideConnection >	client = nullptr
	)

createShared()

template<class T , class ... ArgTypes>

static shared_ptr<T> G3D::ReferenceCountedObject::createShared ( ArgTypes &&...  args )

inlinestaticprotectedinherited

Like std::make_shared, but works for protected constructors.

Call as createShared<myclass>.

disconnect()

virtual void G3D::NetConnection::disconnect ( bool  waitForOtherSide = true )

virtual

enetsend()

virtual void G3D::NetSendConnection::enetsend ( NetChannel  channel, _ENetPacket *  packet  )

protectedvirtualinherited

Acutally send the packet with enet.

This allows code reuse with NetConnection, which has a different sending mechanism.

getIncomingChannels()

const Array<NetChannel> G3D::NetConnection::getIncomingChannels

(

)

const

incomingMessageIterator()

NetMessageIterator& G3D::NetConnection::incomingMessageIterator

(

const NetChannel &

channel

)

Check the network for new messages and return an iterator over them.

For same channels this returns the same iterator. If no iterator is available on the channel the return value is a null pointer

latency()

RealTime G3D::NetConnection::latency

(

)

const

Estimated one-way latency measured from a large number of round trip times.

The accuracy of the individual round trip times is at best 1ms, although the combined average may be more accurate. This average may double-count the time for particular messages depending on the send and receive pattern of the application, so it is biased.

latencyVariance()

RealTime G3D::NetConnection::latencyVariance

(

)

const

A measure of variance for latency().

processFreeQueue()

void G3D::NetSendConnection::processFreeQueue ( )

protectedinherited

queueMessage()

bool G3D::NetConnection::queueMessage	(	const NetChannel &	channel,
		_ENetPacket *	packet
	)

send() [1/4]

void G3D::NetSendConnection::send ( NetMessageType  type, const void *  bytes, size_t  size, NetChannel  channel = 0, const shared_ptr< MemoryManager > &  memoryManager = shared_ptr< MemoryManager >()  )

inherited

Schedule for sending across this connection.

Parameters

bytes

By default, the memory will be copied, so it is safe to deallocate or change on return

memoryManager

If notNull, then this memory manager will be used to free bytes once the data has been transmitted. Do not modify or free bytes after invoking send(). If not provided, the contents of bytes are immediately copied and the caller is able to mutate or free it immediately on return. The memoryManagers are queued and can be invoked at the time of any future method invocation. This guarantees that they are run on a thread that the application controls (and not the internal network threads).

Pass a memoryManager when sending large packets to avoid the overhead of copying. Do not pass a memoryManager for small packets, since there is some overhead in initializing the deallocation record.

Parameters

channel

See NetChannel

Messages may be divided over individual packets if large, but are always observed outside of the API as atomic.

Not guaranteed to be delivered if a disconnection occurs on either side before the message is completely transferred, or if this is currently disconnected.

See also

networkSendBacklog

send() [2/4]

void G3D::NetSendConnection::send ( NetMessageType  type, const void *  bytes, size_t  size, BinaryOutput &  header, NetChannel  channel = 0, const shared_ptr< MemoryManager > &  memoryManager = shared_ptr< MemoryManager >()  )

inherited

send() [3/4]

void G3D::NetSendConnection::send ( NetMessageType  type, BinaryOutput &  bo, NetChannel  channel = 0  )

inherited

Send the contents of this BinaryOutput.

This is easier and safer to use than the other version of send(), so it is preferred for general use. However, this method copies the memory, so it is slightly slower than the other overloaded version of send() for large buffers.

See also

networkSendBacklog

send() [4/4]

void G3D::NetSendConnection::send ( NetMessageType  type, BinaryOutput &  bo, BinaryOutput &  header, NetChannel  channel = 0  )

inherited

Includes a header.

The header should be fairly small to avoid increasing latency during the extra copies required.

serviceHost()

virtual void G3D::NetConnection::serviceHost ( )

protectedpure virtual

Called from serviceNetwork() on the network thread.

shutdownSenderThreads()

void G3D::NetSendConnection::shutdownSenderThreads ( )

inherited

status()

NetworkStatus G3D::NetConnection::status

(

)

Invoking this can change the status of the connection, so that it may be used in a loop condition.

submitToSendQueues()

void G3D::NetSendConnection::submitToSendQueues ( const _internal::NetMessage &  message )

inherited

updateLatencyEstimate()

void G3D::NetConnection::updateLatencyEstimate ( )

protected

Friends And Related Function Documentation

NetMessageIterator

friend class NetMessageIterator

friend

NetServer

friend class NetServer

friend

serviceNetwork

void serviceNetwork ( )

friend

If NOT using G3D's internal threaded networking, you must invoke this periodically to service the receiving side network connections.

Receiving messages will only update inside this call–all other network calls queue for processing.

If using G3D's internal threaded networking, this is automatically called continuously on a separate thread.

See also

setNetworkCommunicationInterval, G3D::G3DSpecification::threadedNetwork

Member Data Documentation

m_enetHost

_ENetHost* G3D::NetSendConnection::m_enetHost

protectedinherited

m_enetPeer

_ENetPeer* G3D::NetSendConnection::m_enetPeer

protectedinherited

nullptr for a NetSendConnection, non-null for a NetConnection

m_freeQueue

ThreadsafeQueue<_internal::NetworkCallbackInfo> G3D::NetSendConnection::m_freeQueue

protectedinherited

Callbacks to be run the next time any method is invoked.

m_latency

std::atomic<float> G3D::NetConnection::m_latency

protected

This is a float stored in an int to make it atomic.

m_latencyVariance

std::atomic<float> G3D::NetConnection::m_latencyVariance

protected

m_netMessageIteratorTable

ChannelMessageIteratorTable G3D::NetConnection::m_netMessageIteratorTable

protected

Contains the incoming message queue.

m_sentRecently

std::atomic_bool G3D::NetConnection::m_sentRecently

protected

m_status

std::atomic<NetworkStatus> G3D::NetConnection::m_status

protected

This is a NetworkStatus.