Main Page | Class Hierarchy | Class List | Directories | File List | Class Members

RNReplicaNet::ReplicaObject Class Reference

#include <ReplicaObject.h>

Collaboration diagram for RNReplicaNet::ReplicaObject:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 ReplicaObject ()
virtual ~ReplicaObject ()
bool IsReplica (void) const
bool IsMaster (void) const
void Publish (void)
virtual const int GetClassID (void)=0
virtual void SetRegistered (bool flag=true)=0
virtual bool GetRegistered (void)=0
int GetUniqueID (void)
int GetSessionID (void)
ReplicaNetGetBoundReplicaNet (void)
virtual bool ApproveFault (void)
virtual bool ApproveMigration (void)
virtual void OwnerChange (void)
void GiveOwnership (int sessionID)
void RequestOwnership (void)
virtual float CalculateDistanceToObject (ReplicaObject *object)
float GetDistanceToObject (ReplicaObject *object)
virtual void SetOpaquePointer (void *data)
virtual void * GetOpaquePointer (void *data=0)
DataBlockFindDataBlock (void *pdata)
void GiveDeltaHint (float &variable, float delta)
void ContinuityBreak (float &variable, unsigned char breakTypes)
void UpdateSetReliable (void)
void UpdateSetCertain (void)
void UpdateSetUnreliable (void)
bool UpdateIsReliable (void)
bool UpdateIsCertain (void)
bool UpdateIsUnreliable (void)
void SetLoadBalancing (const bool enable=false)
void SetLoadBalancingDefault (const bool defaultValue=false)
bool GetLoadBalancing (void)
void SetLoadScore (const float load=0.0f)
void SetLoadScoreDefault (const float defaultLoad=0.0f)
float GetLoadScore (void)
virtual void PostObjectCreate (void)
virtual void UserRegisterDataBlocks (void)
void AddAutoRegisterDataBlock (DataBlock *const dataBlock)
void SetMessageReflectionID (const int sessionID=kReplicaObjectUnknownUniqueID)
int GetMessageReflectionID (void) const
void SetPropagateToSessionDistance (const float distance=kReplicaObject_InfiniteDistance)
void SetPropagateToSessionDistanceDefault (const float distance=kReplicaObject_InfiniteDistance)
float GetPropagateToSessionDistance (void) const
void SetPropagateToSessionDistanceRecalculationDelay (const float delay=0.1f)
void SetSessionPropagationFilter (const bool enable=false)
bool GetSessionPropagationFilter (void) const
void GetSessionPropagationSet (std::set< int > &theSet)
bool SessionPropagationAddSession (const int sessionID)
bool SessionPropagationRemoveSession (const int sessionID)
virtual void DataBlockPacketDataReceived (const DataBlock *datablock)
virtual s_RO_RegistryBlockGetRegistryBlock (void) const =0

Static Public Member Functions

static ReplicaObjectAllocateForReplicaNet (void)
static void DeleteForReplicaNet (ReplicaObject *object)

Protected Member Functions

virtual void _Internal_GetUpdateType (void)
virtual void _Internal_SetupLoadBalance (void)
virtual void _Internal_SetupLoadBalanceScore (void)
virtual void _Internal_SetupLoadBalanceDefault (void)
virtual void _Internal_SetupLoadBalanceScoreDefault (void)
virtual void _Internal_SetupOpaquePointer (void)
virtual void _Internal_SetupPropagateDistance (void)
virtual void _Internal_SetupPropagateDistanceDefault (void)
void _Internal_SetFullyQualifiedName (const char *name=0)
const char * _Internal_GetFullyQualifiedName (void)
void _DebugInternal_EmitClassCreate (const int packetSize, const int toSession)
void _DebugInternal_EmitClassDelete (const int packetSize, const int toSession)
virtual void RegisterDataBlock (DataBlock *block)

Protected Attributes

bool mDataBlocksRegistered

Friends

class ReplicaNet
class ReplicaNetPrivate
struct SessionUnique
class DataBlock

Detailed Description

A ReplicaObject is the base class that all replica objects use.
For any ReplicaObject derived class that is intended to be used in a network session an instance of ReplicaNet must be created first. However if a ReplicaObject derived class is not intended to be used in a network session there is no requirement to allocate an instance of ReplicaNet. For example, if an application is started without ReplicaNet networking then instances of ReplicaObject will do nothing and use a nominal amount of memory.
Each ReplicaObject class member variable propagated with a DataBlock can have a different packet update type (Unreliable, Certain or Reliable) to the ReplicaObject. When a ReplicaObject is propagated to a session all class member variables that need to send an initial update will temporarily use the update type of the ReplicaObject. This means a ReplicaObject propagated with the Certain update and with a class member variable normally propagated using Unreliable will have the initial variable propagetd using Certain instead. This is to guarantee the initial object state is propagated along with the object propagation packet.


