A generic, distributed object. More...

#include <object.h>

Inheritance diagram for co::Object:

Collaboration diagram for co::Object:

Public Member Functions
CO_API	Object ()
	Construct a new distributed object.
virtual CO_API	~Object ()
	Destruct the distributed object.
Data Access
bool	isAttached () const
LocalNodePtr	getLocalNode ()
const base::UUID &	getID () const
uint32_t	getInstanceID () const
CO_API bool	isBuffered () const
CO_API bool	isMaster () const
Versioning
virtual ChangeType	getChangeType () const
virtual CO_API uint32_t	chooseCompressor () const
	Return the compressor to be used for data transmission.
virtual bool	isDirty () const
	Return if this object needs a commit.
CO_API uint128_t	commit (const uint32_t incarnation=CO_COMMIT_NEXT)
	Commit a new version of this object.
virtual CO_API uint32_t	commitNB (const uint32_t incarnation)
	Start committing a new version of this object.
virtual CO_API uint128_t	commitSync (const uint32_t commitID)
	Finalize a commit transaction.
CO_API void	setAutoObsolete (const uint32_t count)
	Automatically obsolete old versions.
CO_API uint32_t	getAutoObsolete () const
virtual CO_API uint128_t	sync (const uint128_t &version=VERSION_HEAD)
	Sync to a given version.
CO_API uint128_t	getHeadVersion () const
CO_API uint128_t	getVersion () const
virtual CO_API void	notifyNewHeadVersion (const uint128_t &version)
	Notification that a new head version was received by a slave object.
virtual void	notifyNewVersion ()
	Notification that a new version was received by a master object.
Serialization methods for instantiation and versioning.
virtual void	getInstanceData (DataOStream &os)=0
	Serialize all instance information of this distributed object.
virtual void	applyInstanceData (DataIStream &is)=0
	Deserialize the instance data.
virtual void	pack (DataOStream &os)
	Serialize the modifications since the last call to commit().
virtual void	unpack (DataIStream &is)
	Deserialize a change.
Packet Transmission
CO_API bool	send (NodePtr node, ObjectPacket &packet)
	Send a packet to peer object instance(s) on another node.
CO_API bool	send (NodePtr node, ObjectPacket &packet, const std::string &string)
	Send a packet to peer object instance(s) on another node.
CO_API bool	send (NodePtr node, ObjectPacket &packet, const void *data, const uint64_t size)
	Send a packet to peer object instance(s) on another node.
Notifications
virtual void	notifyAttached ()
	Notify that this object has been registered or mapped.
virtual CO_API void	notifyDetach ()
	Notify that this object will be deregistered or unmapped.

CO_API void	setID (const base::UUID &identifier)
uint32_t	getMasterInstanceID () const
NodePtr	getMasterNode ()
void	addSlave (Command &command, NodeMapObjectReplyPacket &reply)
void	removeSlave (NodePtr node)
void	setMasterNode (NodePtr node)
void	addInstanceDatas (const ObjectDataIStreamDeque &, const uint128_t &)
void	setupChangeManager (const Object::ChangeType type, const bool master, LocalNodePtr localNode, const uint32_t masterInstanceID)
virtual CO_API void	attach (const base::UUID &id, const uint32_t instanceID)
virtual CO_API void	detach ()
void	transfer (Object *from)
void	applyMapData (const uint128_t &version)
void	sendInstanceData (Nodes &nodes)
Public Types
enum	ChangeType { NONE, STATIC, INSTANCE, DELTA, UNBUFFERED }
	Object change handling characteristics, see Programming Guide. More...
Protected Member Functions
CO_API	Object (const Object &)
	Copy constructor.
const Object &	operator= (const Object &)
	NOP assignment operator.
Friends
class	DeltaMasterCM
class	FullMasterCM
class	MasterCM
class	StaticMasterCM
class	StaticSlaveCM
class	UnbufferedMasterCM
class	VersionedSlaveCM

Detailed Description

A generic, distributed object.

