|
CXXR (C++ R) API
|
Serialization/deserialization of pointers to GCNode objects. More...
#include <GCNode_PtrS11n.hpp>
Static Public Member Functions | |
| template<class Archive , typename Ptr > | |
| static void | invoke (Archive &ar, Ptr &ptr, const char *name) |
| Serialize/deserialize a pointer to a GCNode object. | |
Friends | |
| class | GCNode |
Serialization/deserialization of pointers to GCNode objects.
This class, all of whose members are static, provides the mechanism by which pointers to objects inheriting from GCNode should be serialized and deserialized.
boost::serialization includes mechanisms for ensuring that if, before serialization, several pointers to be serialized point to the same object of a class type, then after deserialization, the deserialized pointers will also all point to a single object. During deserialization, boost::serialization creates this object using the appropriate operator new when the first pointer of the group is deserialized; subsequent pointers of the group are then simply set to point to that object.
However, in the CXXR application of boost::serialization, there is a complication in that by the time the previous user session is deserialized, the interpreter will already have partially established the GCNode-GCEdge graph. It will, for example, already have set up the base environment, and defined many Symbol and BuiltInFunction objects. It is necessary that the GCNode graph read from an archive is integrated correctly with this pre-existing graph. It is important, for example, that pointers that pointed to the NA string in the previous session are deserialized to point to the NA string already established in the new session prior to deserialization (whereas, left to itself, boost::serialization would be apt to make them point to a duplicate of that string read from the archive).
The way CXXR handles this is that whenever a non-null pointer to an object of a class inheriting from GCNode is deserialized, class GCNode::PtrS11n (specifically the templated function GCNode::PtrS11n::invoke()) will call the function S11nScope::relocate() on the pointer value. This function will use a look-up table within the innermost S11nScope. If this function returns a null pointer, then this signifies that no special handling is required, and the pointer being deserialized is left unchanged from the value given to it by boost deserialization.
However, if S11nScope::relocate() returns a non-null pointer p, this signifies that the pointer value yielded by boost deserialization needs to be replaced by p. For example suppose that in the previous session a particular pointer pointed to the NA string. When that pointer is deserialized, boost::deserialization will create a String object s which is merely a proxy for the NA string; however, invoking S11nScope::relocate() on the address of that object will return a pointer to the new session's NA string. GCNode::PtrS11n::invoke() will make the pointer being deserialized point to that.
Whenever one of these 'proxy' objects is deserialized, the deserialization logic should create an appropriate entry in the look-up table used by S11nScope::relocate() by calling S11nScope::defineRelocation(). Once that is done, there is no need to retain the proxy object, and S11nScope::defineRelocation() will automatically expose it to garbage collection.
Note that proxy objects may be malformed, i.e. violate the invariants of their class: no use should be made of them.
|
inlinestatic |
Serialize/deserialize a pointer to a GCNode object.
See class description for details.
| Archive | an archive class compatible with boost::serialization. Serialization or deserialization will be performed according to whether this is an output or an input archive. |
| Ptr | either a pointer type (possibly const) to GCNode or a class inheriting from GCNode, or a smart pointer encapsulating such a pointer. |
If Ptr is a smart pointer, then it is required that Ptr::type* define the type of the encapsulated pointer, and that class Ptr allow assignment to an from Ptr::type*.
| ar | The archive to be read/written. |
| ptr | Reference to the pointer to be serialized/deserialized. |
| name | The name (e.g. XML tag) to be attached to this pointer within the archive. |
1.8.1