Rogue Wave banner
Previous fileTop of documentContentsIndexNext file

14.4 Isomorphic Persistence

Isomorphic persistence is the storage and retrieval of objects to and from a stream such that the pointer relationships between the objects are preserved. If there are no pointer relationships, isomorphic persistence effectively saves and restores objects the same way as simple persistence. When a collection is isomorphically persisted, all objects within that collection are assumed to have the same type. (A collection of objects of the same type is called a homogeneous collection.)

You can use isomorphic persistence to save and restore any Tools.h++ class listed in Table 2 above. In addition, you can add isomorphic persistence to a class by following the technique described in Section 14.4.3.

Note that in this implementation of Tools.h++, isomorphic persistence of types templatized on pointers is not supported. For example, saving and restoring RWTValDlist<int*> is not supported.[19] In this case, we suggest that you use RWTPtrDlist<int> instead.

Table 2. Isomorphic Persistence Classes

Category
Description
Rogue Wave Standard C++ Library-based collection classes
RWTValDeque, RWTPtrMap, ...
RWCollectable (Smalltalk-like) classes
RWCollectableDate, RWCollectableString... Note that RWCollectable classes also provide polymorphic persistence (see Section 1.5)
RWCollection classes that derive from RWCollectable
RWBinaryTree, RWBag, ...
Rogue Wave Tools.h++ 6.x templatized collections
RWTPtrDlist, RWTValDlist, RWTPtrSlist, RWTValSlist, RWTPtrOrderedVector, RWTValOrderedVector, RWTPtrSortedVector, RWTValSortedVector, RWTPtrVector, RWTValVector

14.4.1 Isomorphic versus Simple Persistence

Let's look at a couple of illustrations that show the difference between isomorphic and simple persistence. In Figure 2, a collection of multiple pointers to the same object is saved to and restored from a stream, using simple persistence. Notice that when the collection is stored and restored in Figure 2, each pointer points to a distinct object. Contrast this with the isomorphic persistence of the same collection, shown in Figure 3, in which all of the restored pointers point to the same object, just as they did in the original collection.

Figure 2. Saving and restoring with simple persistence.

image6.gif


image7.gif


Figure 3. Saving and Restoring a Collection with Isomorphic Persistence

image8.gif


image9.gif


In Figure 4, we attempt to save and restore a circularly-linked list, using simple persistence. As shown in the figure, any attempt to use simple persistence to save a circularly-linked list results in an infinite loop.

The simple persistence mechanism creates a copy of each object that is pointed to and saves that object to a stream. But the simple persistence mechanism doesn't remember which objects it has already saved. When the simple persistence mechanism encounters a pointer, it has no way of knowing whether it has already saved that pointer's object. So in a circularly-linked list, the simple persistence mechanism saves the same objects over and over and over as the mechanism cycles through the list forever.

On the other hand, as shown in Figure 5, isomorphic persistence allows us to save the circularly-linked list. The isomorphic persistence mechanism uses a table to keep track of pointers it has saved. When the isomorphic persistence mechanism encounters a pointer to an unsaved object, it copies the object data, saves that object data -- not the pointer -- to the stream, then keeps track of the pointer in the save table. If the isomorphic persistence mechanism later encounters a pointer to the same object, instead of copying and saving the object data, the mechanism saves the save table's reference to the pointer.

When the isomorphic persistence mechanism restores pointers to objects from the stream, the mechanism uses a restore table to reverse the process. When the isomorphic persistence mechanism encounters a pointer to an unrestored object, it recreates the object with data from the stream, then changes the restored pointer to point to the recreated object. The mechanism keeps track of the pointer in the restore table. If the isomorphic persistence mechanism later encounters a reference to an already-restored pointer, then the mechanism looks up the reference in the restore table, and updates the restored pointer to point to the object referred to in the table.

Figure 4. Attempt to Save and Restore a Circularly-linked List with Simple Persistence

image10.gif


image11.gif


Figure 5. Saving and Restoring a Circularly-linked List with Isomorphic Persistence

image12.gif


image13.gif


14.4.2 Isomorphic Persistence of a Tools.h++ Class

The following example shows the isomorphic persistence of a templatized collection of RWCollectable integers, RWTPtrDlist<RWCollectableInt>. RWTPtrDlist is a templatized, reference-based, doubly-linked list that uses isomorphic persistence to store pointer references to values in memory.

