A distributed object. More...

#include <object.h>

Inheritance diagram for co::Object:

Collaboration diagram for co::Object:

Public Types
enum	ChangeType { NONE, STATIC, INSTANCE, DELTA, UNBUFFERED }
	Object change handling characteristics, see Programming Guide. More...

Public Types inherited from co::Dispatcher
typedef CommandFunc< Dispatcher >	Func
	The signature of the base Dispatcher callback. More...

Public Member Functions
virtual CO_API	~Object ()
	Destruct the distributed object. More...

Data Access
CO_API bool	isAttached () const

CO_API LocalNodePtr	getLocalNode ()

CO_API void	setID (const uint128_t &identifier)
	Set the object's unique identifier. More...

CO_API const uint128_t &	getID () const

CO_API 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 on slave instances. More...

virtual CO_API uint32_t	chooseCompressor () const
	Return the compressor to be used for data transmission. More...

virtual bool	isDirty () const
	Return if this object needs a commit. More...

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. More...

virtual CO_API uint128_t	commit (const uint32_t incarnation=CO_COMMIT_NEXT)
	Commit a new version of this object. More...

CO_API void	setAutoObsolete (const uint32_t count)
	Automatically obsolete old versions. More...

CO_API uint32_t	getAutoObsolete () const

virtual CO_API uint128_t	sync (const uint128_t &version=VERSION_HEAD)
	Sync to a given version. More...

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. More...

virtual void	notifyNewVersion ()
	Notification that a new version was received by a master object. More...

Serialization methods for instantiation and versioning.
virtual void	getInstanceData (DataOStream &os)=0
	Serialize all instance information of this distributed object. More...

virtual void	applyInstanceData (DataIStream &is)=0
	Deserialize the instance data. More...

virtual void	pack (DataOStream &os)
	Serialize the modifications since the last call to commit(). More...

virtual void	unpack (DataIStream &is)
	Deserialize a change. More...

Messaging API
CO_API ObjectOCommand	send (NodePtr node, const uint32_t cmd, const uint32_t instanceID=CO_INSTANCE_ALL)
	Send a command with optional data to object instance(s) on another node. More...

Notifications
virtual void	notifyAttach ()
	Notify that this object will be registered or mapped. More...

virtual void	notifyAttached ()
	Notify that this object has been registered or mapped. More...

virtual CO_API void	notifyDetach ()
	Notify that this object will be deregistered or unmapped. More...

virtual void	notifyDetached ()
	Notify that this object has been deregistered or unmapped. More...


uint32_t	getMasterInstanceID () const

NodePtr	getMasterNode ()

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 uint128_t &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 Member Functions inherited from co::Dispatcher
Dispatcher &	operator= (const Dispatcher &)

template<typename T >
void	registerCommand (const uint32_t command, const CommandFunc< T > &func, CommandQueue *queue)
	Register a command member function for a command. More...

virtual CO_API bool	dispatchCommand (ICommand &command)
	Dispatch a command from the receiver thread to the registered queue. More...

Protected Member Functions
CO_API	Object ()
	Construct a new distributed object. More...

Object &	operator= (const Object &)
	NOP assignment operator. More...

CO_API	Object (const Object &)
	Copy construct a new, unattached object. More...

Protected Member Functions inherited from co::Dispatcher
CO_API	Dispatcher (const Dispatcher &from)

CO_API bool	_cmdUnknown (ICommand &command)
	The default handler for handling commands. More...

Friends
class	ObjectStore

Detailed Description

A distributed object.

Please refer to the Equalizer Programming Guide and examples on how to develop and use distributed objects. The Serializable implements a typical common use case based on the basic Object.

Definition at line 45 of file object.h.

Member Enumeration Documentation

enum co::Object::ChangeType

Object change handling characteristics, see Programming Guide.

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

Definition at line 49 of file object.h.

Constructor & Destructor Documentation

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

virtual

Destruct the distributed object.

Version: 1.0

CO_API co::Object::Object ( )

protected

Construct a new distributed object.

Version: 1.0

CO_API co::Object::Object ( const Object & )

