Co-simulation

Co-simulation allows the simulation of a POOSL model to interact with the outside world, and to synchronize multiple simulations. The POOSL mechanism for co-simulation is based on external system ports. Each external system port is implemented via an adapter that is specified in an external port configuration file (.ini). The examples bundle (download) contain three examples (FileCopy, SocketExample, and SocketExampleDistributed) that use co-simulation.

When debugging a POOSL model, the adapter instances are visible in the Debug View and in the Sequence Diagram. Moreover they can be inspected in the Execution Tree View after selecting one:

External System Ports: Model Syntax

External system ports are defined in the optional ports section of the system definition. The syntax for this section is identical to the syntax for ports of a cluster or process class.

Example

The following example POOSL model has 4 external system ports:

        system
        ports
            ep1
            ep2
            ep3
            ep4
        instances
            proc : MyProcess()
        channels
            { ep1, proc.port1 }
            { ep2, proc.port2 }
            { ep3, proc.port3 }
            { ep4, proc.port4 }

External System Ports: Configuration File

External system ports are connected to adapters as specified in the external port configuration file. This file is in the INI file format:

	[section]
	key1=value1
	key2=value2

Each external system port is described in one section of the file, where the name of the section is equal to the name of the external system port in the model. Each section has one mandatory key, namely the key "type", which defines the type of adapter for the external system port.

When launching a new POOSL model with an INI file in the same directory, this INI file will automatically be used. To manually select a different INI file, or adding one later on, the Launch Configuration settings can be used.

Example

The following example .ini file describes four external system ports of different types:

	[ep1]
	type=SocketClient
	hostname=localhost
	port_number=9060

	[ep2]
	type=SocketServer
	port_number=9060
	
	[ep3]
	type=FileIn
	filename=../FileToCopy.txt

	[ep4]
	type=FileOut
	filename=../CopiedFile.txt

External System Ports: Supported Adapter Types

The following list describes the currently supported adapter types, and their keys for specifying additional properties (if any):

SocketClient
- port_number: The port that the socket should connect to.
- hostname: The server that the socket should connect to.
- read_buffer_size: An optional field to specify the size (in bytes) of the internal read-ahead buffer.*
SocketServer
- port_number: The port that the socket should listen on.
- read_buffer_size: An optional field to specify the size (in bytes) of the internal read-ahead buffer.*
FileIn
- filename: Path to the text file to read from. The path can be absolute, or relative to the "simulator" directory in which the POOSL model is simulated.
- read_buffer_size: An optional field to specify the size (in bytes) of the internal read-ahead buffer.*
FileOut
- filename: Path to the text file to write into. The path can be absolute, or relative to the "simulator" directory in which the POOSL model is simulated.
- mode: This optional field can be 'open' or 'append'; the default value is 'open'.
  - open: If the file does not exist, it is created. If the file already exists, the existing content is cleared.
  - append: If the file does not exist, it is created. If the file already exists, the existing content is preserved.
Console

* : The size of the buffer determines the maximum number of bytes can be received in one message. The default value is 10kbyte. Only adjust this option if you need to read more then 10kbyte of data in one receive statement.

Connection Status

When starting the simulation of a POOSL model, these adapters will automatically try to set-up their file or socket connection. If afterwards the file or socket connection is lost or closed, the adapter will not try to reconnect.

After the connection has been lost or closed, the adapter blocks all messages except for status messages like isConnected(Boolean) as specified below. Thus the simulation engine can determine that the model has terminated if the model is only waiting for external input.

Supported messages on external ports

The following lists contain the messages that can be send and received by the various adapters. The supported messages can also be observed in the Execution Tree view by selecting an adapter instance in the Debug View; see the earlier screenshot on this page. Note that the messages that can be received by the adapter need to be send by the rest of the model, for example, ep!writeString("word").

Be aware that the IDE does not validate whether the used external port messages in the POOSL model are supported by the adapter selected in the INI file.

SocketClient and SocketServer messages

Messages that can be received by the adapter:
- writeLine(String): Write the String to the socket (its characters, not its syntactic representation) followed by new line character LF(10).
- writeString(String): Write a syntactic representation of the String to the socket.
- write(String): Write the String to the socket (not its syntactic representation).
- writeCharacters(Array): Write the characters in the Array to the socket. The Array is only allowed to contain characters.
- close(): Close the open socket and clear the internal buffers. Afterwards the adapter for this external port is terminated.
- setReadSize(Integer): Set the number of characters to read using readCharacters(Array).
- setReadUntilSeparator(Char): Set the 'readUntil' character that is used by readUntil(String).