Constructor & Destructor Documentation

RNReplicaNet::ReplicaObject::ReplicaObject  ) 
 

The ctor performs some basic initialisation

virtual RNReplicaNet::ReplicaObject::~ReplicaObject  )  [virtual]
 

The dtor makes sure everything is tidy. If this object has been published the dtor also calls ReplicaNet::RemoveObject(this) to remove the references ReplicaNet holds about this object.


Member Function Documentation

void RNReplicaNet::ReplicaObject::AddAutoRegisterDataBlock DataBlock *const   dataBlock  ) 
 

This function allows DataBlocks to automatically register when a ReplicaObject is created. It is required that the same DataBlocks are registered in the same order for all master and replica objects.

Parameters:
dataBlock the pointer to the DataBlock to register

static ReplicaObject* RNReplicaNet::ReplicaObject::AllocateForReplicaNet void   )  [static]
 

This static function can be defined in a derived class to enable the allocation of a ReplicaObjet derived class to be implemented. The default implementation is to use new.

Returns:
A pointer to an object that is derived from ReplicaObject.

virtual bool RNReplicaNet::ReplicaObject::ApproveFault void   )  [virtual]
 

Use this virtual callback to approve or deny that this object is fault tolerant and can change owner when a session leaves.

Returns:
To approve return true else return false. The default is false

virtual bool RNReplicaNet::ReplicaObject::ApproveMigration void   )  [virtual]
 

Use this virtual callback to approve or deny that this object can migrate when a migrate request is made.

Returns:
To approve return true else return false. The default is false

virtual float RNReplicaNet::ReplicaObject::CalculateDistanceToObject ReplicaObject object  )  [virtual]
 

The callback for calculating the distance to an object. This can (and should) be replaced by the application's object types.

Parameters:
object The destination object to use, if this parameter is null then kReplicaObject_InfiniteDistance should be returned.
Returns:
the distance to the object. The default return value is kReplicaObject_InfiniteDistance meaning that the distance between objects could not be calculated.

void RNReplicaNet::ReplicaObject::ContinuityBreak float &  variable,
unsigned char  breakTypes
 

This is used to set a continuity break for the data set and provides useful information to the extrapolation algorithm

Parameters:
variable the variable to give a hint for
breakTypes The break types to use for this break. For example : DataBlock::ContinuityBreakTypes::kSuddenChange | DataBlock::ContinuityBreakTypes::kTeleport

virtual void RNReplicaNet::ReplicaObject::DataBlockPacketDataReceived const DataBlock datablock  )  [virtual]
 

This virtual callback is triggered by ReplicaNet every time an update packet for a DataBlock is received. See also FindDataBlock()

Parameters:
datablock The pointer to the DataBlock that is getting the update.

static void RNReplicaNet::ReplicaObject::DeleteForReplicaNet ReplicaObject object  )  [static]
 

This static function can be defined in a derived class to enable the de-allocation of a ReplicaObjet derived class to be implemented. The default implementation is to use delete. Care must be taken to use ReplicaNet::RemoveObject(this) properly to remove references held by ReplicaNet if this function is user implemented.

Parameters:
object A pointer to an object that is derived from ReplicaObject.

DataBlock* RNReplicaNet::ReplicaObject::FindDataBlock void *  pdata  ) 
 

Given a pointer to memory this functions finds a data block attached to that memory area

Parameters:
pdata the pointer to the memory area
Returns:
the DataBlock pointer or NULL if no data block is attached

ReplicaNet* RNReplicaNet::ReplicaObject::GetBoundReplicaNet void   ) 
 

Gets the object's bound ReplicaNet class

Returns:
the ReplicaNet pointer that is bound to this object

virtual const int RNReplicaNet::ReplicaObject::GetClassID void   )  [pure virtual]
 

Gets the class id that is set

Returns:
the class id for this class

float RNReplicaNet::ReplicaObject::GetDistanceToObject ReplicaObject object  ) 
 

Gets the distance to another supplied ReplicaObject. This function applies a caching mechanism to avoid too many unwanted calculations

Parameters:
object The destination object to use. If the object pointer is null then kReplicaObject_InfiniteDistance is returned.
Returns:
the distance to the object or kReplicaObject_InfiniteDistance meaning the distance between two objects couldn't be calculated.

bool RNReplicaNet::ReplicaObject::GetLoadBalancing void   ) 
 

