6.16.1 Bus Example Scenario

Suppose you run a bus company. To automate part of your ridership tracking system, you want to write classes that represent a bus, its set of customers, and its set of actual passengers. In order to be a passenger, a person must be a customer. Hence, the set of customers is a superset of the set of passengers. Also, a person can physically be on the bus only once, and there is no point in putting the same person on the customer list more than once. As the developer of this system, you must make sure there are no duplicates on either list.

These duplicates can be a problem. Suppose that the program needs to be able to save and restore information about the bus and its customers. When it comes time to polymorphically save the bus, if your program naively iterates over the set of customers, then over the set of passengers, saving each one, any person who is both a customer and a passenger is saved twice. When the program polymorphically restores the bus, the list of passengers will not simply refer to people already on the customer list. Instead, each passenger has a separate instantiation on both lists.

You need some way of recognizing when a person has already been polymorphically saved to the stream and, instead of saving him or her again, merely saving a reference to the previous instance.

6.16.1.1 Serialization Support Macros

These macros use the following tokens as parameters:

The only limitation on the naming of Id and Str is that each must be unique since they are used to identify a particular serializable type.

When you are creating a library that defines serialization types, you must ensure that the serialization support symbols introduced by the expansion of the macros are properly exported. In addition, the symbols must be properly imported into the programs that are built on top of the library.

6.16.1.2 Exporting Symbols in a Windows Environment

In a Microsoft Windows environment, the dynamic libraries require a special inline syntax to declare a symbol as exported. The classic mechanism for exporting a specific symbol from a library and importing it into a program that uses that library is a conditionally defined macro which expands to the appropriate storage-class attributes. This macro will expand one way in the library and another way in the program. For example:

// library internal header // library.h #ifdef LIBRARY_SOURCE # define EXPORT __declspec(dllexport) #else # define EXPORT __declspec(dllimport) #endif // LIBRARY_SOURCE // library header, declaring exported type // A.h #include <library.h> struct EXPORT A { // ... }; // library source file // A.cpp #define LIBRARY_SOURCE #include <A.h> //... // program using the above library #include <A.h> int main () { A a; }

From this code example, you can see how the EXPORT macro is expanded in the library code different from the way it is expanded in the program code.

The Essential Tools Module serialization macros use a similar mechanism. To properly export the serialization symbols:

1. In one of the internal headers of the library, define a macro such as MODULE_FUNCTION which will expand to either dllexport or dllimport.

   // user library internal header // library.h #ifdef LIBRARY_SOURCE # define MODULE_FUNCTION __declspec(dllexport) # define EXPORT __declspec(dllexport) #else # define MODULE_FUNCTION __declspec(dllimport) # define EXPORT __declspec(dllimport) #endif // LIBRARY_SOURCE

2. The prefix of the MODULE_FUNCTION macro is then used consistently across the library as the first parameter of the serialization macros.

   // user library header // A.h class EXPORT A : public RWCollectable { // use serialization macros; pass as first parameter the // prefix of the MODULE_FUNCTION macro above, // i.e. "MODULE" RW_DECLARE_COLLECTABLE_CLASS(MODULE, A) // ... }; // user library source files // A.cpp #define LIBRARY_SOURCE #include <A.h> // use serialization macros; first parameter same as above; // use the name "MODULE" consistently across your whole // library

For example, in a user application called "BusSchedule" you might choose a prefix such as BUS_SCHEDULE and compose the support macro as:

// ... #define BUS_SCHEDULE_FUNCTION // ...

For a static library on a Windows platform, a static or dynamic library on any other platform, or for your application, simply define MODULE_FUNCTION with no body such as:

// user header // my_header.h #define MODULE_FUNCTION // program source #include <my_header.h> class A : public RWCollectable { RW_DECLARE_CLASS_COLLECTABLE(MODULE, A) // ... };

For more information, refer to rw/rwwind.h.

6.16.2 The Role of RWCollectable

6.16.3 Bus Example Code

The code below shows how we might declare the classes described in the previous section. Later we will use the macro RW_DECLARE_COLLECTABLE_CLASS and discuss our function choices. You will find the complete code from which this example is taken at the end of this chapter; it is also given as the bus example in the buildspace\examples\tools directory.

class Bus : public RWCollectable { RW_DECLARE_COLLECTABLE_CLASS(USER_MODULE, Bus) public: Bus(); Bus(int busno, const RWCString& driver); ~Bus(); // Inherited from class "RWCollectable": Rwspace binaryStoreSize() const; int compareTo(const RWCollectable*) const; bool isEqual(const RWCollectable*) const; unsigned hash() const; void restoreGuts(RWFile&); void restoreGuts(RWvistream&); void saveGuts(RWFile&) const; void saveGuts(RWvostream&) const; void addPassenger(const char* name); void addCustomer(const char* name); size_t customers() const; size_t passengers() const; RWCString driver() const {return driver_;} int number() const {return busNumber_;} private: RWSet customers_; RWSet* passengers_; int busNumber_; RWCString driver_; }; class Client : public RWCollectable { RW_DECLARE_COLLECTABLE_CLASS(USER_MODULE, Client) Client(const char* name) : name_(name) {} private: RWCString name_; // ignore other client information for this example };