Please refer to the Programming Guide and examples on how to develop and use distributed objects.

See also:: eq::Object

Definition at line 40 of file co/object.h.

Member Enumeration Documentation

enum co::Object::ChangeType

Object change handling characteristics, see Programming Guide.

Enumerator:

STATIC	non-versioned, static object.
INSTANCE	use only instance data
DELTA	use pack/unpack delta
UNBUFFERED	versioned, but don't retain versions

Definition at line 44 of file co/object.h.

Constructor & Destructor Documentation

CO_API co::Object::Object ( )

Construct a new distributed object.

Reimplemented in eq::fabric::Object.

virtual CO_API co::Object::~Object ( ) [virtual]

Destruct the distributed object.

Reimplemented in eq::fabric::Object.

CO_API co::Object::Object ( const Object & ) [protected]

Copy constructor.

Member Function Documentation

virtual void co::Object::applyInstanceData ( DataIStream & is ) [pure virtual]

Deserialize the instance data.

This method is called during object mapping to populate slave instances with the master object's data.

Parameters:

is	the input stream.

Implemented in co::Barrier, eq::Frame, eq::FrameData, eqNbody::InitData, eqPly::InitData, eqPly::VertexBufferDist, eVolve::InitData, and osgScaleViewer::InitData.

Referenced by unpack().

Here is the caller graph for this function:

virtual CO_API uint32_t co::Object::chooseCompressor ( ) const [virtual]

Return the compressor to be used for data transmission.

This default implementation chooses the compressor with the highest compression ratio with lossless compression for EQ_COMPRESSOR_DATATYPE_BYTE tokens. The application may override this method to deactivate compression by returning EQ_COMPRESSOR_NONE or to select object-specific compressors.

CO_API uint128_t co::Object::commit ( const uint32_t incarnation = CO_COMMIT_NEXT )

Commit a new version of this object.

This method is a convenience function for commitSync( commitNB( incarnation )).

Objects using the change type STATIC can not be committed.

Master instances will increment new versions continously, starting at VERSION_FIRST. If the object has not changed, no new version will be generated, that is, the current version is returned. The high value of the returned version will always be 0.

Slave objects can be commited, but have certain caveats for serialization. Please refer to the Programming Guide for more details. Slave object commits will return a random version on a successful commit, or VERSION_NONE if the object has not changed since the last commit. The high value of a successful commit will never be 0.

The incarnation count is meaningful for buffered master objects. The commit implementation will keep all instance data committed with an incarnation count newer than current_incarnation - getAutoObsolete(). By default, each call to commit creates a new incarnation, retaining the data from last getAutoObsolete() commit calls. When the application wishes to auto obsolete by another metric than commit calls, it has to consistently provide an incarnation counter. Buffers with a higher incarnation count than the current are discarded. A typical use case is to tie the auto obsoletion to rendering frames in a visualization application.

Parameters:

incarnation the commit incarnation for auto obsoletion.

Returns:: the new head version.

See also:: commitNB(), commitSync()

Reimplemented in eq::fabric::Config< S, C, O, L, CV, N, V >, and eq::fabric::Config< Server, Config, Observer, Layout, Canvas, Node, ConfigVisitor >.

Referenced by eqNbody::Config::handleEvent(), osgScaleViewer::Config::startFrame(), and eVolve::Config::startFrame().

Here is the caller graph for this function:

virtual CO_API uint32_t co::Object::commitNB ( const uint32_t incarnation ) [virtual]

Start committing a new version of this object.

The commit transaction has to be completed using commitSync, passing the returned identifier.

Parameters:

incarnation the commit incarnation for auto obsoletion.

Returns:: the commit identifier to be passed to commitSync

See also:: commit(), commitSync()

Reimplemented in eq::fabric::Object, and eqNbody::FrameData.

Referenced by eqNbody::FrameData::commitNB().

Here is the caller graph for this function:

virtual CO_API uint128_t co::Object::commitSync ( const uint32_t commitID ) [virtual]

Finalize a commit transaction.

