5.1 Class Wormhole

A wormhole for a domain is much like a star belonging to that domain, but it contains pointers to a subsystem that operates in a different domain. The interface to that other domain is through a "universal event horizon". The wormhole design, therefore, does not depend on the domain it contains, but only on the domain in which it is used as a block. It must look like a star in that outer domain. The base Wormhole class is derived from class Runnable , just like the class Universe . Every member of the Runnable class has a pointer to a component Galaxy and a Target (\pxref class Target). Like a Universe, a Wormhole can perform the scheduling actions on the component Galaxy. A Wormhole is different from a Universe in that it is not a stand-alone object. Instead, it is triggered from the outer domain to initiate the scheduling. Also, since Wormhole is an abstract base class, you cannot create an object of class Wormhole; only derived Wormholes can be created. Each domain has a derived Wormhole class. For example, the SDF domain has class SDFWormhole. This domain-specific Wormhole is derived from not only the base Wormhole class but also from the domain-specific star class, SDFStar. This multiple inheritance realizes the inherent nature of the Wormhole. First, the Wormhole behaves exactly like a Star from the outer domain (SDF) since it is derived from SDFStar. Second, internally it can encapsulate an entire foreign domain with a separate Galaxy and a separate Target and Scheduler.

5.1.1 Wormhole public members

const char* insideDomain() const;

This function returns the name of the inside domain.

void setStopTime(double stamp);

This function sets the stop time for the inner universe.

Wormhole(Star& self, Galaxy& g, const char* targetName = 0); 
Wormhole(Star& self, Galaxy& g, Target* innerTarget = 0);

The above two signatures represent the constructors provided for class Wormhole. We never use plain Wormholes; instead we always have objects derived from Wormhole and some kind of Star. For example:

class SDFWormhole : public Wormhole, public SDFStar { 
public:
    SDFWormhole(Galaxy& g,Target* t) : Wormhole(*this,g,t) {
        buildEventHorizons();
    }

};

The first argument to the constructor should always be a reference to the object itself, and represents "the wormhole as a star". The second argument is the inner galaxy. The third argument describes the target of the Wormhole, and may be provided either as a Target object or by name, in which case it is created by using the KnownTarget class.

Scheduler* outerSched();

This returns a pointer to the scheduler for the outer domain (the one that lives above the wormhole). The scheduler for the inner domain for derived wormhole classes can be obtained from the scheduler() method.

5.1.2 Wormhole protected members

void setup();

The default implementation calls initTarget.

int run();

This function executes the inside of the wormhole for the appropriate amount of time.

void buildEventHorizons ();

This function creates the EventHorizon objects that connect the inner galaxy ports to the outside. A pair of EventHorizons is created for each galaxy port. It is typically called by the constructor for the XXXWormhole, where XXX is the outer domain name.

void freeContents();

This function deletes the event horizons and the inside galaxy. It is intended to be called from XXXWormhole destructors. It cannot be part of the Wormhole constructor due to an ordering problem (we want to assure that it is called before the destructor for either of XXXWormhole's two base classes is called).

virtual double getStopTime() = 0;

Get the stopping condition for the inner domain. This is a pure virtual function and must be redefined in the derived class.

virtual void sumUp();

This function is called by Wormhole::run after running the inner domain. The default implementation does nothing. Derived wormholes can redefine it to put in any "summing up" work that is required after running the inner domain.

Galaxy& gal;

The member gal is a reference to the inner galaxy of the Wormhole.