G3D::LightweightConduit Class Reference

#include <NetworkDevice.h>

Classes
class	PacketSizeException

Public Member Functions
	~LightweightConduit ()
int	maxMessageSize () const
template<typename T >
void	send (const NetAddress &a, uint32 type, const T &msg)
template<typename T >
void	send (const Array< NetAddress > &a, uint32 type, const T &m)
bool	receive (NetAddress &sender)
template<typename T >
bool	receive (NetAddress &sender, T &message)
bool	receive ()
virtual uint32	waitingMessageType ()
virtual bool	messageWaiting ()
Public Member Functions inherited from G3D::Conduit
virtual	~Conduit ()
uint64	bytesSent () const
uint64	messagesSent () const
uint64	bytesReceived () const
uint64	messagesReceived () const
bool	ok () const
Public Member Functions inherited from G3D::ReferenceCountedObject
virtual	~ReferenceCountedObject ()

Static Public Member Functions
static LightweightConduitRef	create (uint16 receivePort, bool enableReceive, bool enableBroadcast)

Private Member Functions
	LightweightConduit (uint16 receivePort, bool enableReceive, bool enableBroadcast)
void	sendBuffer (const NetAddress &a, BinaryOutput &b)
template<typename T >
void	serializeMessage (uint32 type, const T &m, BinaryOutput &b) const

Private Attributes
bool	alreadyReadMessage
NetAddress	messageSender
uint32	messageType
Array< uint8 >	messageBuffer
int	MTU

Friends
class	NetworkDevice

Additional Inherited Members
Protected Member Functions inherited from G3D::Conduit
	Conduit ()
Protected Attributes inherited from G3D::Conduit
uint64	mSent
uint64	mReceived
uint64	bSent
uint64	bReceived
SOCKET	sock
BinaryOutput	binaryOutput

Detailed Description

Provides fast but unreliable transfer of messages. On a LAN, LightweightConduit will probably never drop messages but you might get your messages out of order. On an internet connection it might drop messages altogether. Messages are never corrupted, however. LightweightConduit requires a little less setup and overhead than ReliableConduit. ReliableConduit guarantees message delivery and order but requires a persistent connection.