Gets the status of the load balancing flag

Returns:
true if load balancing is enabled

float RNReplicaNet::ReplicaObject::GetLoadScore void   ) 
 

Gets the object to report a score based on its "load" for the master session. The definition of "load" units is left to the user. The default return value is 0.0f

Returns:
A "load" score for this object.

int RNReplicaNet::ReplicaObject::GetMessageReflectionID void   )  const
 

This function gets the sessionID used to reflect message updates

Returns:
The sessionID that isused to reflect messages, kReplicaObjectUnknownUniqueID means that the master object sends message updates

virtual void* RNReplicaNet::ReplicaObject::GetOpaquePointer void *  data = 0  )  [virtual]
 

This is a useful virtual call that can be used to obtain opaque pointers to classes or data in a ReplicaObject or the derived class

Parameters:
data the pointer to some optional data that can be passed in. This defaults to null
Returns:
the opaque data pointer

float RNReplicaNet::ReplicaObject::GetPropagateToSessionDistance void   )  const
 

Allows the distance value to be read for this ReplicaObject set by SetPropagateToSessionDistance(). This function can be used on a master or replica ReplicaObject

Returns:
the distance value

virtual bool RNReplicaNet::ReplicaObject::GetRegistered void   )  [pure virtual]
 

Returns the registered flag status of this class

Returns:
the registered state of this class

virtual s_RO_RegistryBlock* RNReplicaNet::ReplicaObject::GetRegistryBlock void   )  const [pure virtual]
 

A pure virtual access method to return the registry block associated with this ReplicaObject class type. This registry block is set when the ReplicaObject derived class is registered with ReplicaNet and the standard interface is implemented by the macro _RO_DO_STD_FRAMEWORK()
For example, to get the registered class name of an unknown "ReplicaObject *theObject" pointer, use the preprocessor to define REPLICANET_VISUALDEBUGGER and then use: theObject->GetRegistryBlock()->GetName().

Returns:
the pointer to the s_RO_RegistryBlock. The registry block contents must not be changed by the user. This function must always return a valid registry block pointer.

int RNReplicaNet::ReplicaObject::GetSessionID void   ) 
 

Returns the session id of the object which is global for the whole network session

Returns:
the session id

bool RNReplicaNet::ReplicaObject::GetSessionPropagationFilter void   )  const
 

Allows the status of the session propagation filter mechanism to be read.

Parameters:
Returns true if the mechanism is enabled

void RNReplicaNet::ReplicaObject::GetSessionPropagationSet std::set< int > &  theSet  ) 
 

Gets the current propagation set.

Parameters:
theSet The current set is stored in this reference.

int RNReplicaNet::ReplicaObject::GetUniqueID void   ) 
 

Returns the unique id of the object local to the session. To identify an object for the entire network session you need to use GetUniqueID() and GetSessionID().

Returns:
the unique id

void RNReplicaNet::ReplicaObject::GiveDeltaHint float &  variable,
float  delta
 

This gives a delta hint for a particular variable that has a float type

Parameters:
variable the variable to give a hint for
delta the delta hint

void RNReplicaNet::ReplicaObject::GiveOwnership int  sessionID  ) 
 

This tries to change the ownership on a ReplicaObject to another session. This only succeeds if the ReplicaObject is a Master object. This only succeeds if the ApproveMigration() callback returns true for the object.

Parameters:
sessionID the target sessionID for this object to migrate to

bool RNReplicaNet::ReplicaObject::IsMaster void   )  const
 

Tests the status of the object to see if it is a master object

Returns:
Returns true if this object is a master copy for the network

bool RNReplicaNet::ReplicaObject::IsReplica void   )  const
 

Tests the status of the object to see if it is a master object

Returns:
Returns true if this object is a replica (copy) from the network

virtual void RNReplicaNet::ReplicaObject::OwnerChange void   )  [virtual]
 

This callback is used whenever an object changes owner

virtual void RNReplicaNet::ReplicaObject::PostObjectCreate void   )  [virtual]
 

This virtual method callback is called by ReplicaNet when a class is created and the initial data from the data blocks has been filled in. The user can choose to override this function if needed. The base class method does not need to be called.

void RNReplicaNet::ReplicaObject::Publish void   ) 
 

Publish this object on to the network. This uses ReplicaNet::AddObject(this) to add a reference of this object to ReplicaNet.

virtual void RNReplicaNet::ReplicaObject::RegisterDataBlock DataBlock block  )  [protected, virtual]
 

