eq::net::Object Class Reference

A generic, distributed object. More...

#include <object.h>

Inherited by eq::ConfigDeserializer, eq::fabric::Serializable, eq::Frame, eq::FrameData, eq::net::Barrier, eq::Node, eq::Pipe, eq::server::ConfigSerializer, eq::server::Frame, eq::server::FrameData, eq::server::Node, eq::server::Pipe, eq::server::Window, eq::Window, eqNbody::InitData, eqPly::InitData, eqPly::VertexBufferDist, eVolve::InitData, and osgScaleViewer::InitData.

Collaboration diagram for eq::net::Object:

[legend]

List of all members.

Public Member Functions
	Object ()
	Construct a new distributed object.
virtual	~Object ()
	Destruct the distributed object.
virtual void	attachToSession (const uint32_t id, const uint32_t instanceID, Session *session)
	Called when object is attached to session.
virtual void	detachFromSession ()
	Called when object is detached from session.
virtual void	makeThreadSafe ()
	Make this object thread safe.
bool	isThreadSafe () const
NodePtr	getLocalNode ()
const Session *	getSession () const
Session *	getSession ()
uint32_t	getID () const
uint32_t	getInstanceID () const
uint32_t	getMasterInstanceID () const
bool	isMaster () const
Versioning

virtual ChangeType	getChangeType () const
void	becomeMaster ()
	Switches a slave object to become the master instance.
virtual bool	isDirty () const
	Return if this object needs a commit.
uint32_t	commit ()
	Commit a new version of this object.
virtual uint32_t	commitNB ()
	Start committing a new version of this object.
virtual uint32_t	commitSync (const uint32_t commitID)
	Finalizes a commit transaction.
void	obsolete (const uint32_t version)
	Explicitly obsoletes all versions including version.
void	setAutoObsolete (const uint32_t count, const uint32_t flags=AUTO_OBSOLETE_COUNT_VERSIONS)
	Automatically obsolete old versions.
uint32_t	getAutoObsoleteCount () const
uint32_t	sync (const uint32_t version=VERSION_HEAD)
	Sync to a given version.
