(Process Network Runner)

Joseph E Coffland

05 April 2006

Version 1.5.0

PNRunner runs process networks from a YML (Y-Chart Markup Language) description and its associated program libraries.

Table of Contents


PNRunner [OPTIONS] filename.yml [variable=value]


PNRunner is part of the SESAME software system. More information can be found on the web at

Given YML (Y-Chart Markup Language) input files, PNRunner loads the classes references in these files and executes the described process network. Currently only Kahn Process Networks are supported.

PNRunner processes can output event traces which describe their communication and computation actions. PNRunner can output these traces either to files or directly to an architecture simulator via supported inter-process communication methods. To output traces PNRunner also requires a YML mapping file.

A PNRunner YML application description describes process, their communication ports, and how they are connected to one another. See the section Files below for a description of YML properties specific to PNRunner.

Command Line Usage

There are two distinct ways to run PNRunner. Either as a standalone application simulator or in conjunction with an architecture simulator such as ymlpearl(1). As a standalone simulator PNRunner may or may not emit trace events to a file. When running PNRunner with an architecture simulator event traces are communicated through some form of inter-process communication (IPC). The next two sections explain these two modes of operation.

Standalone Application Simulation

To run PNRunner as a standalone application simulator with out outputting trace events simply execute the command PNRunner application.yml where application.yml is the YML file which describes the structure of the simulation. It may be necessary to also use the -L path library path option to assist PNRunner in finding the necessary application libraries.

If there are no errors the application will execute until all its processes finish. PNRunner does not print any status information as while the simulation is running unless you use the -P option. However, your application processes may print status information.

In order to write trace events to files you must use the -T basename option and supply a YML mapping with the -m mapping.yml option. The following example demonstrates application simulation with trace events written to files:

  PNRunner -T trace -m map.yml application.yml

The above example will produce trace files named trace0, trace1,. . ., traceN, where N is total number of application processes in your simulation. Trace numbers are assigned according the order in which application process appear in the mapping file. These traces can be read later by the architecture simulator using the same mapping file.

Application to Architecture Cosimulation

The easy way to start SESAME cosimulations is by using the SESAMERunner(1) utility. This section describes how to start simulations manually.

To run PNRunner in cosimulation with an architecture simulator you must use either the default system message queue mapping or the -S option for shared memory mapping. Shared memory mapping is much faster than system message queue mapping, but shared memory mapping does not work on some systems because of limitations on shared memory usage. The example below demonstrates running PNRunner with shared memory mapping in cosimulation.

  PNRunner -S -m map.yml application.yml

When the simulation starts PNRunner will print the chosen mapping key. This key must be passed to the architecture simulator to initiate trace event communication between the two simulators.

Once started PNRunner will wait for the architecture simulator to connect. At this point you should execute the architecture simulator with the same options and the mapping key printed by PNRunner in another terminal to start the cosimulation. If the architecture simulator does not connect with in 30 seconds PNRunner will time out and exit.

You may choose the mapping key ahead of time with the -K key option, but a key that is valid on one system is not necessarily valid on another. It is also difficult to guarantee that any specific key is not already in use by another process. By not specifying a mapping key the system will automatically pick a valid key.


-C directory
Change to directory before running.
Use the specified mapping key. Execution will fail if this key is already in use.
-L path
Add path to the library search path.
Only load the application and exit. Do not run it. Useful for check errors and printing. See -p.
-m mapping.yml
Output traces using the supplied mapping. If no key is given a random one will be choosen. See -K.
-P #
Print process states every # seconds.
Print a textual description of the network and exit.
Suppress interpreter output. (except errors)
Used the shared memory mapping interface rather than the default message queue interface.
-T basename
Output traces as 'basename<process id>'.
Print full stack trace on errors.

variable=value pairs can be used to pass parameters to your simulation at run time. This can be used, for example, to name input files. These variable value pairs are made available to the YML scripting language which in turn can pass the values to application processes via YML properties. See the YML Users Guide for more information.


.yml files
PNRunner reads YML application and mapping files. YML is described in detail in the YML Users Guide. YML usage specific to PNRunner is described in the PNRunner Users Guide.

Environment Variables

This variable is system dependent, but on POSIX compliant systems it specifies the shared library path. PNRunner requires several shared libraries which are included in the Sesame distribution and YML descriptions also include shared libraries. Depending on where these libraries are installed paths may need to be added to this variable.

PNRunner calls ymlpp(1), the YML preprocessor. ymlpp(1) must be on your PATH.



Joseph Coffland -
Simon Polstra -

See Also

PNRunnerYMLTool(1), ymlpearl(1), ymlpp(1), SESAMERunner(1), YML Users Guide,