Registers a datablock from the derived class to this class. This calls DataBlock::BindReplicaNet(ReplicaObject::GetBoundReplicaNet()), DataBlock::BindReplicaObject(ReplicaObject::this) and DataBlock::SetID(theNextInternalID)

Parameters:
The data block to register

void RNReplicaNet::ReplicaObject::RequestOwnership void   ) 
 

This requests a change of the ownership on a ReplicaObject to be the calling session. This only succeeds if the ReplicaObject is a Replica. This only succeeds if the ApproveMigration() callback returns true for the object.

bool RNReplicaNet::ReplicaObject::SessionPropagationAddSession const int  sessionID  ) 
 

When the session propagation filter mechanism is enabled this function tells this ReplicaObject to propagate to the supplied session ID. This function will only operate correctly when the session propagation filter mechanism is enabled. The session ID must be a valid ID known to the network session. The session ID from the callback ReplicaNet::JoinerSessionIDPre() can be safely added to objects. If the session ID has already been added to the list (without a corresponding remove) then ReplicaNet will ignore extra additions.

Parameters:
sessionID The session ID to propagate to.
Returns:
Returns true if the added sessionID was not in the list. Returns false if the sessionID was in the propagation list.

bool RNReplicaNet::ReplicaObject::SessionPropagationRemoveSession const int  sessionID  ) 
 

When the session propagation filter mechanism is enabled this function tells this ReplicaObject to finish propagating to the supplied session ID. This function will only operate correctly when the session propagation filter mechanism is enabled. The session ID must be a valid ID known to the network session. The session ID from the callback ReplicaNet::LeaverSessionIDPre() can be safely added to objects. If the session ID has already been removed from the list (without a corresponding add) then ReplicaNet will ignore extra remove requests.

Parameters:
sessionID The session ID to finish propagating to.
Returns:
Returns true if the removed sessionID was in the list. Returns false if the sessionID was not in the propagation list.

void RNReplicaNet::ReplicaObject::SetLoadBalancing const bool  enable = false  ) 
 

Enables or disables load balancing for this ReplicaObject.

Parameters:
enable set this to true to enable load balancing. The default is false

void RNReplicaNet::ReplicaObject::SetLoadBalancingDefault const bool  defaultValue = false  ) 
 

This sets the default value that the load balancing uses. Setting the default value in the object constructor to the same value that is set for the load balancing will result in a smaller data packet being sent.

Parameters:
defaultValue the value that is the default value. The default is false to match the parameter to SetLoadBalancing()

void RNReplicaNet::ReplicaObject::SetLoadScore const float  load = 0.0f  ) 
 

Sets the object load unit score.. The definition of "load" units is left to the user. The default return value is 0.0f

Parameters:
load A "load" score for this object.

void RNReplicaNet::ReplicaObject::SetLoadScoreDefault const float  defaultLoad = 0.0f  ) 
 

This sets the default value that the load balancing score uses. Setting the default value in the object constructor to the same value that is set for the load balancing will result in a smaller data packet being sent when an object is published. When setting a default value the same value must be set on the master and all replica objects otherwise the different sessions will assume different default values. If a replica is unable to know that other replicas will set the same default value then not using the function will ensure that the correct value is propagated.

Parameters:
defaultLoad the value that is the default value. The default is 0.0f to match the parameter to SetLoadScore()

void RNReplicaNet::ReplicaObject::SetMessageReflectionID const int  sessionID = kReplicaObjectUnknownUniqueID  ) 
 

This function allows an object to state which sessionID should be used for sending messages to other sessions. By default the master object is used to send DataBlock and message updates.

Parameters:
sessionID the session to be used for sending message updates, the default is kReplicaObjectUnknownUniqueID which signifies that the master sends messages

virtual void RNReplicaNet::ReplicaObject::SetOpaquePointer void *  data  )  [virtual]
 

This is a useful virtual call that can be used to set an opaque pointer to classes or data in a ReplicaObject or the derived class

Parameters:
data the pointer to the opaque data

void RNReplicaNet::ReplicaObject::SetPropagateToSessionDistance const float  distance = kReplicaObject_InfiniteDistance  ) 
 

This functions sets the distance that an object has to be within for it to be propagated relative to a session observer. If a session has an observer and the CalculateDistanceToObject() result is greater than the value specified then the session will not receive object updates. If a session has no registered observer then the object will always be propagated to that session. It is therefore a good idea to publish and set the observer for a session before joining a ReplicaNet session so that the joining session does not receive objects that will then quickly get removed again. The default value for a ReplicaObject is to have this distance set to kReplicaObject_InfiniteDistance, which means that the object will always be propogated to a session. This function can only be used if the ReplicaObject is a master and SetSessionPropagationFilter() is not activated. This distance can be changed at runtime. To ensure this functionality is enabled the first use of this function must be before the object is published using the Publish() method. If the ReplicaObject owner changes, notified through the OwnerChange() callback, then SetPropagateToSessionDistance() must be called to enable this functionality on the new master.

