Line data Source code
1 :
2 : /* Copyright (c) 2012-2013, Daniel Nachbaur <danielnachbaur@googlemail.com>
3 : * 2012-2014, Stefan Eilemann <eile@eyescale.ch>
4 : *
5 : * This file is part of Collage <https://github.com/Eyescale/Collage>
6 : *
7 : * This library is free software; you can redistribute it and/or modify it under
8 : * the terms of the GNU Lesser General Public License version 2.1 as published
9 : * by the Free Software Foundation.
10 : *
11 : * This library is distributed in the hope that it will be useful, but WITHOUT
12 : * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13 : * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
14 : * details.
15 : *
16 : * You should have received a copy of the GNU Lesser General Public License
17 : * along with this library; if not, write to the Free Software Foundation, Inc.,
18 : * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 : */
20 :
21 : #ifndef CO_OBJECTMAP_H
22 : #define CO_OBJECTMAP_H
23 :
24 : #include <co/serializable.h> // base class
25 :
26 : namespace co
27 : {
28 : namespace detail
29 : {
30 : class ObjectMap;
31 : }
32 :
33 : /**
34 : * A distributed object registry.
35 : *
36 : * The object map takes care of distribution and synchronization of registered
37 : * objects across all slave instances. Objects are registered with an
38 : * additional type to resolve the creation of new objects during mapping.
39 : * This creation is handled by an ObjectFactory which has to be provided and
40 : * implemented for the desired object types.
41 : */
42 : class ObjectMap : public Serializable
43 : {
44 : public:
45 : /**
46 : * Construct a new object map.
47 : *
48 : * @param handler used for object registration and mapping
49 : * @param factory to create & destroy slave objects
50 : * @version 1.0
51 : */
52 : CO_API ObjectMap(ObjectHandler& handler, ObjectFactory& factory);
53 :
54 : /**
55 : * Destroy this object map.
56 : *
57 : * All registered and mapped objects will be deregistered and unmapped.
58 : * All mapped and owned objects will be destroyed using the object factory.
59 : * @version 1.0
60 : */
61 : CO_API virtual ~ObjectMap();
62 :
63 : /**
64 : * Add and register a new object as master instance to this object map.
65 : *
66 : * Upon registering using the map's object handler, this object will be
67 : * remembered for serialization on the next commit of this object map.
68 : *
69 : * @param object the new object to add and register
70 : * @param type unique object type to create object via slave factory
71 : * @return false on failed ObjectHandler::registerObject, true otherwise
72 : * @version 1.0
73 : */
74 : CO_API bool register_(Object* object, const uint32_t type);
75 :
76 : /**
77 : * Remove and deregister an object from this object map.
78 : *
79 : * Upon deregistering using the map's object handler, this object will be
80 : * remembered for unmap and possible deletion on the next commit of this
81 : * object map.
82 : *
83 : * @param object the object to remove and deregister
84 : * @return false on if object was not registered, true otherwise
85 : * @version 1.0
86 : */
87 : CO_API bool deregister(Object* object);
88 :
89 : /**
90 : * Map and return an object.
91 : *
92 : * The object is either created via its type specified upon registering or
93 : * an already created instance is used if passed to this function. Passed
94 : * instances will not be considered for deletion during explicit unmap(),
95 : * implicit unmap caused by deregister(), or destruction of this object map.
96 : *
97 : * The object will be mapped to the version that was current on registration
98 : * time.
99 : *
100 : * @param identifier unique object identifier used for map operation
101 : * @param instance already created instance to skip factory creation
102 : * @return 0 if not registered, the valid instance otherwise
103 : * @version 1.0
104 : */
105 : CO_API Object* map(const uint128_t& identifier, Object* instance = 0);
106 :
107 : /**
108 : * Unmap an object from the object map.
109 : *
110 : * The object is unmapped using the map's object handler and will not be
111 : * considered for further synchronization. The object will be destructed if
112 : * if was created by the object map.
113 : *
114 : * @param object the object to unmap
115 : * @return false on if object was not mapped, true otherwise
116 : * @version 1.0
117 : */
118 : CO_API bool unmap(Object* object);
119 :
120 : /** Deregister or unmap all registered and mapped objects. @version 1.0 */
121 : CO_API void clear();
122 :
123 : /** Commit all registered objects. @version 1.0 */
124 : CO_API uint128_t
125 : commit(const uint32_t incarnation = CO_COMMIT_NEXT) override;
126 :
127 : protected:
128 : CO_API bool isDirty() const override; //!< @internal
129 :
130 : /** @internal */
131 : CO_API void serialize(DataOStream& os, const uint64_t dirtyBits) override;
132 :
133 : /** @internal */
134 : CO_API void deserialize(DataIStream& is, const uint64_t dirtyBits) override;
135 : /** @internal */
136 2 : ChangeType getChangeType() const override { return DELTA; }
137 : CO_API void notifyAttached() override; //!< @internal
138 :
139 : /** @internal The changed parts of the object since the last serialize(). */
140 : enum DirtyBits
141 : {
142 : DIRTY_ADDED = Serializable::DIRTY_CUSTOM << 0, // 1
143 : DIRTY_REMOVED = Serializable::DIRTY_CUSTOM << 1, // 2
144 : DIRTY_CHANGED = Serializable::DIRTY_CUSTOM << 2, // 4
145 : DIRTY_CUSTOM = Serializable::DIRTY_CUSTOM << 3 // 8
146 : };
147 :
148 : private:
149 : detail::ObjectMap* const _impl;
150 :
151 : /** @internal Commit and note new master versions. */
152 : void _commitMasters(const uint32_t incarnation);
153 : };
154 : }
155 : #endif // CO_OBJECTMAP_H
|
