Syntax of CubePL

Syntax step by step

This chapter introduced the CubePL syntax of the most common programming structures.

Expressions

Constants

Any constant expression is an expression. eg. 123.0, "someString"

Arithmetical Expressions

Common mathematical notation of an arithmetical expression is valid in CubePL. Any arithmetical expression is an expression. eg. 123.0 + 23.6, sin(23)

Boolean Expressions

Common literal notation of a boolean expression is valid in CubePL. Any boolean expression is an expression.

[expression] or|and|xor [expression]

or

not [expression]

Any expression can be a term of a boolean expression. Non zero value is observed as TRUE, zero value is FALSE.

Function call expressions

Function calls have the following syntax:

name ( [expression ] )

Lambda function (In-place function definition)

To define a function in-place, one uses the following syntax:

{
[statement];
[statement];
...
return [expression];
}

In-place definition of a function is an expression. It means, it can appear everywhere, where one can use an expression.

Control structures

Control structures like if-else or while are statements.

Condition IF-ELSE

One can execute series of statements under a condition using the short form of the if statement:

if ( condition )
{
[statement];
[statement];
...
}

or full form with else :

if ( condition )
{
[statement];
[statement];
...
}
else
{
[statement];
[statement];
...
}

condition is a boolean expression

Loop WHILE

One can execute a series of statements as long as a condition is true using the while statement:

while ( condition )
{
[statement];
[statement];
...
}

Sequence of statements will be executed till condition is not fulfilled, max 1000000000 times.

Variables

CubePL allows to work with memory, by using variables. All variables are multi-typed:

  • In string context value of a numeric variable is presented in string format.
  • In numerical context a string variable is converted to its numerical representation, if possible. Otherwise it is 0.

All variables are arrays. Indexless access to the variable assummes mutually index value 0.

User defined Variables

The user can define a variable using the syntax:

${ name } = [expression];

or

${ name }[index] = [expression];

Currently its name is a fixed string of characters. In later versions of CubePL it will allow any expression.

Example of a string context :

${name} seq "STRING"

Example of a numeric context :

${name} >= 0.34

Example of an array access to the variable :

${name}[ ${i} ] >= 0.34

Access to the variable is an expression.

Index for the access to the value is also an expression.

Predefined Variables

Cube provides a set of predefined variables for every calculation, which values are independend. Following predefined variables do contain the general information about the cube:

Predefined variable Explanation
cube::#mirrors Number of mirrors in cube file
cube::#metrics Number of metrics in cube file
cube::#root::metrics Number of root metrics in cube file
cube::#regions Number of regions in cube file
cube::#callpaths Number of call paths in cube file
cube::#root::callpaths Number of root call paths
cube::#locations Number of locations in cube file
cube::#locations::void Number of void locations in cube file
cube::#locations::nonvoid Number of nonvoid locations in cube file
cube::#locationgroups Number of location groups in cube file
cube::#locationgroups::void Number of void location groups in cube file
cube::#locationgroups::nonvoid Number of nonvoid location groups in cube file
cube::#stns Number of system tree nodes in cube file
cube::#rootstns Number of root system tree nodes in cube file
cube::filename Name of the cube file

CubePL engine defines a set of variables, which do depend on an index, their "id". Using call sizeof(...) one can run over them and inspect within CubePL expression.

cube::metric::unit::name Unique name of the metric
cube::metric::disp::name Display name of the metric
cube::metric::url URL of the documentation of the metric
cube::metric::description Description of the metric
cube::metric::dtype Data type of the metric
cube::metric::uom Unit of measurement of the metric
cube::metric::expression CubePL expression of the metric
cube::metric::initexpression CubePL initialisation expression of the metric
cube::metric::parentd::id ID of the parent of the metric
cube::metric::#children Number of children in the metric

cube::callpath::mod

Module of the call path
cube::callpath::line File line of the call path
cube::calleeid ID of the callee region
cube::callpath::#children Number of children in the call path
cube::callpath::parent::id ID of the parent callpath
cube::region::name Name of the region
cube::region::mangled::name Mangled name of the region
cube::region::paradigm Name of the paradigm of the region
cube::region::role Name of the role the region is playing within the paradigm
cube::region::url URL with the description of the region of the call path
cube::region::description Description of the region of the call path
cube::region::mod Module of the region of the call path
cube::region::begin::line Begin line of the region of the call path
cube::region::end::line End line of the region of the call path
cube::stn::name Name of the system tree node
cube::stn::class Class of the system tree node
cube::stn::description Description of the system tree node
cube::stn::#children Number of children (other system tree nodes) of the system tree node
cube::stn::#locationgroups Number of location groups of the system tree node
cube::stn::parent::id ID (among all system tree nodes) of the parent of the system tree node
cube::stn::parent::sysid ID (global) of the parent of the system tree node
cube::locationgroup::name Name of the location group
cube::locationgroup::rank Rank of the location group
cube::locationgroup::type Type of the location group
cube::locationgroup::void Is the this location group void?
cube::locationgroup::#locations Number of locations of the location group
cube::locationgroup::parent::id ID (amoung all system tree nodes) of the parent system tree node
cube::locationgroup::parent::sysid ID (global) of the parent system tree node
cube::location::name Name of the location
cube::location::rank Rank of the location
cube::location::type Type of the location
cube::location::void Is the this location void?
cube::location::parent::id ID (among all location groups) of the parent location group
cube::location::parent::sysid ID (global) of the parent location group