Parameters:
distance the distance to set, kReplicaObject_InfiniteDistance is the default value

void RNReplicaNet::ReplicaObject::SetPropagateToSessionDistanceDefault const float  distance = kReplicaObject_InfiniteDistance  ) 
 

This sets the default value that the propagate distance uses. Setting the default value in the object constructor to the same value that is set for the distance will result in a smaller data packet being sent when an object is published. When setting a default value the same value must be set on the master and all replica objects otherwise the different sessions will assume different default values. If a replica is unable to know that other replicas will set the same default value then not using the function will ensure that the correct value is propagated.

Parameters:
distance the value that is the default value. The default is kReplicaObject_InfiniteDistance to match the parameter to SetPropagateToSessionDistance()

void RNReplicaNet::ReplicaObject::SetPropagateToSessionDistanceRecalculationDelay const float  delay = 0.1f  ) 
 

This function sets the minimum recalculation delay that this object will use when it calculates distance based propagation.
If the object owner changes the delay time will revert back to the default value. The object will, if enabled, automatically recalculate the list of sessions to propagate to.

Parameters:
delay The recalculation delay in seconds, the default is 0.1 seconds. Values less than 0 are ignored.

virtual void RNReplicaNet::ReplicaObject::SetRegistered bool  flag = true  )  [pure virtual]
 

Sets the registered flag to the bool value

Parameters:
flag the value to set the flag to, true is default

void RNReplicaNet::ReplicaObject::SetSessionPropagationFilter const bool  enable = false  ) 
 

This allows the session propagation filter mechanism to be enabled or disabled for a master ReplicaObject. When enabled the ReplicaObject will ignore all joining sessions and the user application is then responsible for supplying the session IDs that this object will propagate to. This mechanism effectively turns off all ReplicaNet object propagation functions for this object, including the distance based propagation. This mechanism can only be enabled or disabled before the object is published to ReplicaNet. If the object is set to reflect updates, using SetMessageReflectionID(), then the reflect session ID must also be added to the session propagation list. If the ReplicaObject owner changes, notified through the OwnerChange() callback, then the previous list of propagated sessions is discarded. SetSessionPropagationFilter() must be called to enable this functionality on the new master and the sessions to propagate to must again be added using SessionPropagationAddSession().

Parameters:
enable When true enables this mechanism. The default value is false and this mechanism is disabled.

bool RNReplicaNet::ReplicaObject::UpdateIsCertain void   ) 
 

Tests the update type for this object.

Returns:
true if this object uses the 'certain' packet type.

bool RNReplicaNet::ReplicaObject::UpdateIsReliable void   ) 
 

Tests the update type for this object.

Returns:
true if this object uses the 'reliable' packet type.

bool RNReplicaNet::ReplicaObject::UpdateIsUnreliable void   ) 
 

Tests the update type for this object.

Returns:
true if this object uses the 'certain' packet type.

void RNReplicaNet::ReplicaObject::UpdateSetCertain void   ) 
 

This sets this object to use the 'certain' packet type when transmitting information about this object to other sessions.
By default the object uses the reliable method.
Each datablock then uses the type of update assigned to itself.

void RNReplicaNet::ReplicaObject::UpdateSetReliable void   ) 
 

This sets this object to use the 'reliable' packet type when transmitting information about this object to other sessions.
By default the object uses the reliable method.
Each datablock then uses the type of update assigned to itself.

void RNReplicaNet::ReplicaObject::UpdateSetUnreliable void   ) 
 

This sets this object to use the 'normal' packet type when transmitting information about this object to other sessions.
By default the object uses the reliable method.
Each datablock then uses the type of update assigned to itself.

virtual void RNReplicaNet::ReplicaObject::UserRegisterDataBlocks void   )  [virtual]
 

Allows the user to expand the datablock mechanism with custom registering of datablocks if needed. It is required that the same DataBlocks are registered in the same order for all master and replica objects. These datablocks are registered after the internal ReplicaObject, ROL derived class datablocks and auto-added datablocks. Any datablocks added by this function should be added using RegisterDataBlock() and not AddAutoRegisterDataBlock() Do not call this function directly, this function is only called by ReplicaNet.


The documentation for this class was generated from the following file:
Generated on Sun Oct 30 01:11:58 2005 for ReplicaNet by  doxygen 1.4.1