explicitprotected

Copy construct a new, unattached object.

Version: 1.0

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.

Version: 1.0

Implemented in co::Barrier, co::Serializable, and co::QueueSlave.

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 lossless compression ratio 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.

Version: 1.0

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 continuously, 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 committed, but have certain caveats for serialization. Please refer to the Equalizer Programming Guide for 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 slave 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 a corresponding 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 (master) or commit id (slave).

Version: 1.0

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

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

Returns: get the number of retained incarnations.

Version: 1.0

virtual ChangeType co::Object::getChangeType ( ) const

inlinevirtual

Returns: how the changes are to be handled.

Version: 1.0

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

Definition at line 103 of file object.h.

References STATIC.

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

Returns: the latest available (head) version.

Version: 1.0

CO_API const uint128_t& co::Object::getID ( ) const

Returns: the object's unique identifier.

Version: 1.0

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.

Version: 1.0

Implemented in co::Barrier, co::Serializable, and co::QueueSlave.

Referenced by pack().

Here is the caller graph for this function:

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

Returns: the node-wide unique object instance identifier.

Version: 1.0

CO_API LocalNodePtr co::Object::getLocalNode ( )

Returns: the local node to which this object is attached.

Version: 1.0

virtual uint64_t co::Object::getMaxVersions ( ) const

inlinevirtual

Limit the number of queued versions on 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.0

Definition at line 123 of file object.h.

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

Returns: the currently synchronized version.

Version: 1.0

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

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

Version: 1.0

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

Here is the caller graph for this function:

virtual bool co::Object::isDirty ( ) const

inlinevirtual

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.

Version: 1.0

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

Definition at line 149 of file object.h.

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

Returns: true if this instance is a registered master version.

Version: 1.0

virtual void co::Object::notifyAttach ( )

inlinevirtual

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.

Version: 1.0

Definition at line 352 of file object.h.

virtual void co::Object::notifyAttached ( )

inlinevirtual

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()

Version: 1.0

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

Definition at line 362 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()

Version: 1.0

virtual void co::Object::notifyDetached ( )

inlinevirtual

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.

Version: 1.0

Definition at line 381 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 called from the receiver thread, which is different from the node main thread. The object cannot be sync()'ed from this notification, as this might lead to deadlocks and synchronization issues with the application thread changing the object. It should signal the application, which then takes the appropriate action. Do not perform any potentially blocking operations from this method.

Parameters

version The new head version.

Version: 1.0

virtual void co::Object::notifyNewVersion ( )

inlinevirtual

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

The same constraints as for notifyNewHeadVersion() apply.

Version: 1.0

Definition at line 280 of file object.h.

Object& co::Object::operator= ( const Object & )

inlineprotected

NOP assignment operator.

Version: 1.0

Definition at line 434 of file object.h.

Referenced by co::Serializable::operator=().

Here is the caller graph for this function:

virtual void co::Object::pack ( DataOStream & os )

inlinevirtual

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.

Version: 1.0

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

Definition at line 313 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. LocalNode::objectPush() is called once for each node in the nodes list.

Buffered objects do not reserialize 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.

Version: 1.0

CO_API ObjectOCommand co::Object::send	(	NodePtr	node,
		const uint32_t	cmd,
		const uint32_t	instanceID = `CO_INSTANCE_ALL`
	)

Send a command with optional data to object instance(s) on another node.

The returned command can be used to pass additional data. The data will be send after the command object is destroyed, aka when it is running out of scope.

Parameters

node	the node where to send the command to.
cmd	the object command to execute.
instanceID	the object instance(s) which should handle the command.

Returns: the command object to pass additional data to.

Version: 1.0

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

Automatically obsolete old versions.

The versions for the last count incarnations are retained for the buffered object types INSTANCE and DELTA.

Parameters

count the number of incarnations to retain.

Version: 1.0

CO_API void co::Object::setID ( const uint128_t & 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.0

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 all received versions, 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 past or future version generated by a commit on the master instance. Syncing to a concrete version applies all pending versions up to this version and potentially blocks if given a future version.

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).