Main Page   Modules   Namespace List   Class Hierarchy   Compound List   Namespace Members   Compound Members   Related Pages  

GNE::PingPacket Class Reference
[Mid-Level API]

#include <PingPacket.h>

Inheritance diagram for GNE::PingPacket:

GNE::Packet List of all members.

Public Types

typedef SmartPtr< PingPacket > sptr
typedef WeakPtr< PingPacket > wptr

Public Member Functions

 PingPacket (bool makeReq=true)
 Creates a PingPacket with a preassigned request ID which is pulled from an internal source.

bool isRequest ()
 Is this PingPacket a ping request?

void makeReply ()
 Changes this PingPacket from a ping request to a ping reply.

PingInformation getPingInformation ()
 If this packet is a ping reply that is from one of our requests, this finds the round-trip time and clock offset.

virtual int getSize () const
 Returns the current size of this packet in bytes.

virtual void writePacket (Buffer &raw) const
 Writes the packet to the given Buffer.

virtual void readPacket (Buffer &raw)
 Reads this packet from the given Buffer.


Static Public Member Functions

int recoverLostRequests (Time limit)
 Every time you create a packet, the request ID is placed into a request table so that the time difference can be measured later.

int reqsPending ()
 Returns the number of pending requests.

Packet * create ()
 Returns a new instance of this class using the constructor to pass in false, so this returns an object in an uninitialized state and suitable only to call readPacket on.


Static Public Attributes

const int ID = 4
 The ID for this type of packet.

Detailed Description

Using the PingPacket is one way to measure ping and clock offsets from a remote machine. Measuring ping and clock offset are very similar operations in how they work, and because the extra overhead of measuring clock offset is small, that functionality was added into PingPacket. The effectiveness of the clock synchronization is discussed in the GNE Protocol specification, available on the GNE web site. Ping capability was not integrated into the Connection class to give you the largest flexibility on how to measure latency and ping in your games.

A choice had to be made between synchronizing actual real clock times, or synchronizing on an arbitrary server clock. Due to the fact that absolute time clocks have less resolution in some platforms (ie Windows), and because of possible difficulties surrounding differing timezones and GMT-UTC differences, the clock synchronization will be based on an arbitrary clock on the server. This allows the server to use the clock with the highest resolution, and perhaps more importantly, the server can use the same clock for synchronizing and for timing the game logic. The important part to know from this is that the clock offsets may be extreme (as GMT is used in Linux, and seconds since CPU powerup in Windows), and thus may not fit into a 32-bit integer with microsecond accuracy.

Since the PingPackets will be placed into the queue and received as normal, this will be measuring effective ping rather than the actual time it takes for the packet to travel there and back, giving a more realistic view of lag.

The way to use PingPackets:

Check out the exping example for an example and more explaination on how to use PingPacket.

Constructor & Destructor Documentation

GNE::PingPacket::PingPacket (  bool  makeReq = true  ) 
 

Creates a PingPacket with a preassigned request ID which is pulled from an internal source.

Only ping requests are made using the constructor -- you should use getReply when you get a ping request to make the ping response packet.

The PingPacket::create function passes in false to get an uninitalized PingPacket for reading. You will probably only ever use the default form of the constructor. If you pass false, the state of this object is undefined after creation and is suitable only to use readPacket on.

Member Function Documentation

PingInformation GNE::PingPacket::getPingInformation (   ) 
 

If this packet is a ping reply that is from one of our requests, this finds the round-trip time and clock offset.

Calling this function will remove the request ID from the request table, so this function will only work once for each reply. If the request ID was not found, then times of 0 will be returned.

void GNE::PingPacket::makeReply (   ) 
 

Changes this PingPacket from a ping request to a ping reply.

If the PingPacket is already a reply, this function has no net effect.

int GNE::PingPacket::recoverLostRequests (  Time  limit  )  [static]
 

Every time you create a packet, the request ID is placed into a request table so that the time difference can be measured later.

This takes up some memory. It is possible that a ping reply is never received, espically if sending PingPackets over an unreliable connection. This function will remove any packets that have been pending for longer than the time specified. It will return the number of packets that were considered lost based on the specified pending time limit and remove these requests from the table. If a reply for one of these lost requests comes back, getPing will be unable to find them and return an elapsed time of 0.

When GNE is shutdown the request table will be cleared out so you don't have to ever call this function unless you want to find out how many more packets have been lost, or if you want to free some memory.

int GNE::PingPacket::reqsPending (   )  [static]
 

Returns the number of pending requests.

This number increases by 1 every time a request is made, and goes down by one with a successful call to getPing. The number will also decrease if recoverLostReqests is called and finds late requests.

The documentation for this class was generated from the following files:
Generated on Fri Aug 22 13:40:06 2003 for GNE by doxygen1.3