Messages that can be send by the adapter:
- readLine(String): Read from the socket a full line. It returns the sequence of non-new line characters (as a String) until the first new-line character sequence after this sequence. The read pointer has been advanced till after the longest new-line character sequence immediately following the non-newline characters (if the line ends in CR(13) followed by LF(10) it advances till after the LF(10)). The new line characters are not part of the returned String.
- readString(String): Read from the socket an escaped string. In case the character sequence starting from the double quote character is a valid syntactical representation of a String, then this String is returned. The read pointer has advanced till after the end of the String representation. In case the character sequence is not a valid syntactical representation of a String and cannot be completed to a valid String, an error is generated.
- readWord(String): Read from the socket and return the sequence of non-white space characters (as a String). The read starts after a possibly empty sequence of white-space characters until the first white space character after this sequence. The read pointer has been advanced till immediately after the first white space character after the sequence of non-white space characters. None of the white space characters before or after the word are part of the returned String.
- readCharacters(Array): Read from the socket the number of characters configured by setReadSize(Integer). It returns the sequence of characters as an Array containing Char elements. The read pointer has been advanced till after the last read character.
- readUntil(String): Read from the socket until the first occurrence of character set by setReadUntilSeparator(Char). It returns the sequence of characters (as a String). The read pointer has been advanced till after the last read character. The character is not returned as part of the String. This method returns nil if there is no character set by setReadUntilSeparator(Char).
- isConnected(Boolean): Indicate in the parameter whether the socket is connected.

FileOut messages

Messages that can be received by the adapter:
- write(String): Write the String to the file (not its syntactic representation).
- writeLine(String): Write the String to the file (its characters, not its syntactic representation) followed by new line character LF(10).
- writeString(String): Write a syntactic representation of the String to the file.
- writeCharacters(Array): Write the characters in the Array to the file. The Array is only allowed to contain characters.
- close(): Close the open file and clear the internal buffers. Afterwards the adapter for this external port is terminated.

FileIn messages

Messages that can be received by the adapter:
- setReadUntilSeparator(Char): Set the 'readUntil' character that is used by readUntil(String).
- setReadSize(Integer): Set the number of characters to read using readCharacters(Array).
- close(): Close the open file and clear the internal buffers. Afterwards the adapter for this external port is terminated.

Messages that can be send by the adapter:
- readLine(String): Read from the file a full line. It returns the sequence of non-new line characters (as a String) until the first new-line character sequence after this sequence. The read pointer has been advanced till after the longest new-line character sequence immediately following the non-newline characters (if the line ends in CR(13) followed by LF(10) it advances till after the LF(10)). The new line characters are not part of the returned String.
- readString(String): Read from the file an escaped string. In case the character sequence starting from the double quote character is a valid syntactical representation of a String, then this String is returned. The read pointer has advanced till after the end of the String representation. In case the character sequence is not a valid syntactical representation of a String and cannot be completed to a valid String, an error is generated.
- readUntil(String): Read from the file until the first occurrence of character set by setReadUntilSeparator(Char). It returns the sequence of characters (as a String). The read pointer has been advanced till after the last read character. The character is not returned as part of the String. This method returns nil if there is no character set by setReadUntilSeparator(Char).
- readWord(String): Read from the file and return the sequence of non-white space characters (as a String). The read starts after a possibly empty sequence of white-space characters until the first white space character after this sequence. The read pointer has been advanced till immediately after the first white space character after the sequence of non-white space characters. None of the white space characters before or after the word are part of the returned String.
- readCharacters(Array): Read from the file the number of characters configured by setReadSize(Integer). It returns the sequence of characters as an Array containing Char elements. The read pointer has been advanced till after the last read character.
- atEndOfFile(Boolean): Indicate in the parameter whether the read pointer in the file points at the end of the file.

Console messages

Messages that can be received by the adapter:
- write(String): Write the String to stdout (not its syntactic representation).
- writeLine(String): Write the String to stdout (its characters, not its syntactic representation) followed by new line character LF(10).
- writeString(String): Write a syntactic representation of the String to stdout.
- writeCharacters(Array): Write the characters in the Array to stdout. The Array is only allowed to contain characters.
- writeError(String): Write the String to stderr (not its syntactic representation).
- writeErrorLine(String): Write the String to stderr (its characters, not its syntactic representation) followed by new line character LF(10).
- writeErrorString(String): Write a syntactic representation of the String to stderr.
- writeErrorCharacters(Array): Write the characters in the Array to stderr. The Array is only allowed to contain characters.