To set up a LightweightConduit (assuming you have already made subclasses of G3D::NetMessage based on your application's pcommunication protocol):

[Server Side]

1. Call LightweightConduit::create(port, true, false), where port is the port on which you will receive messages.

2. Poll LightweightConduit::messageWaiting from your main loop. When it is true (or, equivalently, when LightweightConduit::waitingMessageType is non-zero) there is an incoming message.

3. To read the incoming message, call LightweightConduit::receive with the appropriate class type, which mist have a deserialize method. LightweightConduit::waitingMessageType tells you what class is needed (you make up your own message constants for your program; numbers under 1000 are reserved for G3D's internal use).

4. When done, simply set the G3D::LightweightConduitRef to NULL or let it go out of scope and the conduit cleans itself up automatically.

[Client Side]

1. Call G3D::LightweightConduit::create(). If you will broadcast to all servers on a LAN, set the third optional argument to true (the default is false for no broadcast). You can also set up the receive port as if it was a server to send and receive from a single LightweightConduit.

2. To send, call G3D::LightweightConduit::send with the target address and a pointer to an instance of the message you want to send.

3. When done, simply set the G3D::LightweightConduitRef to NULL or let it go out of scope and the conduit cleans itself up automatically.

Deprecated:

Constructor & Destructor Documentation

G3D::LightweightConduit::LightweightConduit ( uint16  receivePort, bool  enableReceive, bool  enableBroadcast  )

private

 {
 NetworkDevice* nd = NetworkDevice::instance();

 Log::common()->print("Creating a UDP socket ");
 sock = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
 
 if (sock == SOCKET_ERROR) {
 sock = 0;
 Log::common()->println("FAIL");
 Log::common()->println(socketErrorCode());
 return;
 }
 Log::common()->println("Ok");

 if (enableReceive) {
 debugAssert(port != 0);
 if (! nd->bind(sock, NetAddress(0, port))) {
 nd->closesocket(sock);
 sock = (SOCKET)SOCKET_ERROR;
 }
 }

 // Figuring out the MTU seems very complicated, so we just set it to 1000,
 // which is likely to be safe. See IP_MTU for more information.
 MTU = 1000;

 increaseBufferSize(sock);

 if (enableBroadcast) {
 int TR = true;
 if (setsockopt(sock, SOL_SOCKET, SO_BROADCAST, 
 (const char*)&TR, sizeof(TR)) != 0) {
 Log::common()->println("Call to setsockopt failed");
 Log::common()->println(socketErrorCode());
 nd->closesocket(sock);
 sock = 0;
 return;
 }
 }

 Log::common()->printf("Done creating UDP socket %d\n", sock);

 alreadyReadMessage = false;
}

Here is the call graph for this function:

Here is the caller graph for this function:

G3D::LightweightConduit::~LightweightConduit

(

)

Closes the socket.

 {
}

Member Function Documentation

LightweightConduitRef G3D::LightweightConduit::create ( uint16  receivePort, bool  enableReceive, bool  enableBroadcast  )

static

 {
 
 return LightweightConduitRef(new LightweightConduit(receivePort, enableReceive, enableBroadcast));
}

Here is the call graph for this function:

int G3D::LightweightConduit::maxMessageSize ( ) const

inline

The maximum length of a message that can be sent (G3D places a small header at the front of each UDP packet; this is already taken into account by the value returned).

 {
 return MTU - 4;
 }

Here is the caller graph for this function:

bool G3D::LightweightConduit::messageWaiting ( )

virtual

If true, receive will return true.

Reimplemented from G3D::Conduit.

 {
 // We may have already pulled the message off the network stream
 return alreadyReadMessage || Conduit::messageWaiting();
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool G3D::LightweightConduit::receive

(

NetAddress &

sender

)

 {
 // This both checks to ensure that a message was waiting and
 // actively consumes the message from the network stream if
 // it has not been read yet.
 uint32 t = waitingMessageType();
 if (t == 0) {
 return false;
 }

 sender = messageSender;
 alreadyReadMessage = false;

 if (messageBuffer.size() < 4) {
 // Something went wrong
 return false;
 }

 return true;
}

Here is the call graph for this function:

template<typename T >

bool G3D::LightweightConduit::receive ( NetAddress &  sender, T &  message  )

inline

 {
 bool r = receive(sender);
 if (r) {
 BinaryInput b((messageBuffer.getCArray() + 4), 
 messageBuffer.size() - 4, 
 G3D_LITTLE_ENDIAN, BinaryInput::NO_COPY);
 message.deserialize(b);
 }

 return r;
 }

Here is the call graph for this function:

bool G3D::LightweightConduit::receive ( )

inline

 {
 static NetAddress ignore;
 return receive(ignore);
 }

Here is the caller graph for this function:

template<typename T >

void G3D::LightweightConduit::send ( const NetAddress &  a, uint32  type, const T &  msg  )

inline

 {
 binaryOutput.reset();
 serializeMessage(type, msg, binaryOutput);
 sendBuffer(a, binaryOutput);
 }

Here is the call graph for this function:

template<typename T >

void G3D::LightweightConduit::send ( const Array< NetAddress > &  a, uint32  type, const T &  m  )

inline

Send the same message to multiple addresses (only serializes once). Useful when server needs to send to a known list of addresses (unlike direct UDP broadcast to all addresses on the subnet)

 {
 binaryOutput.reset();
 serializeMessage(type, m, binaryOutput);

 for (int i = 0; i < a.size(); ++i) {
 sendBuffer(a[i], binaryOutput);
 }
 }

Here is the call graph for this function:

void G3D::LightweightConduit::sendBuffer ( const NetAddress &  a, BinaryOutput &  b  )

private

 {
 NetworkDevice* nd = NetworkDevice::instance();
 if (sendto(sock, (const char*)b.getCArray(), (int)b.size(), 0,
 (struct sockaddr *) &(a.addr), sizeof(a.addr)) == SOCKET_ERROR) {
 Log::common()->printf("Error occured while sending packet "
 "to %s\n", inet_ntoa(a.addr.sin_addr));
 Log::common()->println(socketErrorCode());
 nd->closesocket(sock);
 } else {
 ++mSent;
 bSent += b.size();
 }
}

Here is the call graph for this function:

Here is the caller graph for this function:

template<typename T >

void G3D::LightweightConduit::serializeMessage ( uint32  type, const T &  m, BinaryOutput &  b  ) const

inlineprivate

 {

 debugAssert(type != 0);
 b.writeUInt32(type);
 m.serialize(b);
 b.writeUInt32(1);
 
 debugAssertM(b.size() < MTU, 
 format("This LightweightConduit is limited to messages of "
 "%d bytes (Ethernet hardware limit; this is the "
 "'UDP MTU')", maxMessageSize()));

 if (b.size() >= MTU) {
 throw LightweightConduit::PacketSizeException(
 format("This LightweightConduit is limited to messages of "
 "%d bytes (Ethernet hardware limit; this is the "
 "'UDP MTU')", maxMessageSize()),
 (int)b.size() - 4, // Don't count the type header
 maxMessageSize());
 }
 }

Here is the call graph for this function:

Here is the caller graph for this function:

uint32 G3D::LightweightConduit::waitingMessageType ( )

virtual

Returns the type of the waiting message (i.e. the type supplied with send). The return value is zero when there is no message waiting.

One way to use this is to have a Table mapping message types to pre-allocated subclasses so receiving looks like:

    // My base class for messages.
    class Message {
        virtual void serialize(BinaryOutput&) const;
        virtual void deserialize(BinaryInput&);
        virtual void process() = 0;
    };

    Message* m = table[conduit->waitingMessageType()];
    conduit->receive(m);
    m->process();

Another is to simply switch on the message type:

    switch (conduit->waitingMessageType()) {
    case 0:
       // No message
       break;

    case ENTITY_SPAWN_MSG:
       {
          EntitySpawnMsg m;
          condiut->receive(m);
          spawnEntity(m.id, m.position, m.modelID);
       }
       break;
       ...
    }
 

Implements G3D::Conduit.

 {
 NetworkDevice* nd = NetworkDevice::instance();
 if (! messageWaiting()) {
 return 0;
 } 

 if (! alreadyReadMessage) {
 messageBuffer.resize(8192);

 SOCKADDR_IN remote_addr;
 int iRemoteAddrLen = sizeof(sockaddr);

 int ret = recvfrom(sock, (char*)messageBuffer.getCArray(), 
 messageBuffer.size(), 0, (struct sockaddr *) &remote_addr, 
 (socklen_t*)&iRemoteAddrLen);

 if (ret == SOCKET_ERROR) {
 Log::common()->println("Error: recvfrom failed in "
 "LightweightConduit::waitingMessageType().");
 Log::common()->println(socketErrorCode());
 nd->closesocket(sock);
 messageBuffer.resize(0);
 messageSender = NetAddress();
 messageType = 0;
 return 0;
 }

 messageSender = NetAddress(remote_addr);

 ++mReceived;
 bReceived += ret;

 messageBuffer.resize(ret, DONT_SHRINK_UNDERLYING_ARRAY);

 // The type is the first four bytes. It is little endian.
 if (System::machineEndian() == G3D_LITTLE_ENDIAN) {
 messageType = *((uint32*)messageBuffer.getCArray());
 } else {
 // Swap the byte order
 for (int i = 0; i < 4; ++i) {
 ((char*)&messageType)[i] = messageBuffer[3 - i];
 }
 }

 alreadyReadMessage = true;
 }

 return messageType;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Function Documentation

friend class NetworkDevice

friend

Member Data Documentation

bool G3D::LightweightConduit::alreadyReadMessage

private

True when waitingForMessageType has read the message from the network into messageType/messageStream.

Array<uint8> G3D::LightweightConduit::messageBuffer

private

The message received (the type has already been read off).

NetAddress G3D::LightweightConduit::messageSender

private

Origin of the received message.

uint32 G3D::LightweightConduit::messageType

private

The type of the last message received.

int G3D::LightweightConduit::MTU

private

Maximum transmission unit (packet size in bytes) for this socket. May vary between sockets.

---

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

• dep/g3dlite/include/G3D/NetworkDevice.h
• dep/g3dlite/source/NetworkDevice.cpp