uint32_t	getHeadVersion () const
uint32_t	getVersion () const
uint32_t	getOldestVersion () const
virtual void	notifyNewHeadVersion (const uint32_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.
Methods used by session during mapping.

void	setupChangeManager (const Object::ChangeType type, const bool master, const uint32_t masterInstanceID=EQ_ID_INVALID)
	Setup the change manager.
Public Types
enum	ObsoleteFlags { AUTO_OBSOLETE_COUNT_VERSIONS = 0, AUTO_OBSOLETE_COUNT_COMMITS = 1 }
	Flags for auto obsoletion.
enum	ChangeType { STATIC, INSTANCE, DELTA, UNBUFFERED }
	Object change handling characteristics, see Programming Guide. More...
Protected Member Functions
	Object (const Object &)
	Copy constructor.
const Object &	operator= (const Object &)
	NOP assignment operator.
void	removeSlave (NodePtr node)
	Remove a subscribed slave.
Automatic Instantiation and Versioning

virtual void	getInstanceData (DataOStream &os)=0
	Serialize the instance information about this managed 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

bool	send (NodePtr node, ObjectPacket &packet)
	Send a packet to peer object instance(s) on another node.
bool	send (NodePtr node, ObjectPacket &packet, const std::string &string)
	Send a packet to peer object instance(s) on another node.
bool	send (NodePtr node, ObjectPacket &packet, const void *data, const uint64_t size)
	Send a packet to peer object instance(s) on another node.
Friends
class	Session
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 44 of file net/object.h.

Member Enumeration Documentation

enum eq::net::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 57 of file net/object.h.

Constructor & Destructor Documentation

eq::net::Object::Object ( )

Construct a new distributed object.

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

Definition at line 45 of file net/object.cpp.

eq::net::Object::~Object ( ) [virtual]

Destruct the distributed object.

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

Definition at line 65 of file net/object.cpp.

References EQERROR, eq::net::Session::getID(), and eq::net::ObjectCM::ZERO.

Here is the call graph for this function:

eq::net::Object::Object ( const Object & object ) [protected]

Copy constructor.

Definition at line 54 of file net/object.cpp.

Member Function Documentation

virtual void eq::net::Object::applyInstanceData ( DataIStream & is ) [protected, pure virtual]

Deserialize the instance data.

This method is called during object mapping to populate slave instances with the master object's data. The default implementation writes the data into the memory declared by setInstanceData.

Parameters:

is

the input stream.

Implemented in eq::ConfigDeserializer, eq::Frame, eq::FrameData, eq::net::Barrier, eqNbody::InitData, eqPly::InitData, eqPly::VertexBufferDist, eVolve::InitData, osgScaleViewer::InitData, eq::server::ConfigSerializer, eq::server::Frame, and eq::server::FrameData.

Referenced by eq::net::VersionedSlaveCM::applyMapData(), eq::net::StaticSlaveCM::applyMapData(), and unpack().

Here is the caller graph for this function:

void eq::net::Object::attachToSession	(	const uint32_t	id,
		const uint32_t	instanceID,
		Session *	session
	)			`[virtual]`

Called when object is attached to session.

For internal use only.

Reimplemented in eq::Channel, eq::FrameData, eq::Node, eq::Pipe, eq::Window, eq::fabric::Serializable, eq::net::Barrier, eq::server::Channel, eq::server::Node, eq::server::Pipe, and eq::server::Window.

Definition at line 78 of file net/object.cpp.

References EQLOG, eq::net::Session::getCommandThreadQueue(), isMaster(), and eq::net::Dispatcher::registerCommand().

Here is the call graph for this function:

void eq::net::Object::becomeMaster ( )

Switches a slave object to become the master instance.

This function unmaps and registers this instance, making it a master instance with a new identifier. The old master is informed of this change and becomes a slave.

Additional slaves are not informed. The object is synced to the head version before switching.

Definition at line 181 of file net/object.cpp.

References eq::net::ObjectCM::addOldMaster(), EQINFO, getChangeType(), eq::net::Session::getID(), eq::net::Session::getIDMaster(), eq::net::Session::getLocalNode(), getMasterInstanceID(), isMaster(), eq::base::RefPtr< T >::isValid(), eq::net::Session::registerObject(), sync(), eq::net::Session::unmapObject(), and eq::base::UUID::ZERO.

Here is the call graph for this function:

uint32_t eq::net::Object::commit ( )

Commit a new version of this object.

If the object has not changed no new version will be generated, that is, the previous version number is returned. This method is a convenience function for commitNB(); commitSync()

Returns:: the new head version.

See also:: commitNB, commitSync

Reimplemented in eq::fabric::Frustum, eqNbody::FrameData, and eq::server::Frame.

Definition at line 224 of file net/object.cpp.

References commitNB(), and commitSync().

Referenced by eq::server::Frame::commitData(), and eVolve::Config::startFrame().

Here is the call graph for this function:

Here is the caller graph for this function:

uint32_t eq::net::Object::commitNB ( ) [virtual]

Start committing a new version of this object.

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

Returns:: the commit identifier to be passed to commitSync

See also:: commitSync

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

Definition at line 277 of file net/object.cpp.

References eq::net::ObjectCM::commitNB(), and isDirty().

Referenced by commit().

Here is the call graph for this function:

Here is the caller graph for this function:

uint32_t eq::net::Object::commitSync ( const uint32_t commitID ) [virtual]

Finalizes a commit transaction.

Parameters:

commitID

the commit identifier returned from commitNB

Returns:: the new head version.

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

Definition at line 285 of file net/object.cpp.

References eq::net::ObjectCM::commitSync(), and getVersion().

Referenced by commit().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Object::detachFromSession ( ) [virtual]

Called when object is detached from session.

For internal use only.

Definition at line 109 of file net/object.cpp.

uint32_t eq::net::Object::getAutoObsoleteCount ( ) const

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

Definition at line 303 of file net/object.cpp.

References eq::net::ObjectCM::getAutoObsoleteCount().

Referenced by eq::server::Frame::cycleData().

Here is the call graph for this function:

Here is the caller graph for this function:

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

Returns:: how the changes are to be handled.

Reimplemented in eq::Frame, eq::FrameData, eq::fabric::Serializable, eq::fabric::View< L, V, O >, eq::net::Barrier, eqPly::FrameData, eVolve::FrameData, osgScaleViewer::FrameData, eq::server::ConfigSerializer, eq::server::Frame, eq::server::FrameData, and eq::fabric::View< Layout, View, Observer >.

Definition at line 131 of file net/object.h.

References STATIC.

Referenced by becomeMaster(), and eq::net::Session::registerObject().

Here is the caller graph for this function:

uint32_t eq::net::Object::getHeadVersion ( ) const

Returns:: the latest available (head) version.

Definition at line 313 of file net/object.cpp.

References eq::net::ObjectCM::getHeadVersion().

Here is the call graph for this function:

uint32_t eq::net::Object::getID ( ) const [inline]

Returns:: the session-wide unique object identifier.

Definition at line 113 of file net/object.h.

Referenced by eq::net::VersionedSlaveCM::applyMapData(), eq::net::StaticSlaveCM::applyMapData(), eq::ChannelStatistics::ChannelStatistics(), eq::server::Frame::commit(), eqPly::Channel::configInit(), eq::net::Barrier::enter(), eqPly::Channel::frameClear(), eqPly::Channel::frameViewFinish(), eq::server::Config::getDistributorID(), eqPly::VertexBufferDist::getInstanceData(), eVolve::Config::init(), eVolve::Config::mapData(), eqPly::Config::mapData(), eq::net::Session::mapObjectNB(), eq::net::Session::registerObject(), eq::server::Layout::serialize(), eq::server::Canvas::serialize(), eq::net::VersionedSlaveCM::sync(), eq::net::MasterCM::sync(), eq::FrameData::transmit(), eq::server::Observer::unmap(), eq::server::Layout::unmap(), eq::server::Canvas::unmap(), eq::server::CompoundUpdateInputVisitor::visit(), and eq::server::CompoundInitVisitor::visit().

virtual void eq::net::Object::getInstanceData ( DataOStream & os ) [protected, pure virtual]

Serialize the instance information about this managed object.

The default implementation uses the data provided by setInstanceData.

Parameters:

os

The output stream.

Implemented in eq::ConfigDeserializer, eq::Frame, eq::FrameData, eq::net::Barrier, eqNbody::InitData, eqPly::InitData, eqPly::VertexBufferDist, eVolve::InitData, osgScaleViewer::InitData, eq::server::ConfigSerializer, eq::server::Frame, and eq::server::FrameData.

Referenced by eq::net::UnbufferedMasterCM::addSlave(), eq::net::StaticMasterCM::addSlave(), and pack().

Here is the caller graph for this function:

uint32_t eq::net::Object::getInstanceID ( ) const [inline]

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

Definition at line 116 of file net/object.h.

Referenced by eq::net::UnbufferedMasterCM::addSlave(), eq::net::StaticMasterCM::addSlave(), eq::net::VersionedSlaveCM::applyMapData(), eq::net::StaticSlaveCM::applyMapData(), eq::net::VersionedSlaveCM::sync(), eq::net::MasterCM::sync(), and eq::FrameData::update().

Here is the caller graph for this function:

NodePtr eq::net::Object::getLocalNode ( )

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

Definition at line 150 of file net/object.cpp.

References eq::net::Session::getLocalNode().

Referenced by eq::net::VersionedSlaveCM::commitNB(), eq::net::MasterCM::commitNB(), eq::net::VersionedSlaveCM::commitSync(), eq::net::MasterCM::commitSync(), eq::net::VersionedSlaveCM::sync(), eq::FrameData::transmit(), and eq::FrameData::update().

Here is the call graph for this function:

Here is the caller graph for this function:

uint32_t eq::net::Object::getMasterInstanceID ( ) const

Returns:: the master object instance identifier.

For internal use only.

Definition at line 328 of file net/object.cpp.

References eq::net::ObjectCM::getMasterInstanceID().

Referenced by becomeMaster().

Here is the call graph for this function:

Here is the caller graph for this function:

uint32_t eq::net::Object::getOldestVersion ( ) const

Returns:: the oldest available version.

Definition at line 323 of file net/object.cpp.

References eq::net::ObjectCM::getOldestVersion().

Here is the call graph for this function:

Session* eq::net::Object::getSession ( ) [inline]

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

Definition at line 110 of file net/object.h.

const Session* eq::net::Object::getSession ( ) const [inline]

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

Definition at line 104 of file net/object.h.

Referenced by eqPly::VertexBufferDist::applyInstanceData(), eq::server::Frame::cycleData(), eq::net::Barrier::enter(), eq::server::Frame::flush(), eq::View::getConfig(), eq::Node::getFrameData(), eq::Pipe::getView(), eq::Pipe::isCurrent(), eq::FrameData::transmit(), eq::server::Observer::unmap(), eq::server::Layout::unmap(), and eq::server::Canvas::unmap().

Here is the caller graph for this function:

uint32_t eq::net::Object::getVersion ( ) const

Returns:: the currently synchronized version.

Definition at line 318 of file net/object.cpp.

References eq::net::ObjectCM::getVersion().

Referenced by eq::FrameData::addListener(), eq::server::Frame::commit(), commitSync(), eq::net::Barrier::enter(), eq::FrameData::isReady(), notifyNewHeadVersion(), eq::FrameData::setReady(), eq::FrameData::transmit(), eq::server::CompoundUpdateInputVisitor::visit(), and eq::FrameData::waitReady().

Here is the call graph for this function:

Here is the caller graph for this function:

virtual bool eq::net::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. These functions can still decide to not write any data, upon which no new version will be created. If it returns false, commit() will exit early. Applications using asynchronous commits (commitNB(), commitSync()) should use isDirty() to decide if commitNB() should be called.

Returns:: true if a commit is needed.

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

Definition at line 158 of file net/object.h.

Referenced by commitNB().

Here is the caller graph for this function:

bool eq::net::Object::isMaster ( ) const

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

Definition at line 272 of file net/object.cpp.

References eq::net::ObjectCM::isMaster().

Referenced by attachToSession(), becomeMaster(), eq::net::Session::deregisterObject(), eq::server::View::deserialize(), eq::net::Session::mapObjectNB(), and eq::net::Session::unmapObject().

Here is the call graph for this function:

Here is the caller graph for this function:

bool eq::net::Object::isThreadSafe ( ) const [inline]

Returns:: true if the object has been made threadsafe, false if not.

Definition at line 92 of file net/object.h.

void eq::net::Object::makeThreadSafe ( ) [virtual]

Make this object thread safe.

The caller has to ensure that no other thread is using this object when this function is called. If you don't call this function, certain operations, e.g., sync(), are not-threadsafe.

Definition at line 140 of file net/object.cpp.

References eq::net::ObjectCM::makeThreadSafe().

Here is the call graph for this function:

virtual void eq::net::Object::notifyNewHeadVersion ( const uint32_t version ) [inline, 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.

Definition at line 253 of file net/object.h.

References getVersion().

Here is the call graph for this function:

virtual void eq::net::Object::notifyNewVersion ( ) [inline, virtual]

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

See also:: comment in notifyNewHeadVersion().

Definition at line 260 of file net/object.h.

void eq::net::Object::obsolete ( const uint32_t version )

Explicitly obsoletes all versions including version.

The head version can not be obsoleted.

Parameters:

version

the version to obsolete

Definition at line 293 of file net/object.cpp.

References eq::net::ObjectCM::obsolete().

Here is the call graph for this function:

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

NOP assignment operator.

Definition at line 283 of file net/object.h.

virtual void eq::net::Object::pack ( DataOStream & os ) [inline, protected, virtual]

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

No new version will be created if no data is written to the ostream. The default implementation uses the data provided by setDeltaData or setInstanceData.

Parameters:

os

the output stream.

Reimplemented in eq::net::Barrier.

Definition at line 318 of file net/object.h.

References getInstanceData().

Here is the call graph for this function:

void eq::net::Object::removeSlave ( NodePtr node ) [protected]

Remove a subscribed slave.

Parameters:

node

the slave node.

Definition at line 333 of file net/object.cpp.

References eq::net::ObjectCM::removeSlave().

Here is the call graph for this function:

bool eq::net::Object::send	(	NodePtr	node,
		ObjectPacket &	packet,
		const void *	data,
		const uint64_t	size
	)			`[protected]`

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

Definition at line 172 of file net/object.cpp.

References eq::net::Session::getID().

Here is the call graph for this function:

bool eq::net::Object::send	(	NodePtr	node,
		ObjectPacket &	packet,
		const std::string &	string
	)			`[protected]`

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

Definition at line 163 of file net/object.cpp.

References eq::net::Session::getID().

Here is the call graph for this function:

bool eq::net::Object::send	(	NodePtr	node,
		ObjectPacket &	packet
	)			`[protected]`

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

Definition at line 155 of file net/object.cpp.

References eq::net::Session::getID().

Referenced by eq::net::MasterCM::addOldMaster(), eq::net::VersionedSlaveCM::commitNB(), eq::net::MasterCM::commitNB(), eq::net::Barrier::enter(), eq::Window::setPixelViewport(), and eq::FrameData::update().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Object::setAutoObsolete	(	const uint32_t	count,
		const uint32_t	flags = `AUTO_OBSOLETE_COUNT_VERSIONS`
	)

Automatically obsolete old versions.

Flags are a bitwise combination of the following values:

AUTO_OBSOLETE_COUNT_VERSIONS: count 'full' versions are retained. AUTO_OBSOLETE_COUNT_COMMIT: The versions for the last count commits are retained. Note that the number of versions may be less since commit may not generate a new version. This flags takes precedence over AUTO_OBSOLETE_COUNT_VERSIONS.

Parameters:

	count	the number of versions to retain, excluding the head version.
	flags	additional flags for the auto-obsoletion mechanism

Definition at line 298 of file net/object.cpp.

References eq::net::ObjectCM::setAutoObsolete().

Referenced by eq::server::Node::changeLatency(), eq::server::Frame::cycleData(), eq::server::Node::getBarrier(), eVolve::Config::init(), eq::server::CompoundInitVisitor::visit(), and eq::server::ChangeLatencyVisitor::visit().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Object::setupChangeManager	(	const Object::ChangeType	type,
		const bool	master,
		const uint32_t	masterInstanceID = `EQ_ID_INVALID`
	)

Setup the change manager.

Parameters:

	type	the type of the change manager.
	master	true if this object is the master.
	masterInstanceID	the instance identifier of the master object, when master == false.

Definition at line 230 of file net/object.cpp.

References DELTA, INSTANCE, STATIC, and UNBUFFERED.

uint32_t eq::net::Object::sync ( const uint32_t version = VERSION_HEAD )

Sync to a given version.

Syncing to VERSION_HEAD syncs to the last received version, does not block, ignores the timeout and always returns true.

Parameters:

version

the version to synchronize, must be bigger than the current version.