Top Up Prev Next Bottom Contents Index Search

6.6 Class Geodesic

A Geodesic implements the connection between a pair, or a larger collection, of PortHoles. A Geodesic may be temporary, in which case it is deleted when the connection it implements is broken, or it can be permanent, in which case it can live in disconnected form. As a rule, temporary geodesics are used for point-to-point connections and permanent geodesics are used for netlist connections. In the latter case, the Geodesic has a name and is a member of a galaxy; hence, Geodesic is derived from NamedObj . The base class Geodesic, which is temporary, suffices for most simulation and code generation domains. In fact, in a number of these domains it contains unused features, so it is perhaps too "heavyweight" an object. A Geodesic contains a ParticleStack member which is used as a queue for movement of Particles between two portholes; it also has an originating port and a destination port. A Geodesic can be asked to have a specific number of initial particles. When initialized, it creates that number of particles in its ParticleStack; these particles are obtained from the Plasma of the originating port (so they will be of the correct type).

A severe limitation of the current Geodesic class is that it is designed around point-to-point connections, i.e., a single source port to a single destination port. This is a problem for domains that wish to support one-to-many geodesics (single source to multiple receivers) or many-to-many geodesics (such as multiple in/out ports connected to a common bus). Geodesic ought to be redesigned as a base class that supports any number of connected ports, with the restriction to point-to-point being a specialized subclass. This would also allow a cleaner treatment of autofork (autoforking geodesics could just be a subclass of Geodesic). It would be necessary to remove PortHole's belief that there is a unique far-side porthole, and that would require rethinking the porthole type resolution algorithm; probably type resolution should become a Geodesic function, not a PortHole function. This area will be addressed in some future version of Ptolemy.

6.6.1 Geodesic public members

virtual PortHole* setSourcePort (GenericPort &src, int delay = 0); 
Set the source port and the number of initial particles. The actual source port is determined by calling newConnection on src; thus if src is a MultiPortHole, the connection will be made to some port within that MultiPortHole, and aliases will be resolved. The return value is the "real porthole" used. In the default implementation, if there is already a destination port, any preexisting connection is broken and a new connection is completed.

virtual PortHole* setDestPort (GenericPort &dp); 
Set the destination port to dp.newConnection(). The return value is the "real porthole" used. In the default implementation, if there is already a source port, any preexisting connection is broken and a new connection is completed.

virtual int disconnect (PortHole & p); 
In the default implementation, if p is either the source port or the destination port, both the source port and destination port are set to null. This is not enough to break a connection; as a rule, disconnect should be called on the porthole, and that method will call this one as part of its work.

virtual void setDelay (int newDelay); 
Modify the delay (number of initial tokens) of a connection. The default implementation simply changes a count.

virtual int isItPersistent() const; 
Return TRUE if the Geodesic is persistent (may exist in a disconnected state) and FALSE otherwise. The default implementation returns FALSE.

PortHole* sourcePort () const; 
PortHole* destPort () const;
Return my source and destination ports, respectively.

virtual void initialize(); 
In the default implementation, this function initializes the number of Particles to that given by the numInitialParticles field (the value returned by numInit(); these Particles are obtained from the Plasma (allocation pool) for the source port. The particles will have zero value for numeric particles, and will hold the "empty message" for message Particles.

void put(Particle* p); 
Put a particle into the Geodesic (using a FIFO discipline).

Particle* get(); 
Retrieve a particle from the Geodesic (using a FIFO discipline). Return a null pointer if the Geodesic is empty.

void pushBack(Particle* p); 
Push a Particle back into the Geodesic (onto the front of the queue, instead of onto the back of the queue as put does).

int size() const; 
Return the number of Particles on the Geodesic at the current time.

int numInit() const; 
Return the number of initial particles. This call is valid at any time. Immediately after initialize, size and numInit return the same value (and this should be true for any derived Geodesic as well), but this will not be true during execution (where numInit stays the same and size changes).

StringList print(int verbose = 0) const; 
Print information on the Geodesic, overrides NamedObj function.

virtual void incCount(int); 
virtual void decCount(int);
These methods are available for schedulers such as the SDF scheduler to simulate a run and keep track of the number of particles on the geodesic. incCount increases the count, decCount decreases it, They are virtual to allow additional bookkeeping in derived classes.

int maxNumParticles() const;
Return maximum number of particles.

virtual void makeLock(const PtGate& master);
Create a lock for the Geodesic.

virtual void delLock();
Delete lock for the Geodesic.

int isLockEnabled() const;
Return lock status.

const char * initDelayValues();
Return the initValues string.

6.6.2 Geodesic protected members

void portHoleConnect(); 
This function completes a connection if the originating and destination ports are set up.

virtual Particle* slowGet();
virtual void slowPut(Particle*);
The "slow" versions of get() and put().

PortHole *originatingPort;
PortHole *destinationPort;
These protected members point to my neighbors.

Top Up Prev Next Bottom Contents Index Search
Copyright © 1990-1997, University of California. All rights reserved.