2.7 Reference

2.7.1 Function read

Program 2.7.1   Read

template<class T>
void read(InPort<T>& s, T& t)

template<class T>
void read(InPort<T>& s, T* p, unsigned int n)

The function read (in file port.h) is an overloaded template function that consumes data from a given input port and stores this data in a given variable. The type of the input port must match with the type of the variable. This means that either both types are identical, or the variable is an array of the type of the input port. In the latter case one must provide a third argument to the read function which indicates the number of elements to be read.

2.7.2 Function write

Program 2.7.2   Write

template<class T>
void write(OutPort<T>& s, const T& t)

template<class T>
void write(OutPort<T>& s, const T* p, unsigned int n)

The function write (in file port.h) is an overloaded template function that copies^2.1 data contained in a given variable to a given output port. The type of the output port must match with the type of the variable. This means that either both types are identical, or the variable is an array of the type of the output port. In the latter case one must provide a third argument to the write function which indicates the number of elements to be written.

2.7.3 Function select

Program 2.7.3   Select

inline unsigned int select(SelectList& l);

template<class T0,class T1> 
unsigned int select(InPort<T0>&  p0, InPort<T1>&  p1)

template<class T0,class T1> 
unsigned int select(InPort<T0>&  p0, OutPort<T1>& p1)

template<class T0,class T1> 
unsigned int select(OutPort<T0>& p0, OutPort<T1>& p1)
        
template<class T0,class T1> 
unsigned int select(InPort<T0>&  p0, unsigned int n0, 
                    InPort<T1>&  p1, unsigned int n1)

template<class T0,class T1> 
unsigned int select(InPort<T0>&  p0, unsigned int n0, 
                    OutPort<T1>& p1, unsigned int n1)

template<class T0,class T1> 
unsigned int select(OutPort<T0>& p0, unsigned int n0, 
                    OutPort<T1>& p1, unsigned int n1)

The function select (in file select.h) is an overloaded template function that selects one of the given ports that is able to communicate the given requested number of tokens. The default value for the number of tokens is one. An input port can be selected if and only if it holds that the requested number of tokens is smaller than or equal to the number of tokens that the corresponding output port has committed to produce plus the number of tokens in the fifo. An output port can be selected if and only if it holds that the requested number of tokens is smaller than or equal to the number of tokens that the corresponding input port has committed to consume minus the number of tokens in the fifo.

To save space we have restricted the listed select operations to those that have two ports as arguments. YAPI also supports three and four ports as arguments. From YAPI Release 1.1 a select can be performed on a SelectList class that can hold an arbitrary number of ports. This is useful when a select on more than four ports is needed. For more details on SelectList see Section 2.7.13.

2.7.4 Class Id

Program 2.7.4   Id (id.h)

class IdBase
{
public:
    IdBase(const IdBase& i);
    IdBase(const char* n, IdBase* p);
    virtual ~IdBase();
  
    IdBase& operator+(char c);
    IdBase& operator+(const char* str);
    IdBase& operator=(const IdBase& i);
 
    IdBase*     parent() const;
    const char* name() const;
    const char* fullName(char* buf=0) const;

    operator const char*() const;

    IdBase id(const char* n);

private:
    char*   nm;  // name
    IdBase* pa;  // parent
};

class Id: public IdBase
{ 
public:
    Id(const char*, Id*);
    Id(const IdBase&);
    ~Id();
};

Id id(const char*);

The class Id (in file Id.h) provides a public interface to the class IdBase. The class IdBase is a base class of the classes ProcessNetwork, Process, Fifo InPort, and OutPort, but due to private inheritance it is not accessible.

The class Id has two constructors. The copy constructor of class Id is used to set the Id of member objects. In this case the member function id of class IdBase is called to create the Id for member objects. The id member function returns an IdBase with the given instance name and the object itself (this) as a parent. The non-member function id is used to create an Id for the root process network. This function returns an Id with the parent set to the null pointer. The constructor of class Id with two arguments is used to set the Id of the root process network.

The member function parent returns the parent object, represented by a pointer to an IdBase. The member function name returns the instance name of the object, represented as a null-terminated character string. The member function fullName returns the path name of the object within the network hierarchy. The full name is a null-terminated character string consisting of a concatenation of the names of all objects in the path, starting from the root object. The names in the path are separated by dots. If the function fullName is provided with the null pointer (default argument), the result will be placed in an internal static area, which will be preserved until the next call of fullName. Otherwise the result will be stored in the given array of characters. Finally, operator functions + and = are available.