CubePL engine sets a series of context sensetive variables, which value depends on the paramaters, for which the derived metric is being calculated. Their value can be used to refer to the values of context insensitive variables described above:

calculation::metric::id ID of the metric, being calculated
calculation::callpath::id ID of the callpath, for what is the metric being calculated
calculation::region::id ID of the region, for what is the metric being calculated
calculation::sysres::id ID (global) if the sysem resource, for what is the metric being calculated
calculation::sysres::kindType of the system element:
  • 0 = unknown
  • 5 = system tree node
  • 6 = location group
  • 7 = location

Different ways to refer an another metric

Context sensitive reference to another metric

To use values of another metric in the same calculation context, one uses syntax:

metric::[uniq_name]( modificator, modificator )

or

metric::[uniq_name]( modificator)

or

metric::[uniq_name]()

There are three version of this call:

  1. with two arguments (call path and system);
  2. with one argument (call path);
  3. with no argument(an arguments takes as '*').

modificator specifies flavor of the calculation: i - inclusive, e - exclusive, * - same like in calculation context.

Metric reference is an expression.

Context insensitive reference to another metric

To use values of another metric in the some fixed calculation context (e.g. aggregated over threads), one uses syntax:

metric::fixed::[uniq_name]( modificator, modificator )

or

metric::fixed::[uniq_name]( modificator)

or

metric::fixed::[uniq_name]()

There are three version of this call:

  1. with two arguments (call path and system);
  2. with one argument (call path);
  3. with no argument(an arguments takes as '*').

modificator specifies flavor of the calculation: i - inclusive, e - exclusive, * - same like in calculation context.

Metric reference is an expression.

Direct reference to another metric

To use values of another metric with an specific call path id and system resource id (!), one uses syntax:

metric::call::[uniq_name]( callpath id, modificator, sysres id, modificator )

or

metric::call::[uniq_name]( callpath id, modificator )

There are two version of this call:

  1. with four arguments (call path and system); - Only callculation of an inclusive or exclusive value is performed
  2. with one argument (call path); - Aggragation over system tree is performed additionally to the calculation of the inclisive or exclusive value for the calltree id

modificator specifies flavor of the calculation: i - inclusive, e - exclusive.

Metric reference is an expression.

Note that "sysres id" is a global identificator and can be refered using ${calculation::sysres::id}.

Definition of an encapsulated calculation within CubePL expression using metrics of Cube.

One special mechanis of CubePL processing engine allows some level of calculation separation. A derived metric can be created within another CubePL expression. Such "ghost" metric gets its name and properties and exists inside of the cube object as a casual metric. Only difference to the casual metric is in the fact that ghost metric is not visible in GUI and tools and is not stored inside of the metric tree of the cube file.

One can refer such metric as a casual metric using metric references (see 'Context sensitive reference to another metric' , 'Context insensitive reference to another metric' and 'Direct reference to another metric' ).

Example for definition of such metric :

cube::metric::nvisitors(e)
<<
{
${return}=0;
if ( ${cube::locationgroup::void}[${calculation::sysres::id}] != 1)
{
if (metric::visits()>0 )
{
${return} = 1;
};
};
return ${return};
}
>>;
${visitors} = metric::fixed::nvisitors(e);

where

cube::metric::prederived::nvisitors(e)

gives a type (prederives, exclusive) and unique name (nvisitors) of this metric. Unique name is used then later to refer to this metric via

${visitors} = metric::fixed::nvisitors(e);

There are kinds of metrics, which can be defined on such manner:

  1. cube::metric::prederived::name(e) - An exclusive prederived metric with the name name;
  2. cube::metric::prederived::name(i) - An inclusive prederived metric with the name name;
  3. cube::metric::postderived::name - A postderived metric with the name name.

Notice that once the metric with some unique name created it exists whole lifetime of the cube object. Therefore one can refer to some somewhere previously defined ghost metric from any following it CubePL expressions.

Ghost Metric definition is a statement.

Definition of an initialization expression for ghost metrics within CubePL expression.

One can specify within of a CubePL expression an initialisation phase for previously created ghost metric. For that purpose one uses expression cube::init::metric::[name]. Notice that named metric should be know by the moment of compilation of the CubePL expression.

Example for definition of such metric :

cube::init::metric::init::nvisitors
<<
{
global(nvisitors);
}
>>;

where

cube::init::metric::nvisitors

uses an unique name (nvisitors) of the metric.

Definition of the initialisation phase of a metric is a statement.

Definition of an initialization expression for ghost metrics within CubePL expression.

One can specify within of a CubePL expression an aggregation operator "+" or "-" for previously created ghost metric. For that purpose one uses expression cube::metric::plus::[name] or cube::metric::minus::[name]. Notice that named metric should be know by the moment of compilation of the CubePL expression.

Example for definition of such metric :

cube::init::metric::plus::nvisitors
<<
max( arg1, arg2)
>>;

or

cube::init::metric::minus::nvisitors
<<
min( arg1, arg2)
>>;

where

cube::init::metric:plus::nvisitors

or

cube::init::metric:minus::nvisitors

uses an unique name (nvisitors) of the metric.

Definition of the initialisation phase of a metric is a statement.

Grammar of CubePL

Here will be a full grammar of CubePL expressions (later).


Scalasca     Copyright © 1998–2015 Forschungszentrum Jülich, Jülich Supercomputing Centre