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 ()
CO_API void	setID (const UUID &identifier)
	Set the object's unique identifier.
const UUID &	getID () const
uint32_t	getInstanceID () const
CO_API bool	isBuffered () const
CO_API bool	isMaster () const
Versioning
virtual ChangeType	getChangeType () const
virtual uint64_t	getMaxVersions () const
	Limit the number of queued versions of slave instances.
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 void	push (const uint128_t &groupID, const uint128_t &objectType, const Nodes &nodes)
	Push the instance data of the object to the given nodes.
virtual CO_API uint128_t	commit (const uint32_t incarnation=CO_COMMIT_NEXT)
	Commit a new version of this object.
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.
template<class T >
bool	send (NodePtr node, ObjectPacket &packet, const std::vector< T > &v)
	Send a packet to peer object instance(s) on another node.
Notifications
virtual void	notifyAttach ()
	Notify that this object will be registered or mapped.
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.
virtual void	notifyDetached ()
	Notify that this object has been deregistered or unmapped.

uint32_t	getMasterInstanceID () const
NodePtr	getMasterNode ()
void	addSlave (Command &command)
CO_API void	removeSlave (NodePtr node, const uint32_t instanceID)
CO_API void	removeSlaves (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 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	VersionedMasterCM
class	ObjectCM
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 39 of file 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 43 of file object.h.

Constructor & Destructor Documentation

CO_API co::Object::Object ( )

Construct a new distributed object.

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

Destruct the distributed 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.

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.

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

Commit a new version of this object.

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 an application-specific frame loop. Decreasing the incarnation counter will lead to undefined results.

Parameters:

incarnation the commit incarnation for auto obsoletion.

Returns:: the new head version.

Reimplemented in co::ObjectMap, and co::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::ObjectMap, co::Serializable, and co::Barrier.

Definition at line 99 of file object.h.

References STATIC.

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

Returns:: the latest available (head) version.

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

Returns:: the object's unique identifier.

Definition at line 82 of file object.h.

Referenced by co::DataIStream::operator>>().

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.

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 85 of file 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 67 of file object.h.

virtual uint64_t co::Object::getMaxVersions ( ) const [inline, virtual]

Limit the number of queued versions of slave instances.

Changing the return value of this method causes the master instance to block during commit() if any slave instance has reached the maximum number of queued versions. The method is called on the slave instance. Multiple slave instances may use different values.

Changing the return value at runtime, that is, after the slave instance has been mapped is unsupported and causes undefined behavior.

Not supported on master instances for slave object commits. Open an issue if you need this.

Returns:: the number of queued versions a slave instance may have.

Version:: 1.3.2

Definition at line 119 of file 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 61 of file object.h.

Referenced by co::DataOStream::operator<<(), and send().

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, commit() will exit early.

Returns:: true if a commit is needed.

Reimplemented in co::ObjectMap, and co::Serializable.

Definition at line 144 of file object.h.

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

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

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

Notify that this object will be registered or mapped.

The method is called from the thread initiating the registration or mapping, before the operation is executed.

Definition at line 338 of file object.h.

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 co::Serializable, and co::ObjectMap.

Definition at line 347 of file 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()

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

Notify that this object has been deregistered or unmapped.

The method is called from the thread initiating the deregistration or unmapping, after the operation has been executed.

Definition at line 364 of file object.h.

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 receiver thread, which is different from the node main thread. The object should not be sync()'ed from this notification, as this might lead to deadlocks and 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. In particular do not perform any potentially blocking operations from this method.

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 273 of file object.h.

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

NOP assignment operator.

Definition at line 421 of file 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 303 of file object.h.

References getInstanceData().

Here is the call graph for this function:

CO_API void co::Object::push	(	const uint128_t &	groupID,
		const uint128_t &	objectType,
		const Nodes &	nodes
	)

Push the instance data of the object to the given nodes.

Used to push object data from a Node, instead of pulling it during mapping. Does not establish any mapping, that is, the receiving side will typically use LocalNode::mapObject with VERSION_NONE to establish a slave mapping. On each receiving node, LocalNode::objectPush() is called once per node.

Buffered objects do not re-serialize their instance data. Multicast connections are preferred, that is, for a set of nodes sharing one multicast connection the data is only send once.

Parameters:

groupID	An identifier to group a set of push operations.
objectType	A per-push identifier.
nodes	The vector of nodes to push to.

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 std::string &	string
	)

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.

template<class T >

bool co::Object::send	(	NodePtr	node,
		ObjectPacket &	packet,
		const std::vector< T > &	v
	)		`[inline]`

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

Definition at line 452 of file object.h.

References isAttached().

Here is the call graph for this function:

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.

CO_API void co::Object::setID ( const UUID & identifier )

Set the object's unique identifier.

Only to be called on unattached objects. The application has to ensure the uniqueness of the identifier in the peer-to-peer node network. By default, each object has an identifier guaranteed to be unique. During mapping, the identifier of the object will be overwritten with the identifier of the master object.

Version:: 1.1.5

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 on the same object from multiple threads has to be protected by the caller using a mutex.

Parameters:

version the version to synchronize (see above).