2.7.5 Class In<T>

Program 2.7.5   In (io.h)

template<class T>
class In
{
public:
    virtual void read(T& value) = 0;
    virtual void read(T* p, unsigned int n) = 0;

    virtual Connector* connector() = 0;
};

The abstract template class In<T> (in file io.h) is a base class for the classes InPort<T> and Fifo<T> that provides a function read. The read function implements the YAPI function read.

2.7.6 Class Out<T>

Program 2.7.6   Out (io.h)

template<class T> 
class Out
{
public:
    virtual void write(const T& value) = 0;
    virtual void write(const T* p, unsigned int n) = 0;

    virtual Connector* connector() = 0;
};

The abstract template class Out<T> (in file io.h) is a base class for the classes OutPort<T> and Fifo<T> that provides a function write. The write function implements the YAPI function write.

2.7.7 Class Fifo<T>

Program 2.7.7   Fifo (fifo.h)

template<class T>
class Fifo : private FifoImplT<T>, 
             public In<T>, 
             public Out<T>
{
public:
    Fifo(const Id& n);
    Fifo(const Id& n, unsigned int lo);
    Fifo(const Id& n, unsigned int lo, 
         unsigned int hi);

    void read(T& t);
    void read(T* p, unsigned int n);

    void write(const T& t);
    void write(const T* p, unsigned int n);

    Connector* connector();
};

The template class Fifo<T> (in file fifo.h) inherits from the classes In<T>, and Out<t>. One can instantiate fifos of arbitrary types. At the time of instantiation one must provide an instance name, and optionally a minimum size, or a minimum size and a maximum size.

The fifo size has to be specified in terms of the number of elements of the fifo type. The fifo size times the number of bytes that is required to represent the fifo type gives the memory requirements in bytes. The run-time environment instantiates a fifo which has a size between the minimum and maximum size. If the maximum size is not given then it is assumed that the fifo size may be arbitrarily large. If, in addition, the minimum size is not given then it is assumed that the fifo size may be an arbitrarily small non-negative integer.

The minimum size is required to prevent deadlock in the application. The maximum size is required to cause deadlock in the application in order to analyze the occurrence of deadlock. The programmer can set the exact fifo size by setting both the minimum and maximum size to the desired size. Once the programmer has analyzed the deadlock behavior, it is a good programming practice to specify the minimum size to prevent deadlock and omit the maximum size to allow maximum implementation freedom.

The member function connector returns a this pointer, since Connector is a base class of class Fifo<T>.

2.7.8 Class InPort<T>

Program 2.7.8   InPort (port.h)

template<class T>
class InPort : public InPortImplT<T>, public In<T>
{
public:
    InPort(const Id& n, In<T>& i);

    void read(T& value);
    void read(T* p, unsigned int n);
};

The template class InPort<T> (in the file port.h) inherits from the class IdBase (via the subclass InPortImpT<T>), and In<T>. It inherits the function read which is called by the YAPI function read. One can instantiate input ports of arbitrary types in order to define the interface of a process. At the time of instantiation one must provide either a fifo or an input port of the encapsulating process network.

The functions name and fullname are also available. The function name returns the instance name of the InPort and the function fullname returns the path name of the InPort within the network hierarchy..

2.7.9 Class OutPort<T>

Program 2.7.9   OutPort (port.h)

template<class T>
class OutPort : public OutPortImplT<T>, public Out<T>
{
public:
    OutPort(const Id& n, Out<T>& o);

    void write(const T& value);
    void write(const T* p, unsigned int n);
};

The template class OutPort<T> (in file port.h) inherits from the class IdBase (via the subclass OutPortImpT<T>) and Out<T>. It inherits the function write which is called by the YAPI function write. One can instantiate output ports of arbitrary types in order to define the interface of a process. At the time of instantiation one must provide either a fifo or an output port of the encapsulating process network.

The functions name and fullname are also available. The function name returns the instance name of the OutPort and the function fullname returns the path name of the OutPort within the network hierarchy..

2.7.10 Class Process

Program 2.7.10   Process (process.h)

class Process : private ProcessImpl
{
public:
    Process(const Id& n);

protected:
    Id id(const char*);
    const char* name() const;
    const char* fullName() const;
    virtual const char* type() const = 0;

    virtual void main() = 0;
    void execute(const char* i);
};

The class Process (in file process.h) is a base class for user-defined process types. The class inherits from the class IdBase via the subclass ProcessImpl. The member functions id, name, and fullName make the corresponding member functions of the class IdBase accessible to the class Process and its subclasses. At the time of instantiation one must provide an instance name.

Furthermore, subclasses of Process must define a function type that must return the name of the subclass. In addition, they must define a function main that contains the functionality of the process type. A user-defined process type has input and output ports through which it communicates. The main function can read from the input ports via the function read and it can write to the output ports via the function write. To measure the computation workload, the main function of processes can be annotated with execute statements. An execute statement is a call of the protected member function execute. The argument of the execute statement is a symbolic instruction that represents the workload that is associated with a certain code fragment.

2.7.11 Class ProcessNetwork

Program 2.7.11   ProcessNetwork (network.h)

class ProcessNetwork : private NetworkImpl
{
public:
    ProcessNetwork(const Id& n);

protected:
    Id id(const char*);
    virtual const char* type() const = 0;
};

The Class ProcessNetwork (in file network.h) is a base class for user-defined process network types. The class inherits from the class IdBase via the subclass NetworkImpl. The member function id makes the member function id of the class IdBase accessible to the class ProcessNetwork and its subclasses. At the time of instantiation one must provide an instance name. Subclasses of ProcessNetwork must define a function type that must return the name of the subclass.

A user-defined process network has input and output ports through which it communicates. Furthermore, it has a number of internal fifos, processes, and process networks. The fifos are bound to the input and output ports of the internal processes and the internal process networks, and to the input and output ports of the process network itself.

2.7.12 Class RTE

Program 2.7.12   RTE (apiRte.h)

class RTE 
{
public:
    RTE ()  { r = ::newRte();};
    ~RTE () { delete r;};

    void start (ProcessNetwork& n);

    void setOutStream(std::ostream& o);
    void setErrorStream(std::ostream& e);
    std::ostream& getOutStream();
    std::ostream& getErrorStream();

private:
    Rte* r;
};

The class RTE is derived from a specific run time environment that controls the execution of the yapi network. The execution is started by calling the start function of this class. Furthermore the user can change the direction of the info and error messages by setting the out and error stream. By default these streams are directed to cout and cerr.

2.7.13 Class SelectList

Program 2.7.13   SelectList (select.h)

class SelectList : private SelectImpl
{
public:
    SelectList (const Id& n);

    template<class T>
    void pushBack(const InPort<T>& p, 
                  unsigned int n=1);
    inline void pushBack(const InPortImpl& p, 
                         unsigned int n=1);

    template<class T>
    void pushBack(const OutPort<T>& p, 
                  unsigned int n=1);
    inline void pushBack(const OutPortImpl& p, 
                         unsigned int n=1);

    inline unsigned int select ();
};

The class SelectList is a container class for ports that can be used as argument for the select function, as described in the function select section. The return value of the select member function is an index that indicates which port is selected. The ports in the SelectList container are ordened. The first port that is pushed on the list with the pushBack member function referenced with index 0. The next port that is pushed on the list with the pushBack is referenced with index one, etc. At least one port must be pushed on the list before the select member is called, otherwise the behaviour of the select call is undefined.

2.7.14 Function start

Program 2.7.14   Start (baseRte.h)

void start(const ProcessNetwork& n);

Note, this function has become obsolete. The member function start of class RTE (in file apiRte.h) is preferred.

The function start (in file baseRte.h) is used to start the execution of the instantiated process network. The function start starts all processes of the specified process network, and then waits until they have terminated or blocked. A process terminates when it reaches the end of main. One cannot explicitly start, stop, suspend, or resume individual processes. Process control can only be done via reads and writes on input and output channels.

2.7.15 Function printWorkload

Program 2.7.15   Workload (workload.h)

void printWorkload(const ProcessNetwork& n, 
                   std::ostream& o = std::cout);
void printComputationWorkload(
                   const ProcessNetwork& n, 
                   std::ostream& o = std::cout);
void printCommunicationWorkload(
                   const ProcessNetwork& n, 
                   std::ostream& o = std::cout);

After the execution of the process network the computation workload and the communication workload can be printed with the functions printWorkload, printComputationWorkload and printCommunicationWorkload (in file workload.h), respectively.

2.7.16 Function printDotty

Program 2.7.16   Dotty (dotty.h)

void printDotty(const ProcessNetwork& n, 
                std::ostream& o = std::cout, 
                std::ostream& e = std::cerr);

After the declaration of a process network its structure can be visualized with the function printDotty.