This example uses RWCollectableInt instead of int because ints use simple persistence. By using RWCollectableInts, we can implement isomorphic persistence.

When RWTPtrDlist is saved and then restored, the pointer relationships of the restored list will have the same morphology as the original list.

#include <assert.h>
#include <rw/tpdlist.h>  // RWTPtrDlist
#include <rw/collint.h>  // RWCollectableInt
#include <rw/rwfile.h>   // RWFile


main (){
  RWTPtrDlist<RWCollectableInt> dlist1;
  RWCollectableInt    *one = new RWCollectableInt(1);
  dlist1.insert(one);
  dlist1.insert(one);
  {
    RWFile            f("dlist.dat");
    f << dlist1;  // Isomorphic persistence of dlist1.
  }

  assert(dlist1[0] == one && dlist1[0] == dlist1[1]);
    // dlist1[0], dlist[1] and "one" all point to the
    // same place.

  RWTPtrDlist<RWCollectableInt> dlist2;
  {
    RWFile            f("dlist.dat");

    f >> dlist2; 
      // restore dlist2 from f
      // dlist2 now contains 2 pointers
      // to the same RWCollectableInt of value 1.
      // However, this RWCollectableInt isn't at 
      // the same address as the value 
      // that "one" points to.
  }

  // See Figure 6 below to see what dlist1 and dlist2
  // now look like in memory.

  assert(dlist2[0] == dlist2[1] && (*dlist2[0]) == *one);
    // dlist2[0] and dlist2[1] point to the same place
    // and that place has the same value as "one".
  delete dlist2[0];
  delete one;
    // The developer must allocate and delete objects.
    // The templatized collection member function
    // clearAndDestroy() doesn't check that a given
    // pointer is deleted only once.
    // So in this case, delete the shared
    // pointer manually.
 
  return 0;   
}

Figure 6. After Isomorphic Save and Restore of RWTPtrDlist<RWCollectableInt>

image14.gif

14.4.3 Designing Your Class to Use Isomorphic Persistence

Table 2 lists the Tools.h++ classes that implement isomorphic persistence. You can also add isomorphic persistence to an existing class, even if you only have the header files for that class. Before you can add isomorphic persistence to a class, it must meet the following requirements:

If your class T will be stored in a Standard C++ Library container or a Standard C++ Library-based collection, you may need to implement operator<(const T&, const T&) and operator==(const T&, const T&). See Section 11.11 for more information.

To create an isomorphically persistent class or to add isomorphic persistence to an existing class, follow these steps:

  1. Make all necessary class data available.

  2. Add RWDECLARE_PERSISTABLE to your header file.

  3. Add RWDEFINE_PERSISTABLE to one source file.

  4. Check for possible problems.

  5. Define rwSaveGuts and rwRestoreGuts.

14.4.3.1 Make All Necessary Class Data Available

All class data that will be isomorphically persisted must be accessible to the global functions, rwSaveGuts and rwRestoreGuts, used to implement persistence for the class.

Note that only the information necessary to recreate an object of that class must be accessible to rwSaveGuts and rwRestoreGuts. Other data can be kept protected or private.

There are several ways to make protected and private data members of classes accessible.

First, your class could make friends with rwSaveGuts and rwRestoreGuts:

class Friendly {
// These global functions access private members.
  friend void rwSaveGuts(RWvostream&, const Friendly&);
  friend void rwRestoreGuts(RWFile&, Friendly&);
  friend void rwSaveGuts(RWFile&, const Friendly&);
  friend void rwRestoreGuts(RWvistream&, Friendly&);
//...
};

Or your class could have accessor functions to the restricted but necessary members:

class Accessible {
public:
   int  secret(){return secret_}
   void secret(const int s){secret_ = s}
//...
private:
  int   secret_;
};

If you can't change the source code for the class to which you want to add isomorphic persistence, then you could consider deriving a new class that provides access via public methods or friendship:

class Unfriendly{
protected:
   int secret_;
// ...
};

class Friendlier : public Unfriendly {
public:
   int  secret(){return secret_}
   void secret(const int s){secret_ = s}
//...
};

