Collage  1.3.0
High-performance C++ library for developing object-oriented distributed applications.
co::Object Class Referenceabstract

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< DispatcherFunc
 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
Dispatcheroperator= (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...
 
Objectoperator= (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

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
isthe 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
incarnationthe 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
osThe 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
versionThe 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
osthe 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
groupIDAn identifier to group a set of push operations.
objectTypeA per-push identifier.
nodesThe 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
nodethe node where to send the command to.
cmdthe object command to execute.
instanceIDthe 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
countthe 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
versionthe version to synchronize (see above).
Returns
the last version applied.
Version
1.0
virtual void co::Object::unpack ( DataIStream is)
inlinevirtual

Deserialize a change.

Parameters
isthe input data stream.
Version
1.0

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

Definition at line 321 of file object.h.

References applyInstanceData().

+ Here is the call graph for this function:


The documentation for this class was generated from the following file: