[ Home | What's New | Contents | Overview | Contributors | Distribution | Examples | Documentation | Manual | Publications | Mailing List Archive | Problems ] This page was last updated by Axel Belinfante on 2006-06-30
TorX Test Tool Information
Prev   Next

torx-instantiator(5) - a program that implements an instantiator

Table of Contents


torx-instantiator - a program that implements an instantiator




This is all very new (and experimental), such that the default instantiator(1) does not (yet) use this interface!


In this man page we discribe the interface of the INSTANTIATOR module. The interface is very similar to the one of the PRIMER and the ADAPTOR (See torx-primer(5) and torx-adaptor(5)).

When active, the INSTANTIATOR receives commands from the standard input and writes answers in return to the standard output. See section COMMANDS for the available commands and answers. When the INSTANTIATOR is used in the TORX tool it is connected to the DRIVER which has the control and initiative of all communications. When the INSTANTIATOR is used standalone the user plays the role of the DRIVER.

A command consist of a single line of text. The keyword (the first word) of each commands start with a prefix C_.

An answer consist of a single line of text or a multi-line of text. All single-line answers start with a keyword that has prefix A_. Usually, the keyword of single-line answer is identical to the command-keyword, but with the C_ replaced by A_. A multi-line answer has specific markers around the body of the answer. These markers consist of a single line that starts with a prefix A_, followed by the command-keyword without the initial C_, followed by _START respectively _END. Each line of the body of a multi line answer often starts with a keyword (but not always).

Instead of the usual single- or multi-line answer, an A_ERROR answer may occur in case of an error. Such an A_ERROR answer comes instead of the usual single- or multi-line answer.

Additional message lines containing warnings (to be shown to the test run operator), diagnostics (to appear in the test run log), and/or debugging output (to be shown to the test run operator) may appear interspersed with the answer lines described so far. These message lines start with A_WARNING, A_LOG or A_DEBUG, respectively. Because these message lines may appear arbitrarily intermixed with the ``regular'' answer line(s), they do not play a role when the ``end'' of an answer has to be found: once the command-specific answer or A_ERROR answer has been read, the user of the INSTANTIATOR may assume that no other output (specific to to the command) will be generated by the INSTANTIATOR until the next command is send to it.

If the INSTANTIATOR decides autonomously that it will stop executing, it may try to indicate this by sending an A_QUIT answer, just before exiting. For the INSTANTIATOR, reading end-of-file on its standard input is a reason to stop executing.

In all cases, each command and each answer starts with a keyword that is separated from the remainder of the line by one or more spaces or tabs - except for two notable exceptions: A_ERROR, where currently exactely one space should be between the keyword and the category, and the lines between A_STATE_START and A_STATE_END, that do not start with a keyword (see DETAILS below). For most comands and most answers, the text following the keyword has a fixed format; for other commands and answers it is left unspecificed.

For command and answers that deal with channels, events, predicates, etc. the format of each line is as follows: the keyword is followed by a (possibly empty) TAB-separated list of name=value items, where the name cannot contain TABs or = characters, and the value cannot contain TAB characters. For the moment we assume that, when necessary, we will encode TAB characters for example using C conventions. We have chosen for this kind of item-lists because this makes it easy to pass information. Using name=value pairs instead of (for example) a list of values in a fixed order makes the interface more robust: the order of items is not important, and the users can simply ignore items which name they don't recognize. This allows one party to send items which the receiving party doesn't know about. This makes it easier to extend the interface by adding new items and keeping old programs backwards compatible.

For A_ERROR answers, currently the format is as follows: the A_ERROR keyword is followed by a category word indicating the category of the error, followed by arbitrary text that describes the error in more detail. The idea is that the user of the INSTANTIATOR can use the category word to get some idea of the nature of the error. In particular, the idea is that the user can use this to decide whether it makes sense to retry, or whether it is better to give up.


Here we describe first the syntax of the (textual) messages interchanged over the interface, followed by the possible message arguments, followed by the possible error categories.


Below we describes the syntax of the commands and answers, by giving the syntax of just a single interaction.
message* command message* answer-or-error
C_name arguments-upto-end-of-line nl
single-line-answer | multi-line-answer | error
A_name arguments-upto-end-of-line nl
A_name_START nl multi-line-element* A_name_END nl
message | result-element
A_element-name arguments-upto-end-of-line nl
debug | log | warning
A_DEBUG text-upto-end-of-line nl
A_LOG text-upto-end-of-line nl
A_WARNING text-upto-end-of-line nl
A_ERROR space category : text-upto-end-of-line nl
ws* | ws+ arguments
argument | argument tab arguments
name = value
/* value can contain spaces but no tabs */
ws* | ws+ arbitrary-text-without-newline
space | tab


At the moment the following names are defined for the name=value arguments to the commands:
with as value the LOTOS-like string representation of an event, used wherever ``event'' is used below;
with as value a channel name;
where iokind is a value input or output;
with as value either ``0'' or ``1'' to indicate a non-suspension resp. suspension event, used wherever an output ``event'' is used below (in the future we expect to use it also for input events)
with as value a pco name;
with as value a (string representation of the) concrete value (this string cannot contain tab or new-line characters);
with as value a (string representation of the) time


At the moment, for the A_ERROR category messages given by the INSTANTIATOR, the following categories are defined. The user of the INSTANTIATOR (i.e. torx) may use these categories to decide how to react to the A_ERROR answer (in particular, to decide whether it can cope with it, or whether it is better to give up).
the command is not known
a mandatory argument of the command is missing or incomplete
the value of an argument of the command is outside its domain of valid values
the command contains an event argument which cannot be parsed
the command contains an event argument, and the iokind of the event cannot be computed
the command contains more than a single argument, and the values of (some of) the arguments conflict which each other
an internal error occurred during the execution of the command


Below follows the list of the commands. The commands, and their answers, are described in more detail below. With each command, and answer, the possible arguments are indicated. Optional arguments are surrounded by brackets '[' and ']'. Note: the order in which the arguments are named with the commands does not prescribe the order in which arguments may appear: arguments may appear in any order.

C_EVENT [event] predicates

The C_EVENT command is the most important one, and has to be implemented correctly for TorX to work correctly; the other commands are less important, and most of them are mainly used to get configuration information from the INSTANTIATOR, only for logging purposes.

In the subsections below, each command is followed by a short explanation of its use. Additional comments are enclosed between /* and */ after the command.


The C_EVENT command is used to ask the INSTANTIATOR to generate a solution for the given predicates. Other fields may be given, and will appear unchanged in the answer. This command has no side-effects, and can repeatedly be applied without changing the state of the INSTANTIATOR module.
C_EVENT [event] predicates
Answer (single-line):
A_EVENT [event] predicates
Errors (single-line):

A_ERROR WrongValue /*if a given field has value outside domain*/


This command has not been implemented yet. It is to be used to get configuration information from the INSTANTIATOR.

Implementation Notes

For the implementer of an instantiator, the most important command to implement is C_EVENT.

For all the other commands, the implementer can choose to give simple answers, by returning just the answer keyword without parameters, for single-line answers, and returning just the answer start and answer end keywords for multiline answers. Of course, more informational answers proved more feedback during testing, and may make it more easy to investigate in case of errors -- the information above is mainly meant to make it easier to quickly implement a ``basic'' instantiator that already ``does the right thing''.

See Also

torx-intro(1), mkprimer(1), torx-primer(5), torx-adaptor(5), torx-config(4), torx-log(4), torx(1), sh(1)


By Email: <torx_support@cs.utwente.nl>


This manual page documents version 3.9.0 of torx.

Table of Contents

Prev Table of Contents Next
Appendix D: TorX Manual Pages: torx-explorer(5) - interface to program to explore a labelled transition Valid HTML 4.01! Appendix D: TorX Manual Pages: torx-primer(5) - interface to program that derives test primitives from