ZCom_ReplicatorBasic Class Reference

Inheritance diagram for ZCom_ReplicatorBasic:

[legend]Collaboration diagram for ZCom_ReplicatorBasic:

[legend]List of all members.

---

Detailed Description

Interface for standard data replicators.

See also:

Custom Replicators

Interceptor peek support.
The methods getPeekData() and clearPeekData() need to be implemented when the replicator is supposed to be intercepted. Using these methods, the interceptor callback can ask the replicator to peek into the stream, without altering it's read position. Inspecting the data provided by the peekData() method, the callback can then decide if the update should be let through or not. A interceptor trying to see what is in the stream only needs to call the peekData() method. Everything else is handled by the replicator itself. A replicator that should support peeking has to implement peekData(), using getPeekStream() to get the currently processed bitstream. If it needs to allocate memory to hold the data, it has to make use of peekDataStore() in peekData(), and peekDataRetrieve() in clearPeekData(). class MyReplicator : public ZCom_Replicator { void * peekData() { int size = getPeekStream()->getStringSize(); char *string = new char[size]; getPeekStream()->getString(string, size); // store it so it can be deleted later peekDataStore(buf); return (void*) buf; } void clearPeekData() { char *str = peekDataRetrieve(); if (str) delete []str; } Zoidcom automatically notices if data has been stored and calls clearPeekData() after the interceptor has completed. If the stream contains very simple data for which no memory allocation is needed, this will do: void *MyReplicator::peekData() { return (void*) getPeekStream()->getInt(32); } void MyReplicator::clearPeekData() {} More information can be found in the documentation of each peek method.
virtual void	clearPeekData ()=0
	If peekData() has allocated memory, clear it here.
virtual void *	peekData ()=0
	Unpack data from the stream, but don't update the local data.
ZCom_BitStream *	getPeekStream () const
	Get stream currently processed for peeking the data.
void *	peekDataRetrieve ()
	Retrieve the peekbuffer pointer currently stored.
void	peekDataStore (void *_ptr)
	Store pointer to allocated peekbuffer, so it can be deleted again.
Public Member Functions
virtual void	Process (eZCom_NodeRole _localrole, zU32 _simulation_time_passed)=0
	Do any kind of processing.
Update checking.
virtual bool	checkState ()=0
	Find out if data has changed since last time this has been called.
Data packing.
virtual void	packData (ZCom_BitStream *_stream)=0
	Pack current data into the stream.
virtual void	unpackData (ZCom_BitStream *_stream, bool _store, zU32 _estimated_time_sent)=0
	Unpack data from the stream and store it locally.
Protected Attributes
zU8	m_flags
	Additional replicator flags. ZCom_Replicator() c'tor will set this to 0. (ZCOM_REPLICATOR_*).
ZCom_ReplicatorSetup *	m_setup
	pointing to an instance of the setup class - all replication parameters are stored here

---

Member Function Documentation

virtual bool ZCom_ReplicatorBasic::checkState (   )  [pure virtual]

Find out if data has changed since last time this has been called. Returns: 'true' if an update is needed. This won't get called for all connections individually. Instead, Zoidcom calls it once per ZCom_processOutput() and if 'true' is returned, this replicator will get marked dirty internally for all interested connections.

virtual void ZCom_ReplicatorBasic::packData (  ZCom_BitStream *  _stream  )  [pure virtual]

Pack current data into the stream. Parameters: _stream  A stream object you have to feed. This method is a request to write the replicated data into the supplied stream. Make sure the pack and unpackData() methods write exactly as many bits as they read from the stream, otherwise the rest of it becomes unusable. It is also possible to

virtual void ZCom_ReplicatorBasic::unpackData (  ZCom_BitStream *  _stream, bool  _store, zU32  _estimated_time_sent )  [pure virtual]

Unpack data from the stream and store it locally. Parameters: _stream  A stream object you have to extract the data from. _store  If false, only advance the bitstream but do not apply/store the new data. This is needed if an interceptor decided to not apply the update. _estimated_time_sent  gives an msec value trying to estimate the time the data has left the remote ZCom_Control. Execute ZoidCom::getTime() - _estimated_time_sent to find out the data's travel time in msecs. This method is a request to read replicated data from the supplied stream and store it locally. Make sure the pack and unpackData() methods write exactly as many bits as they read from the stream, otherwise the rest of it becomes unusable.

void* ZCom_Replicator::operator new (  size_t  _size  )  [inherited]