If you can't change the source code for a class, you will be unable to isomorphically persist private members of that class. But remember: you only need access to the data necessary to recreate the class object, not to all the members of the class. For example, if your class has a private cache that is created at run time, you probably don't need to save and restore the cache. Thus, even though that cache is private, you don't need access to it in order to persist the class object.

14.4.3.2 Add RWDECLARE_PERSISTABLE to Your Header File

Once you have determined that all necessary class data is accessible, you must add declaration statements to your header files. These statements declare the global functions operator<< and operator>> for your class. The global functions permit storage to and retrieval from RWvistream, RWvostream and RWFile.

Tools.h++ provides several macros that make adding these declarations easy. The macro you choose depends upon whether your class is templatized or not, and if it is templatized, how many templatized parameters it has.

14.4.3.3 Add RWDEFINE_PERSISTABLE to One Source File

After you have declared the global storage and retrieval operators, you must define them. Tools.h++ provides macros that add code to your source file[20] to define the global functions operator<< and operator>> for storage to and retrieval from RWvistream, RWvostream, and RWFile. RWDEFINE_PERSISTABLE macros will automatically create global operator<< and operator>> functions that perform isomorphic persistence duties and call the global persistence functions rwSaveGuts and rwRestoreGuts for your class. More about rwSaveGuts and rwRestoreGuts later.

Again, your choice of which macro to use is determined by whether your class is templatized, and if so, how many parameters it requires.

14.4.3.4 Check for Possible Problems

You've made the necessary data accessible, and declared and defined the global functions required for isomorphic persistence. Before you go any further, you need to review your work for two possible problems.

  1. You can't use the RWDECLARE_PERSISTABLE_TEMPLATE and RWDEFINE_PERSISTABLE_TEMPLATE macros to persist any templatized class that has non-type template parameters. Templates with non-type template parameters, such as RWTBitVec<size>, cannot be isomorphically persisted.

  2. If you have defined any of the following global operators and you use the RWDEFINE_PERSISTABLE macro, you will get compiler ambiguity errors.

    RWvostream& operator<<(RWvostream& s, const YourClass& t);
    RWvistream& operator>>(RWvistream& s, YourClass& t);
    RWvistream& operator>>(RWvistream& s, YourClass*& pT);
    
    RWFile& operator<<(RWFile& s, const YourClass& t);
    RWFile& operator>>(RWFile& s, YourClass& t);
    RWFile& operator>>(RWFile& s, YourClass*& pT);
    

    The compiler errors occur because using RWDEFINE_PERSISTABLE along with a different definition of the operators defines the operators twice. This means that the compiler does not know which operator definition to use. In this case, you have two choices:

14.4.3.5 Define rwSaveGuts and rwRestoreGuts

Now you must add to one and only one source file the global functions rwSaveGuts and rwRestoreGuts, which will be used to save and restore the internal state of your class. These functions are called by the operator<< and operator>> that were declared and defined as discussed in Sections 14.4.3.2 and 14.4.3.3 above.

Note: Section 14.4.4 provides guidelines about how to write rwSaveGuts and rwRestoreGuts global functions.

Function rwSaveGuts saves the state of each class member necessary for persistence to an RWvostream or an RWFile. If the members of your class can be persisted (see Table 2 above), and if the necessary class members are accessible to rwSaveGuts, you can use operator<< to save the class members.

Function rwRestoreGuts restores the state of each class member necessary for persistence from an RWvistream or an RWFile. Provided that the members of your class are types that can be persisted, and provided that the members of your class are accessible to rwRestoreGuts, you can use operator>> to restore the class members.

14.4.4 Writing rwSaveGuts and rwRestoreGuts Functions

The next two sections discuss guidelines for writing rwSaveGuts and rwRestoreGuts global functions. To illustrate these guidelines, the following class will be used:

class Gut {
  public:
    int                   fundamentalType_;
    RWCString             aRogueWaveObject_;
    RWTValDlist           anotherRogueWaveObject_;
    RWCollectableString   anRWCollectable_
    RWCollectableString*  pointerToAnRWCollectable_;
    Gut*                  pointerToAnObject_;
};

The discussion in the next two sections describes how to write rwSaveGuts and rwRestoreGuts functions for non-templatized classes. However, the descriptions also apply to the templatized rwSaveGuts and rwRestoreGuts that are written for templatized classes.

14.4.4.1 Guidelines for Writing rwSaveGuts