Parameters:

commitID the commit identifier returned from commitNB

Returns:: the new head version.

See also:: commit()

Reimplemented in eq::fabric::Serializable.

CO_API uint32_t co::Object::getAutoObsolete ( ) const

Returns:: get the number of versions this object retains.

virtual ChangeType co::Object::getChangeType ( ) const [inline, virtual]

Returns:: how the changes are to be handled.

Reimplemented in co::Barrier, eq::fabric::Channel< W, C >, eq::fabric::Node< C, N, P, V >, eq::fabric::Pipe< N, P, W, V >, eq::fabric::Serializable, eq::fabric::Window< P, W, C >, eq::Frame, eq::FrameData, eqNbody::SharedDataProxy, eqPly::FrameData, eVolve::FrameData, osgScaleViewer::FrameData, eq::fabric::Channel< Window, Channel >, eq::fabric::Node< Config, Node, Pipe, NodeVisitor >, eq::fabric::Pipe< Node, Pipe, eq::Window, PipeVisitor >, and eq::fabric::Window< Pipe, Window, Channel >.

Definition at line 88 of file co/object.h.

References STATIC.

CO_API uint128_t co::Object::getHeadVersion ( ) const

Returns:: the latest available (head) version.

const base::UUID& co::Object::getID ( ) const [inline]

Returns:: the object's unique identifier.

Definition at line 71 of file co/object.h.

Referenced by eqPly::Channel::frameClear(), eqPly::Channel::frameViewFinish(), eqPly::Config::getModel(), osgScaleViewer::Config::init(), eVolve::Config::init(), eVolve::Config::mapData(), co::DataIStream::operator>>(), and eqPly::Config::sync().

Here is the caller graph for this function:

virtual void co::Object::getInstanceData ( DataOStream & os ) [pure virtual]

Serialize all instance information of this distributed object.

Parameters:

os	The output stream.

Implemented in co::Barrier, eq::Frame, eq::FrameData, eqNbody::InitData, eqPly::InitData, eqPly::VertexBufferDist, eVolve::InitData, and osgScaleViewer::InitData.

Referenced by pack().

Here is the caller graph for this function:

uint32_t co::Object::getInstanceID ( ) const [inline]

Returns:: the node-wide unique object instance identifier.

Definition at line 74 of file co/object.h.

LocalNodePtr co::Object::getLocalNode ( ) [inline]

Returns:: the local node to which this object is mapped, or 0 if the object is not mapped.

Definition at line 68 of file co/object.h.

CO_API uint128_t co::Object::getVersion ( ) const

Returns:: the currently synchronized version.

bool co::Object::isAttached ( ) const [inline]

Returns:: true if the object is attached, mapped or registered.

Definition at line 62 of file co/object.h.

Referenced by eVolve::Config::mapData(), co::DataOStream::operator<<(), and eqPly::Config::unmapData().

Here is the caller graph for this function:

virtual bool co::Object::isDirty ( ) const [inline, virtual]

Return if this object needs a commit.

This function is used for optimization, to detect early that no commit is needed. If it returns true, pack() or getInstanceData() will be executed. The serialization methods can still decide to not write any data, upon which no new version will be created. If it returns false, commitNB() and commitSync() will exit early.

Returns:: true if a commit is needed.

Reimplemented in eq::fabric::Object, and eq::fabric::Serializable.

Definition at line 112 of file co/object.h.

CO_API bool co::Object::isMaster ( ) const

Returns:: true if this instance is the master version, false otherwise.

Referenced by eq::fabric::Serializable::notifyAttached(), and eqPly::Config::unmapData().

Here is the caller graph for this function:

virtual void co::Object::notifyAttached ( ) [inline, virtual]

Notify that this object has been registered or mapped.

The method is called from the thread initiating the registration or mapping, after the operation has been completed successfully.

See also:: isMaster()

Reimplemented in eq::Config, and eq::fabric::Serializable.

Definition at line 304 of file co/object.h.

