Overview

PGL is a high level, domain-specific language that is used to describe Polygraph workloads. PGL is somewhat similar to many modern programming languages but is much ``simpler''. On the other hand, PGL is more rich and complex than a typical configuration language. Our major objective in designing PGL was to have a language that allows to specify complex workloads in a ``natural'' way.

To get a general idea of PGL, you may want to browse through configuration files in the workloads/ directory of the Polygraph distribution and read documentation pages describing standard workloads.

Main PGL features are:

• domain specific (knows what Polygraph objects of interest are)
• free format (no dependency on line breaks and character positions)
• fixed number of available functions and procedures (one cannot add new ones)
• fixed number of available object types
• unlimited number of individual objects (variables)
• strict type checking (protects user from hidden type-mismatch errors)
• support for nested files (a file can import information from other files)
• support for basic arithmetic calculations

Many Polygraph programs such as polyclt and polysrv interpret a configuration file written in PGL, create and configure the objects described in the file, and start a test or otherwise make use of the information in the file.

In general, a workload is specified using these steps:

1. Define objects of interest, such as Polygraph Robots and Servers. Set specific properties of each object. For example, specify the IP addresses for Servers to listen on.

2. Specify relationships between the objects. For example, instruct Robot R1 to contact origin Servers S1 and S2.

3. Decide which objects and settings will actually be used for the simulation. Others will be simply ignored! Explicit use specification allows you to build a collection of useful objects and then use an appropriate subset for a particular experiment. Many commonly used objects are defined in PGL files located in the workloads/include/ directory.

4. If you want to check your configuration file or see how Polygraph interpreted your code, try the pgl_test program.

If needed, the steps may be reordered as long as all objects are defined before they are used.

Finally, here are a few facts that you should keep in mind when writing configuration files:

• PGL is case sensitive.

• There are no pointers, references, or ``pass by name'' parameters. A fresh copy of an object is created every time an object is passed to a function or assigned. Remember this fact when you modify an object a copy of which were already used elsewhere (your changes will not be propagated to old copies)!

• Polygraph interprets PGL; there is no compilation step.

• It is highly desirable and often required to feed the same configuration file to all Polygraph processes participating in the test. If you cannot design such a file, you are most likely doing something wrong.

• Current implementation is not foolproof. If you are too smart or careless, Polygraph may not catch your configuration errors. Fortunately, in most cases, you will get an assertion or a fatal error before the actual experiment begins.