Collage  1.5.0
High-performance C++ library for developing object-oriented distributed applications.
co::ObjectMap Class Reference

A distributed object registry. More...

#include <objectMap.h>

+ Inheritance diagram for co::ObjectMap:
+ Collaboration diagram for co::ObjectMap:

Public Member Functions

CO_API ObjectMap (ObjectHandler &handler, ObjectFactory &factory)
 Construct a new object map. More...
 
virtual CO_API ~ObjectMap ()
 Destroy this object map. More...
 
CO_API bool register_ (Object *object, const uint32_t type)
 Add and register a new object as master instance to this object map. More...
 
CO_API bool deregister (Object *object)
 Remove and deregister an object from this object map. More...
 
CO_API Objectmap (const uint128_t &identifier, Object *instance=0)
 Map and return an object. More...
 
CO_API bool unmap (Object *object)
 Unmap an object from the object map. More...
 
CO_API void clear ()
 Deregister or unmap all registered and mapped objects. More...
 
CO_API uint128_t commit (const uint32_t incarnation=CO_COMMIT_NEXT) override
 Commit all registered objects. More...
 
- Public Member Functions inherited from co::Serializable
CO_API uint64_t getDirty () const
 
CO_API bool isDirty () const override
 
virtual CO_API bool isDirty (const uint64_t dirtyBits) const
 
CO_API uint128_t commit (const uint32_t incarnation=CO_COMMIT_NEXT) override
 
- Public Member Functions inherited from co::Object
virtual CO_API ~Object ()
 Destruct the distributed object. More...
 
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
 
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...
 
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...
 
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...
 
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...
 