virtual CO_API void co::Object::notifyDetach ( ) [virtual]

Notify that this object will be deregistered or unmapped.

The method is called from the thread initiating the deregistration or unmapping, before the operation is executed.

See also:: isMaster()

Reimplemented in eq::Config, eq::fabric::Canvas< CFG, C, S, L >, eq::fabric::Config< S, C, O, L, CV, N, V >, eq::fabric::Layout< C, L, V >, eq::fabric::Node< C, N, P, V >, eq::fabric::Object, eq::fabric::Pipe< N, P, W, V >, eq::fabric::Window< P, W, C >, eq::fabric::Canvas< Config, Canvas, Segment, Layout >, eq::fabric::Config< Server, Config, Observer, Layout, Canvas, Node, ConfigVisitor >, eq::fabric::Layout< Config, Layout, View >, eq::fabric::Node< Config, Node, Pipe, NodeVisitor >, eq::fabric::Pipe< Node, Pipe, eq::Window, PipeVisitor >, and eq::fabric::Window< Pipe, Window, Channel >.

virtual CO_API void co::Object::notifyNewHeadVersion ( const uint128_t & version ) [virtual]

Notification that a new head version was received by a slave object.

The notification is send from the command thread, which is different from the node main thread. The object should not be sync()'ed from this notification, as this might lead to synchronization issues with the application thread changing the object. Its purpose is to send a message to the application, which then takes the appropriate action.

Parameters:

version The new head version.

virtual void co::Object::notifyNewVersion ( ) [inline, virtual]

Notification that a new version was received by a master object.

See also:: comment in notifyNewHeadVersion().

Definition at line 242 of file co/object.h.

const Object& co::Object::operator= ( const Object & ) [inline, protected]

NOP assignment operator.

Definition at line 372 of file co/object.h.

virtual void co::Object::pack ( DataOStream & os ) [inline, virtual]

Serialize the modifications since the last call to commit().

No new version will be created if no data is written to the output stream.

Parameters:

os	the output stream.

Reimplemented in co::Barrier.

Definition at line 272 of file co/object.h.

References getInstanceData().

Here is the call graph for this function:

CO_API bool co::Object::send	(	NodePtr	node,
		ObjectPacket &	packet,
		const std::string &	string
	)

Send a packet to peer object instance(s) on another node.

CO_API bool co::Object::send	(	NodePtr	node,
		ObjectPacket &	packet
	)

Send a packet to peer object instance(s) on another node.

CO_API bool co::Object::send	(	NodePtr	node,
		ObjectPacket &	packet,
		const void *	data,
		const uint64_t	size
	)

Send a packet to peer object instance(s) on another node.

CO_API void co::Object::setAutoObsolete ( const uint32_t count )

Automatically obsolete old versions.

The versions for the last count commits are retained. The actual number of versions retained may be less since a commit does not always generate a new version.

Parameters:

count the number of versions to retain, excluding the head version.

Referenced by eVolve::Config::init().

Here is the caller graph for this function:

virtual CO_API uint128_t co::Object::sync ( const uint128_t & version = VERSION_HEAD ) [virtual]

Sync to a given version.

Objects using the change type STATIC can not be synced.

Syncing to VERSION_HEAD syncs up to the last received version, does not block and always returns true. Syncing to VERSION_NEXT applies one new version, potentially blocking. Syncing to VERSION_NONE does nothing.

Slave objects can be synced to VERSION_HEAD, VERSION_NEXT or to any version generated by a commit on the master instance. Syncing to a concrete version applies all pending deltas up to this version and potentially blocks.

Master objects can only be synced to VERSION_HEAD, VERSION_NEXT or to any version generated by a commit on a slave instance. Syncing to a concrete version applies only this version and potentially blocks.

The different sync semantics for concrete versions originate from the fact that master versions are continous and ordered, while slave versions are random and unordered.

This function is not thread safe, that is, calling sync() simultaneously from multiple threads has to be protected by the caller using a mutex.

Parameters:

version the version to synchronize (see above).