The global overloaded functions:

rwSaveGuts(RWFile& f, const YourClass& t) 
rwSaveGuts (RWvostream& s, const YourClass& t) 

are responsible for saving the internal state of a YourClass object to either a binary file (using class RWFile) or to a virtual output stream (an RWvostream). This allows the object to be restored at some later time.

The rwSaveGuts functions that you write must save the state of each member in YourClass, including the members of the class that you inherited from.

How you write the functions depends upon the type of the member data:

Using these guidelines, you can write rwSaveGuts functions for the example class Gut as follows:

void rwSaveGuts(RWvostream& stream, const Gut& gut) {

  // Use insertion operators to save fundamental objects,
  // Rogue Wave objects and pointers to 
  // RWCollectable-derived objects.

  stream 
    << gut.fundamentalType_
    << gut.aRogueWaveObject_
    << gut.anotherRogueWaveObject_
    << gut.pointerToAnRWCollectable_;
  
  // The tricky saving of a pointer 
  // to a non-RWCollectable object.

  if (gut.pointerToAnObject_ == 0)  // Is it a nil pointer? 
    stream << false;                    // Yes, don't save.
  else {
    stream << true;                       // No, it's valid 
    stream << gut.pointerToAnObject_;  // so save it.
  }
}

void rwSaveGuts(RWFile& stream, const Gut& gut) {
  // The body of this function is identical to
  // rwSaveGuts(RWvostream& stream, const Gut& gut).
}

14.4.4.2 Guidelines for Writing rwRestoreGuts

The global overloaded functions:

rwRestoreGuts(RWFile& f, YourClass& t) 
rwRestoreGuts(RWvistream& s, YourClass& t) 

are responsible for restoring the internal state of a YourClass object from either a binary file (using class RWFile) or from a virtual input stream (an RWvistream).

The rwRestoreGuts functions that you write must restore the state of each member in YourClass, including the members of the class that you inherited from. The functions must restore member data in the order that it was saved.

How you write the functions depends upon the type of the member data:

Using these guidelines, you can write the rwRestoreGuts functions for the example class Gut as follows:

void rwRestoreGuts(RWvistream& stream, const Gut& gut) {

  // Use extraction operators to restore fundamental objects,
  // Rogue Wave objects and pointers to 
  // RWCollectable-derived objects.

  stream 
    >> gut.fundamentalType_
    >> gut.aRogueWaveObject_
    >> gut.anotherRogueWaveObject_
    >> gut.pointerToAnRWCollectable_;
  
  // The tricky restoring of a pointer 
  // to a non-RWCollectable object.

  bool isValid;
  stream >> isValid;                   // Is it a nil pointer?

  if (isValid)                         // No,
    stream >> gut.pointerToAnObject_;  // restore the pointer.
  else                                 // Yes,
    gut.pointerToAnObject_ = rwnil;    // set pointer to nil.
}

void rwRestoreGuts(RWFile& stream, Gut& gut) {
  // The body of this function is identical to
  // rwRestoreGuts(RWvostream& stream, Gut& gut).
}

14.4.5 Isomorphic Persistence of a User-designed Class

Section 14.3.1.2 described some example code that implements simple persistence on a collection that includes pointers. That example illustrated how simple persistence does not maintain the original collection's morphology.

This example implements isomorphic persistence on the collection we set up in Section 14.3.1.2: Team, which contains three Developers. Figure 7 shows the morphology of the original Team collection and of the Team collection after we saved and restored it with isomorphic persistence.

Figure 7. Isomorphic Persistence

image15.gif


Collection to be saved (team1).

image16.gif


Collection restored (team2).

As you read the code, notice how the Developer::alias_ member, which points to other Developers, is saved and restored. You'll find that after saving Developer::name_ , the rwSaveGuts function for Developer checks to see if alias_ is pointing to a Developer in memory. If not, rwSaveGuts stores a Boolean false to signify that alias_ is a nil pointer. If alias_ is pointing to a Developer, rwSaveGuts stores a Boolean true. It is only afterwards that rwSaveGuts finally stores the value of the Developer that alias_ is pointing to.

This code can distinguish between new Developers and existing

