Collage  0.6.1
Public Member Functions | Public Types | Protected Member Functions | Friends
co::Object Class Reference

A generic, distributed object. More...

#include <object.h>

+ Inheritance diagram for co::Object:
+ Collaboration diagram for co::Object:

List of all members.

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 Objectoperator= (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

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:
isthe 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:
incarnationthe 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:
osThe 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.

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:
versionThe 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:
osthe 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:
groupIDAn identifier to group a set of push operations.
objectTypeA per-push identifier.
nodesThe 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:
countthe 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:
versionthe version to synchronize (see above).
Returns:
the last version applied.
virtual void co::Object::unpack ( DataIStream is) [inline, virtual]

Deserialize a change.

Parameters:
isthe input data stream.

Reimplemented in co::Barrier.

Definition at line 310 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:
Generated on Mon Nov 26 2012 14:41:44 for Collage 0.6.1 by  doxygen 1.7.6.1