5.2 Class EventHorizon

Class EventHorizon is another example of a "mixin class"; EventHorizon has the same relationship to PortHoles as Wormhole has to Stars. The name is chosen from cosmology, representing the point at which an object disappears from the outside universe and enters the interior of a black hole, which can be thought of as a different universe entirely. As for wormholes, we never consider objects that are "just an EventHorizon". Instead, all objects that are actually used are multiply inherited from EventHorizon and from some type of PortHole class. For each type of domain we require two types of EventHorizon. The first, derived from ToEventHorizon, converts from a format suitable for a particular domain to the "universal form". The other, derived from FromEventHorizon, converts from the universal form to the domain-specific form.

5.2.1 How EventHorizons are used

Generally, EventHorizons are used in pairs to form a connection across a domain boundary between domain XXX and domain YYY. An object of class XXXToUniversal (derived from XXXPortHole and ToEventHorizon) and an object of class YYYFromUniversal (derived from YYYPortHole and FromEventHorizon) are inserted between the ordinary, domain-specific PortHoles. The far() member of the XXXToUniversal points to the XXXPortHole; the ghostAsPort() member points to the YYYFromUniversal object. Similarly, for the YYYFromUniveral object, far() points to the YYYPortHole and ghostAsPort() points to the XXXToUniversal object. These pairs of EventHorizons are created by the buildEventHorizons member function of class Wormhole.

5.2.2 EventHorizon public members

EventHorizon(PortHole* self);

The constructor for EventHorizon takes one argument, representing (for derived classes that call this constructor from their own), "myself" as a PortHole (a pointer to the PortHole part of the object). The destructor is declared virtual and does nothing.

PortHole* asPort();

This returns "myself as a PortHole".

PortHole* ghostAsPort();

This returns a pointer to the "matching event horizon" as a porthole.

virtual void ghostConnect(EventHorizon& to );

This connects another EventHorizon to myself and makes it my "ghost port".

virtual int isItInput() const; 
virtual int isItOutput() const;

Say if I am an input or an output.

virtual int onlyOne() const;

Derived EventHorizon classes should redefine this method to return TRUE for domains in which only one particle may cross the event horizon boundary per execution. The default implementation returns FALSE.

virtual void setEventHorizon(inOutType inOut, const char* portName,
     Wormhole* parentWormhole, Star* parentStar,
     DataType type = FLOAT, unsigned numTokens = 1 );

Sets parameters for the EventHorizon.

double getTimeMark(); 
void setTimeMark(double d);

Get and set the time mark. The time mark is an internal detail used for bookkeeping by schedulers.

virtual void initialize(); 
Scheduler *innerSched(); 
Scheduler *outerSched();

These methods return a pointer to the scheduler that lives inside the wormhole, or outside the wormhole, respectively.

5.2.3 EventHorizon protected members

void moveFromGhost(EventHorizon& from, int numParticles);

Move numParticles from the buffer of from, another EventHorizon, to mine (the object on which this function is called). This is used to implement ToEventHorizon::transferData.

CircularBuffer* buffer();

Access the myBuffer of the porthole.

EventHorizon* ghostPort;

This is the peer event horizon.

Wormhole* wormhole;

This points to the Wormhole I am a member of.

int tokenNew;
double timeMark;

TimeMark of the current data, which is necessary for interface of two domains. This may become a private member in future versions of Ptolemy.