Developers because the insertion operators generated by RWDEFINE_PERSISTABLE(Developer) keep track of Developers that have been stored previously. The insertion operator, operator<<, calls the rwSaveGuts if and only if a Developer has not yet been stored in the stream by operator<<.

When a Developer object is restored, the extraction operator, operator>>, for Developer is called. Like the insertion operators, the extraction operators are generated by RWDEFINE_PERSISTABLE(Developer). If a Developer object has already been restored, then the extraction operator will adjust the Developer::alias_ pointer so that it points to the already existing Developer. If the Developer has not yet been restored, then rwRestoreGuts for Developer will be called.

After restoring Developer::name_ , rwRestoreGuts for Developer restores a Boolean value to determine whether Developer::alias_ should point to a Developer in memory or not. If the Boolean is true, then alias_ should point to a Developer, so rwRestoreGuts restores the Developer object. Then rwRestoreGuts updates alias_ to point to the restored Developer.

The isomorphic persistence storage and retrieval process described above for Developer.alias_ can also be applied to the Developer pointers in Team.

Here is the code:

#include <iostream.h>   // For user output.
#include <assert.h>
#include <rw/cstring.h>
#include <rw/rwfile.h>
#include <rw/epersist.h>

//------------------ Declarations ---------------------

//------------------- Developer -----------------------

class Developer {
  public:
    Developer
      (const char* name = "", Developer* anAlias = rwnil)
      : name_(name), alias_(anAlias) {}

  RWCString         name_;
  Developer*        alias_;
};

#include <rw/edefs.h>
RWDECLARE_PERSISTABLE(Developer)

//--------------------- Team --------------------------

class Team {
  public:
    Developer*  member_[3];
};

RWDECLARE_PERSISTABLE(Team);

//---------- rwSaveGuts and rwRestoreGuts -------------

//------------------- Developer -----------------------

RWDEFINE_PERSISTABLE(Developer)
// This macro generates the following insertion and extraction
// operators:
//   RWvostream& operator<<
//     (RWvostream& strm, const Developer& item)
//   RWvistream& operator>>(RWvistream& strm, Developer& obj)
//   RWvistream& operator>>(RWvistream& strm, Developer*& pObj)
//   RWFile& operator<<(RWFile& strm, const Developer& item)
//   RWFile& operator>>(RWFile& strm, Developer& obj)
//   RWFile& operator>>(RWFile& strm, Developer*& pObj)

void rwSaveGuts(RWFile& file, const Developer& developer){
// Called by:
//    RWFile& operator<<(RWFile& strm, const Developer& item)

  file << developer.name_;        // Save name.

  // See if alias_ is pointing to a Developer in memory.  
  // If not, then rwSaveGuts stores a boolean false to signify
  // that alias_ is a nil pointer. 
  // If alias_ is pointing to a Developer, 
  // then rwSaveGuts stores a boolean true 
  // and stores the value of the Developer 
  // that alias_ is pointing to.  

  if (developer.alias_ == rwnil) 
    file << false;                // No alias.
  else {
    file << true;
    file << *(developer.alias_);  // Save alias.
  }
}


void rwSaveGuts(RWvostream& stream, const Developer& developer) {
// Called by:
//    RWvostream& operator<<
//      (RWvostream& strm, const Developer& item)

  stream << developer.name_;        // Save name.

  // See if alias_ is pointing to a Developer in memory.  

  if (developer.alias_ == rwnil)
    stream << false;                // No alias.
  else {
    stream << true;
    stream << *(developer.alias_);  // Save alias.
  }
}

void rwRestoreGuts(RWFile& file, Developer& developer) {
//  Called by:
//    RWFile& operator>>(RWFile& strm, Developer& obj)

  file >> developer.name_;        // Restore name.

  // Should developer.alias_ point to a Developer?

  RWBoolean alias;
  file >> alias;

  // If alias_ should point to a Developer, 
  // then rwRestoreGuts restores the Developer object 
  // and then updates alias_ to point to the new Developer.

  if (alias)                     // Yes.
     file >> developer.alias_;
        // Call:
        //   RWFile& operator>>(RWFile& strm, Developer*& pObj)
}