Overloaded memory operator ensuring that always Zoidcom's new gets called. Attention: Don't overload this unless you are 100% sure what you are doing.

void ZCom_Replicator::operator delete (  void *  _p  )  [inherited]

Overloaded memory operator ensuring that always Zoidcom's delete gets called. Attention: Don't overload this unless you are 100% sure what you are doing.

virtual void* ZCom_Replicator::peekData (   )  [pure virtual, inherited]

Unpack data from the stream, but don't update the local data. Returns: void* Pointer to peeked data. Interceptors need to call this if they want to know what the update contains without really applying that update. The replicator's peekData() implementation should extract the data from the stream and return it as void*. In case peekData() needs memory to store the peeked data (if the data is a string for example), it can be allocated normally with new or malloc. The resulting pointer should be stored by calling peekDataStore() prior to returning it. When peekDataStore() has been used to store the data pointer, Zoidcom will call clearPeekData() on the replicator as soon as the interceptor, which initiated the call to peekData(), returned. Alternatively, it is also possible to just return the pointer to the allocated memory, and make sure that the interceptors free the memory themselves, afterwards. The bitstream to peek from must be acquired with getPeekStream(). It will be restored to it's previous read position after peekData() has returned. Attention: This may only be called from inside ZCom_NodeReplicationInterceptor::inPreUpdateItem(). Implemented in ZCom_Interpolate< T, SIZE >, and ZCom_Replicate_Numeric< T, SIZE >.

virtual void ZCom_Replicator::clearPeekData (   )  [pure virtual, inherited]

If peekData() has allocated memory, clear it here. This has to be implemented in order to clear up any memory allocated by peekData(). Use peekDataRetrieve() to acquire the pointer stored by peekDataStore() earlier. It is not necessary to call peekDataStore(NULL) to clear the pointer as Zoidcom will do this automatically. This method will get called right after ZCom_NodeReplicationInterceptor::inPreUpdateItem() returned but only if peekDataStore() has been used inside the interceptor. This method will also get called from inside peekDataStore() if it holds a pointer from a previous call to peekDataStore().

ZCom_BitStream* ZCom_Replicator::getPeekStream (   )  const [protected, inherited]

Get stream currently processed for peeking the data. Returns: Pointer to current ZCom_BitStream. As you might have noticed, peekData() does not have a ZCom_BitStream parameter. That's the case because peekData() must be called from inside ZCom_NodeReplicationInterceptor::inPreUpdateItem(), and this interceptor callback has no access to the currently processed stream. Use this method to get a pointer to the currently processed stream instead. This will only return a valid result when called from inside the above mentioned interceptor callback.

void ZCom_Replicator::peekDataStore (  void *  _ptr  )  [protected, inherited]

Store pointer to allocated peekbuffer, so it can be deleted again. Parameters: _ptr  Pointer to the allocated memory. The pointer will get stored in a global Thread Local Storage, so that multiple ZCom_Controls can safely operate simultaneously in different threads. When a replicator's peekData() makes use of this method, expect to get a call to clearPeekData() sometime soon, which is supposed to free the allocated memory again. When you call peekDataStore() more than once with a pointer != NULL, clearPeekData() will get called automatically. Thread Local Storage means, there is one variable for each thread of the program. Replicators could as well declare a member variable used for that purpose instead, but that would waste a lot of memory when peeking interceptors are not used.

void* ZCom_Replicator::peekDataRetrieve (   )  [protected, inherited]

Retrieve the peekbuffer pointer currently stored. Returns: Pointer previously stored with peekDataStore().

virtual void ZCom_Replicator::Process (  eZCom_NodeRole  _localrole, zU32  _simulation_time_passed )  [pure virtual, inherited]

Do any kind of processing. Parameters: _localrole  States the role of the local node. _simulation_time_passed  Time given to ZCom_Control::ZCom_processReplicators() This is intended for replicators that need to perform constant processing like interpolators and extrapolators. Called once everytime ZCom_Control::ZCom_processReplicators() is called. This method will only get called when the replicator has the ZCOM_REPLICATOR_CALLPROCESS flag set.

---

Member Data Documentation

zU8 ZCom_Replicator::m_flags [protected, inherited]

Additional replicator flags. ZCom_Replicator() c'tor will set this to 0. (ZCOM_REPLICATOR_*).

ZCom_ReplicatorSetup* ZCom_Replicator::m_setup [protected, inherited]

pointing to an instance of the setup class - all replication parameters are stored here

---