virtual void notifyAttach ()
 Notify that this object will be 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 (const 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 Types

enum  DirtyBits { DIRTY_ADDED = Serializable::DIRTY_CUSTOM << 0, DIRTY_REMOVED = Serializable::DIRTY_CUSTOM << 1, DIRTY_CHANGED = Serializable::DIRTY_CUSTOM << 2, DIRTY_CUSTOM = Serializable::DIRTY_CUSTOM << 3 }
 
- Protected Types inherited from co::Serializable
enum  DirtyBits { DIRTY_NONE = 0, DIRTY_CUSTOM = 1, DIRTY_ALL = 0xFFFFFFFFFFFFFFFFull }
 The changed parts of the serializable since the last pack(). More...
 

Protected Member Functions

CO_API bool isDirty () const override
 Return if this object needs a commit. More...
 
CO_API void serialize (DataOStream &os, const uint64_t dirtyBits) override
 Worker for pack() and getInstanceData(). More...
 
CO_API void deserialize (DataIStream &is, const uint64_t dirtyBits) override
 Worker for unpack() and applyInstanceData(). More...
 
ChangeType getChangeType () const override
 
CO_API void notifyAttached () override
 Notify that this object has been registered or mapped. More...
 
- Protected Member Functions inherited from co::Serializable
CO_API Serializable ()
 Construct a new Serializable. More...
 
CO_API Serializable (const Serializable &)
 Construct an unmapped, unregistered copy of a serializable. More...
 
virtual CO_API ~Serializable ()
 Destruct the serializable. More...
 
Serializableoperator= (const Serializable &from)
 NOP assignment operator. More...
 
virtual CO_API void setDirty (const uint64_t bits)
 Add dirty flags to mark data for distribution. More...
 
virtual CO_API void unsetDirty (const uint64_t bits)
 Remove dirty flags to clear data from distribution. More...
 
ChangeType getChangeType () const override
 
CO_API void notifyAttached () override
 
void getInstanceData (co::DataOStream &os) override
 Serialize all instance information of this distributed object. More...
 
CO_API void applyInstanceData (co::DataIStream &is) override
 Deserialize the instance data. More...
 
CO_API void pack (co::DataOStream &os) final
 Serialize the modifications since the last call to commit(). More...
 
CO_API void unpack (co::DataIStream &is) final
 Deserialize a change. More...
 
- Protected Member Functions inherited from co::Object
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...
 

Additional Inherited Members

- Public Types inherited from co::Object
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...
 

Detailed Description

A distributed object registry.

The object map takes care of distribution and synchronization of registered objects across all slave instances. Objects are registered with an additional type to resolve the creation of new objects during mapping. This creation is handled by an ObjectFactory which has to be provided and implemented for the desired object types.

Definition at line 39 of file objectMap.h.

Constructor & Destructor Documentation

CO_API co::ObjectMap::ObjectMap ( ObjectHandler handler,
ObjectFactory factory 
)

Construct a new object map.

Parameters
handlerused for object registration and mapping
factoryto create & destroy slave objects
Version
1.0
virtual CO_API co::ObjectMap::~ObjectMap ( )
virtual

Destroy this object map.

All registered and mapped objects will be deregistered and unmapped. All mapped and owned objects will be destroyed using the object factory.

Version
1.0

Member Function Documentation

CO_API void co::ObjectMap::clear ( )

Deregister or unmap all registered and mapped objects.

Version
1.0
CO_API uint128_t co::ObjectMap::commit ( const uint32_t  incarnation = CO_COMMIT_NEXT)
overridevirtual

Commit all registered objects.

Version
1.0

Reimplemented from co::Object.

CO_API bool co::ObjectMap::deregister ( Object object)

Remove and deregister an object from this object map.

Upon deregistering using the map's object handler, this object will be remembered for unmap and possible deletion on the next commit of this object map.

Parameters
objectthe object to remove and deregister
Returns
false on if object was not registered, true otherwise
Version
1.0
CO_API void co::ObjectMap::deserialize ( DataIStream ,
const uint64_t   
)
overrideprotectedvirtual

Worker for unpack() and applyInstanceData().

This function is called with the dirty bits send by the master instance. The dirty bits are received beforehand, and do not need to be deserialized by the overriding method.

See also
serialize()
Version
1.0

Reimplemented from co::Serializable.

ChangeType co::ObjectMap::getChangeType ( ) const
inlineoverrideprotectedvirtual
Returns
how the changes are to be handled.
Version
1.0

Reimplemented from co::Object.

Definition at line 135 of file objectMap.h.

References co::Object::DELTA.

CO_API bool co::ObjectMap::isDirty ( ) const
overrideprotectedvirtual

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 from co::Object.

CO_API Object* co::ObjectMap::map ( const uint128_t &  identifier,
Object instance = 0 
)

Map and return an object.

The object is either created via its type specified upon registering or an already created instance is used if passed to this function. Passed instances will not be considered for deletion during explicit unmap(), implicit unmap caused by deregister(), or destruction of this object map.

The object will be mapped to the version that was current on registration time.

Parameters
identifierunique object identifier used for map operation
instancealready created instance to skip factory creation
Returns
0 if not registered, the valid instance otherwise
Version
1.0
CO_API void co::ObjectMap::notifyAttached ( )
overrideprotectedvirtual

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 from co::Object.

CO_API bool co::ObjectMap::register_ ( Object object,
const uint32_t  type 
)

Add and register a new object as master instance to this object map.

Upon registering using the map's object handler, this object will be remembered for serialization on the next commit of this object map.

Parameters
objectthe new object to add and register
typeunique object type to create object via slave factory
Returns
false on failed ObjectHandler::registerObject, true otherwise
Version
1.0
CO_API void co::ObjectMap::serialize ( DataOStream ,
const uint64_t   
)
overrideprotectedvirtual

Worker for pack() and getInstanceData().

Override this and deserialize() to distribute subclassed data.

This method is called with DIRTY_ALL from getInstanceData() and with the actual dirty bits from pack(), which also resets the dirty state afterwards. The dirty bits are transmitted beforehand, and do not need to be transmitted by the overriding method.

Version
1.0

Reimplemented from co::Serializable.

CO_API bool co::ObjectMap::unmap ( Object object)

Unmap an object from the object map.

The object is unmapped using the map's object handler and will not be considered for further synchronization. The object will be destructed if if was created by the object map.

Parameters
objectthe object to unmap
Returns
false on if object was not mapped, true otherwise
Version
1.0

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