void rwRestoreGuts(RWvistream& stream, Developer& developer) {
// Called by:
//   RWvistream& operator>>(RWvistream& strm, Developer& obj)

  stream >> developer.name_;     // Restore name.

  // Should developer.alias_ point to a Developer?

  RWBoolean alias;
  stream >> alias;

  if (alias)                    // Yes.
    stream >> developer.alias_;  
       // Restore alias and update pointer. 
       // Calls:
       //    RWvistream& operator>>
       //      (RWvistream& strm, Developer*& pObj)

}

// For user output only:

ostream& operator<<(ostream& stream, const Developer& d) {
  stream << d.name_
    << " at memory address: " << (void*)&d;

  if (d.alias_)
    stream << " has an alias at memory address: " 
      << (void*)d.alias_ << " ";
  else
    stream << " has no alias.";

  return stream;
}


//--------------------- Team -------------------------------

RWDEFINE_PERSISTABLE(Team);
// This macro generates the following insertion and extraction
// operators:
//    RWvostream& operator<<
//      (RWvostream& strm, const Team& item)
//    RWvistream& operator>>(RWvistream& strm, Team& obj)
//    RWvistream& operator>>(RWvistream& strm, Team*& pObj)
//    RWFile& operator<<(RWFile& strm, const Team& item)
//    RWFile& operator>>(RWFile& strm, Team& obj)
//    RWFile& operator>>(RWFile& strm, Team*& pObj)


void rwSaveGuts(RWFile& file, const Team& team){
// Called by RWFile& operator<<(RWFile& strm, const Team& item)

  for (int i = 0; i < 3; i++)
    file << *(team.member_[i]);    
      // Save Developer value.
      // Call:
      //   RWFile& operator<<
      //     (RWFile& strm, const Developer& item)
}

void rwSaveGuts(RWvostream& stream, const Team& team) {
// Called by:
//    RWvostream& operator<<(RWvostream& strm, const Team& item)

  for (int i = 0; i < 3; i++)
    stream << *(team.member_[i]);
      // Save Developer value.
      // Call:
      //   RWvostream& operator<<
      //     (RWvostream& strm, const Developer& item)

}

void rwRestoreGuts(RWFile& file, Team& team) {
// Called by RWFile& operator>>(RWFile& strm, Team& obj)

  for (int i = 0; i < 3; i++)
    file >> team.member_[i];   
      // Restore Developer and update pointer.
      // Call:
      //    RWFile& operator>>(RWFile& strm, Developer*& pObj)
}

void rwRestoreGuts(RWvistream& stream, Team& team) {
// Called by:
//    RWvistream& operator>>(RWvistream& strm, Team& obj)

  for (int i = 0; i < 3; i++)
    stream >> team.member_[i]; 
       // Restore Developer and update pointer.
       // Call:
       //    RWvistream& operator>>
       //      (RWvistream& strm, Developer*& pObj)
}

// For user output only:

ostream& operator<<(ostream& stream, const Team& t) {
  for (int i = 0; i < 3; i++)
    stream << "[" << i << "]:" << *(t.member_[i]) << endl;
  return stream;
}


//-------------------- main --------------------------

main (){
  Developer*  kevin   = new Developer("Kevin");
  Developer*  rudi    = new Developer("Rudi", kevin);
  Team        team1;

  team1.member_[0] = rudi;
  team1.member_[1] = rudi;
  team1.member_[2] = kevin;

  cout << "team1 (before save):" << endl
    << team1 << endl << endl;   // Output to user.
  {
    RWFile    f("team.dat");
    f << team1;  // Isomorphic persistence of team.
  }

  Team        team2;
  {
    RWFile            f("team.dat");
    f >> team2;
  }
  cout << "team2 (after restore):" << endl
    << team2 << endl << endl;   // Output to user.
  
  delete kevin;
  delete rudi;
  return 0;
}

Output:

team1 (before save):
[0]:Rudi at memory address: 0x10002be0 
    has an alias at memory address: 0x10002bd0
[1]:Rudi at memory address: 0x10002be0 
    has an alias at memory address: 0x10002bd0
[2]:Kevin at memory address: 0x10002bd0 has no alias.


team2 (after restore):
[0]:Rudi at memory address: 0x10002c00 
    has an alias at memory address: 0x10002c10
[1]:Rudi at memory address: 0x10002c00 
    has an alias at memory address: 0x10002c10
[2]:Kevin at memory address: 0x10002c10 has no alias.

Previous fileTop of documentContentsIndexNext file
©Copyright 1999, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.