blob: 24ae5abb1ec24d8daacda493b0b0acb095452465 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
<title>eTrice Documentation</title>
<!-- Bootstrap -->
<link rel="stylesheet" type="text/css" href="css/bootstrap.min.css"/>
<link rel="stylesheet" type="text/css" href="css/metisMenu.min.css"/>
<link rel="stylesheet" type="text/css" href="css/font-awesome.min.css"/>
<link rel="stylesheet" type="text/css" href="css/prettify.css"/>
<link rel="stylesheet" type="text/css" href="css/custom.css"/>
<link rel="stylesheet" type="text/css" href="css/custom-common.css"/>
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<!-- Fixed navbar -->
<nav class="navbar navbar-default navbar-static-top" role="navigation">
<div class="container">
<div class="navbar-header">
<a class="navbar-brand" style="padding-bottom: 2px; padding-top: 4px;" href="introduction.html"><img style="height: 100%;" src="images/logo/etrice-logo-interim.png"></a>
</div>
<div id="navbar" class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li class="active"><a href="introduction.html">Online Documentation</a></li>
<li><a href="http://www.eclipse.org/forums/eclipse.etrice">Newsgroup</a></li>
<li><a href="https://www.eclipse.org/etrice/">eTrice Home</a></li>
<li><a href="https://www.eclipse.org/etrice/download.php">Downloads</a></li>
<li><a href="https://git.eclipse.org/c/etrice/org.eclipse.etrice.git/">Git repository</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-sm-3">
<div id="sidebar" role="navigation">
<ul class="nav metismenu" id="sidebarMenu">
<li><a href="introduction.html" aria-expanded="false">Introduction <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="introduction.html#etrice-overview" aria-expanded="false">eTrice Overview <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="introduction.html#what-is-etrice-">What is eTrice?</a></li>
<li><a href="introduction.html#reduction-of-complexity">Reduction of Complexity</a></li>
</ul>
</li>
<li><a href="introduction.html#introduction-room-language" aria-expanded="false">Introduction ROOM Language <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="introduction.html#scope-of-room">Scope of ROOM</a></li>
<li><a href="introduction.html#basic-concepts">Basic Concepts</a></li>
<li><a href="introduction.html#execution-models">Execution Models</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tutorials.html" aria-expanded="false">Tutorials <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="tutorials.html#working-with-the-tutorials">Working with the tutorials</a></li>
<li><a href="tutorials.html#getting-started-c">Getting Started C</a></li>
<li><a href="tutorials.html#getting-started-c-">Getting Started C++</a></li>
<li><a href="tutorials.html#getting-started-java">Getting Started Java</a></li>
<li><a href="tutorials.html#tutorial-ping-pong-java-c-and-c-" aria-expanded="false">Tutorial Ping Pong Java, C and C++ <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="tutorials.html#scope">Scope</a></li>
<li><a href="tutorials.html#create-the-structure">Create the structure</a></li>
<li><a href="tutorials.html#implement-the-behavior">Implement the Behavior</a></li>
<li><a href="tutorials.html#summary">Summary</a></li>
</ul>
</li>
<li><a href="tutorials.html#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
<li><a href="standalone-generators.html">Standalone Generators</a></li>
<li><a href="examples.html" aria-expanded="false">Examples <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="examples.html#the-c-examples-project" aria-expanded="false">The C examples project <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="examples.html#traffic-light-step-1">Traffic light - step 1</a></li>
<li><a href="examples.html#traffic-light-step-2">Traffic light - step 2</a></li>
<li><a href="examples.html#traffic-light-step-3">Traffic light - step 3</a></li>
<li><a href="examples.html#traffic-light-step-4">Traffic light - step 4</a></li>
<li><a href="examples.html#features">Features</a></li>
</ul>
</li>
<li><a href="examples.html#the-java-examples-project" aria-expanded="false">The Java examples project <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="examples.html#dynamic-actors-1">Dynamic Actors 1</a></li>
<li><a href="examples.html#dynamic-actors-2">Dynamic Actors 2</a></li>
<li><a href="examples.html#dynamic-actors-3">Dynamic Actors 3</a></li>
<li><a href="examples.html#dynamic-actors-4">Dynamic Actors 4</a></li>
<li><a href="examples.html#dynamic-actors-5">Dynamic Actors 5</a></li>
<li><a href="examples.html#dynamic-actors-6">Dynamic Actors 6</a></li>
<li><a href="examples.html#dynamic-actors-7">Dynamic Actors 7</a></li>
<li><a href="examples.html#dynamic-actors-8">Dynamic Actors 8</a></li>
<li><a href="examples.html#dynamic-actors-9">Dynamic Actors 9</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="room-concepts.html" aria-expanded="false">ROOM Concepts <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="room-concepts.html#actors">Actors</a></li>
<li><a href="room-concepts.html#protocols">Protocols</a></li>
<li><a href="room-concepts.html#ports">Ports</a></li>
<li><a href="room-concepts.html#dataclass">DataClass</a></li>
<li><a href="room-concepts.html#layering">Layering</a></li>
<li><a href="room-concepts.html#finite-state-machines">Finite State Machines</a></li>
</ul>
</li>
<li><a href="etrice-features.html" aria-expanded="false">eTrice Features <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="etrice-features.html#model-navigation" aria-expanded="false">Model Navigation <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="etrice-features.html#from-model-to-behavior-to-structure">From Model to Behavior to Structure</a></li>
<li><a href="etrice-features.html#model-navigation">Model Navigation</a></li>
<li><a href="etrice-features.html#navigating-behavior-diagrams">Navigating Behavior Diagrams</a></li>
<li><a href="etrice-features.html#navigating-structure-diagrams">Navigating Structure Diagrams</a></li>
</ul>
</li>
<li><a href="etrice-features.html#etrice-java-projects" aria-expanded="false">eTrice Java Projects <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="etrice-features.html#eclipse-jdt-build">Eclipse JDT Build</a></li>
</ul>
</li>
<li><a href="etrice-features.html#automatic-diagram-layout-with-kieler" aria-expanded="false">Automatic Diagram Layout with KIELER <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="etrice-features.html#overview">Overview</a></li>
<li><a href="etrice-features.html#performing-automatic-layout">Performing Automatic Layout</a></li>
<li><a href="etrice-features.html#layout-options">Layout Options</a></li>
<li><a href="etrice-features.html#configuring-layout-options">Configuring Layout Options</a></li>
<li><a href="etrice-features.html#special-layout-options">Special Layout Options</a></li>
<li><a href="etrice-features.html#further-references">Further References</a></li>
</ul>
</li>
<li><a href="etrice-features.html#annotations" aria-expanded="false">Annotations <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="etrice-features.html#annotation-type-definitions">Annotation Type Definitions</a></li>
<li><a href="etrice-features.html#usage-and-effect-of-the-pre-defined-annotations">Usage and Effect of the Pre-defined Annotations</a></li>
</ul>
</li>
<li><a href="etrice-features.html#enumerations">Enumerations</a></li>
<li><a href="etrice-features.html#etrice-models-and-their-relations" aria-expanded="false">eTrice Models and Their Relations <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="etrice-features.html#the-room-model">The ROOM Model</a></li>
<li><a href="etrice-features.html#the-config-model">The Config Model</a></li>
<li><a href="etrice-features.html#the-physical-model">The Physical Model</a></li>
<li><a href="etrice-features.html#the-mapping-model">The Mapping Model</a></li>
</ul>
</li>
<li><a href="etrice-features.html#interface-contracts" aria-expanded="false">Interface Contracts <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="etrice-features.html#defining-contracts">Defining Contracts</a></li>
<li><a href="etrice-features.html#contract-monitor-generation">Contract Monitor Generation</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="feature-reference.html" aria-expanded="false">Feature Reference <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="feature-reference.html#roomlanguage" aria-expanded="false">ROOMLanguage <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="feature-reference.html#configmodel">ConfigModel</a></li>
<li><a href="feature-reference.html#logicalmodel" aria-expanded="false">LogicalModel <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="feature-reference.html#actorclass">ActorClass</a></li>
<li><a href="feature-reference.html#actorref">ActorRef</a></li>
<li><a href="feature-reference.html#annotation">Annotation</a></li>
<li><a href="feature-reference.html#annotationtype">AnnotationType</a></li>
<li><a href="feature-reference.html#attribute">Attribute</a></li>
<li><a href="feature-reference.html#binding">Binding</a></li>
<li><a href="feature-reference.html#cpbranchtransition">CPBranchTransition</a></li>
<li><a href="feature-reference.html#choicepoint">ChoicePoint</a></li>
<li><a href="feature-reference.html#communicationtype">CommunicationType</a></li>
<li><a href="feature-reference.html#continuationtransition">ContinuationTransition</a></li>
<li><a href="feature-reference.html#dataclass">DataClass</a></li>
<li><a href="feature-reference.html#datatype">DataType</a></li>
<li><a href="feature-reference.html#entrypoint">EntryPoint</a></li>
<li><a href="feature-reference.html#enumeration">Enumeration</a></li>
<li><a href="feature-reference.html#executiontype">ExecutionType</a></li>
<li><a href="feature-reference.html#exitpoint">ExitPoint</a></li>
<li><a href="feature-reference.html#externalendport">ExternalEndPort</a></li>
<li><a href="feature-reference.html#externaltype">ExternalType</a></li>
<li><a href="feature-reference.html#inheritance">Inheritance</a></li>
<li><a href="feature-reference.html#initialtransition">InitialTransition</a></li>
<li><a href="feature-reference.html#internalendport">InternalEndPort</a></li>
<li><a href="feature-reference.html#layerconnection">LayerConnection</a></li>
<li><a href="feature-reference.html#logicalsystem">LogicalSystem</a></li>
<li><a href="feature-reference.html#operation">Operation</a></li>
<li><a href="feature-reference.html#port">Port</a></li>
<li><a href="feature-reference.html#portclass">PortClass</a></li>
<li><a href="feature-reference.html#primitivetype">PrimitiveType</a></li>
<li><a href="feature-reference.html#protocolclass">ProtocolClass</a></li>
<li><a href="feature-reference.html#refinedstate">RefinedState</a></li>
<li><a href="feature-reference.html#relayport">RelayPort</a></li>
<li><a href="feature-reference.html#replication">Replication</a></li>
<li><a href="feature-reference.html#sap">SAP</a></li>
<li><a href="feature-reference.html#spp">SPP</a></li>
<li><a href="feature-reference.html#serviceimplementation">ServiceImplementation</a></li>
<li><a href="feature-reference.html#simplestate">SimpleState</a></li>
<li><a href="feature-reference.html#state">State</a></li>
<li><a href="feature-reference.html#stategraphnode">StateGraphNode</a></li>
<li><a href="feature-reference.html#statemachine">StateMachine</a></li>
<li><a href="feature-reference.html#subsystemclass">SubSystemClass</a></li>
<li><a href="feature-reference.html#subsystemref">SubSystemRef</a></li>
<li><a href="feature-reference.html#trpoint">TrPoint</a></li>
<li><a href="feature-reference.html#transition">Transition</a></li>
<li><a href="feature-reference.html#transitionpoint">TransitionPoint</a></li>
<li><a href="feature-reference.html#triggeredtransition">TriggeredTransition</a></li>
</ul>
</li>
<li><a href="feature-reference.html#mappingmodel">MappingModel</a></li>
<li><a href="feature-reference.html#physicalmodel">PhysicalModel</a></li>
</ul>
</li>
<li><a href="feature-reference.html#modeleditors" aria-expanded="false">ModelEditors <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="feature-reference.html#graphicalbehavioreditor">GraphicalBehaviorEditor</a></li>
<li><a href="feature-reference.html#graphicalstructureeditor" aria-expanded="false">GraphicalStructureEditor <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="feature-reference.html#actorrefpropertydialog">ActorRefPropertyDialog</a></li>
<li><a href="feature-reference.html#portpropertydialog">PortPropertyDialog</a></li>
<li><a href="feature-reference.html#spppropertydialog">SPPPropertyDialog</a></li>
<li><a href="feature-reference.html#structureeditorpalette">StructureEditorPalette</a></li>
</ul>
</li>
<li><a href="feature-reference.html#textualroomeditor" aria-expanded="false">TextualROOMEditor <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="feature-reference.html#outlineview">OutlineView</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="feature-reference.html#codegenerators" aria-expanded="false">CodeGenerators <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="feature-reference.html#ccodegenerator">CCodeGenerator</a></li>
<li><a href="feature-reference.html#cppcodegenerator">CPPCodeGenerator</a></li>
<li><a href="feature-reference.html#generationoptions">GenerationOptions</a></li>
<li><a href="feature-reference.html#javacodegenerator">JavaCodeGenerator</a></li>
<li><a href="feature-reference.html#msclogging">MSCLogging</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="Dave-Integration.html" aria-expanded="false">Dave Integration <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="Dave-Integration.html#dave-etrice-toolchain-tutorial" aria-expanded="false">DAVE-eTrice Toolchain Tutorial <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="Dave-Integration.html#introduction">Introduction</a></li>
<li><a href="Dave-Integration.html#getting-started-without-operating-system">Getting Started without Operating System</a></li>
<li><a href="Dave-Integration.html#getting-started-with-freertos">Getting Started with FreeRTOS</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="ResourceRequirements.html">Resource Requirements</a></li>
<li><a href="developers-reference.html" aria-expanded="false">Developer's Reference <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="developers-reference.html#etrice-tool-developer-s-reference" aria-expanded="false">eTrice Tool Developer’s Reference <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="developers-reference.html#architecture" aria-expanded="false">Architecture <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="developers-reference.html#editor-and-generator-components">Editor and Generator Components</a></li>
<li><a href="developers-reference.html#the-abstract-finite-state-machine-concept">The Abstract Finite State Machine Concept</a></li>
<li><a href="developers-reference.html#runtimes">Runtimes</a></li>
<li><a href="developers-reference.html#unit-tests">Unit Tests</a></li>
</ul>
</li>
<li><a href="developers-reference.html#component-overview" aria-expanded="false">Component Overview <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="developers-reference.html#room-language-overview">Room Language Overview</a></li>
<li><a href="developers-reference.html#config-language-overview">Config Language Overview</a></li>
<li><a href="developers-reference.html#aggregation-layer-overview">Aggregation Layer Overview</a></li>
<li><a href="developers-reference.html#generator-overview">Generator Overview</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="release-notes.html" aria-expanded="false">Release Notes <span class="fa arrow"></span></a>
<ul class="nav" aria-expanded="false">
<li><a href="release-notes.html#2-0-0-migration">2.0.0 Migration</a></li>
</ul>
</li>
</ul>
</div>
</div>
<span class="version pull-right">version 3.x</span></p>
<div class="col-sm-9">
<h1><a href="#examples" name="examples"></a>Examples</h1>
<p>The eTrice examples can be installed using the new wizard.</p>
<p>Choose File &gt; New &gt; Other (or Ctrl-N), open category “eTrice”. There are examples for C and for Java. Each of them consists of a single Eclipse project that contains several examples which are described in the next sections. Select the desired one, click Next and Finish and you are ready to go.</p>
<p>As already mentioned each example project contains several examples. Each of them comes with a room model, a mapping model a launch configuration for the code generation and a launch configuration to run the compiled example.</p>
<h2><a href="#the-c-examples-project" name="the-c-examples-project"></a>The C examples project</h2>
<p>This example project <code>org.eclipse.etrice.examples.c</code> illustrates a simplified traffic light control. It actually consists of four different steps of increasing complexity that can be generated and built one by one (but not in parallel).</p>
<p>Most of the classes are contained in a common ROOM model <code>model/TrafficLight/TrafficLight.room</code> that also shows how ROOM classes can form a library and be used as building blocks for several systems. Also the physical model is shared by all steps of this example.</p>
<p>Contained in the example you will find a little Java GUI that some of the examples use to simulate a real traffic light. The GUI is contacted using TCP/IP ports 4441 and subsequent. The protocol used on the TCP/IP socket connection is a simple text protocol with commands for the lights. Three of the example steps make use of this simulator GUI. They also contain a launch configuration for it.</p>
<p><strong>Note:</strong> Before compiling and linking a new step of the example the project should be cleaned to avoid duplicate symbols due to artifacts from the previous build.</p>
<h3><a href="#traffic-light-step-1" name="traffic-light-step-1"></a>Traffic light - step 1</h3>
<p>The main ROOM model and the mapping model of this example is contained in <code>org.eclipse.etrice.examples.c/model/TrafficLight_step1</code>. It also contains launch configurations for the code generation and for running the application.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>This example illustrates how a single actor can be tested against a test harness.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>A <code>PedestrianTrafficLightController</code> is an actor that controls a traffic light consisting of a traffic light with red, yellow and green for the cars, a second traffic light with just red and green and a request button for the pedestrians.</p>
<p>The controller has two ports, <code>fct</code> and <code>tlInterface</code>. The first one uses a protocol <code>PTrafficLightController</code> that offers the high level commands <code>standby</code>, <code>start</code> and <code>stop</code>. The second one uses a conjugated protocol <code>PTrafficLightInterface</code> which controls each of the lights separately.</p>
<p>The test harness <code>TrafficLightControllerTestHarness</code> is connected to both ports and drives the test in several steps.</p>
<p>To run the test first generate the code using <code>gen_TrafficLight_step1.launch</code>, then compile and link it (using the CDTbuild). Since this step doesn’t use a GUI you can just start the application using <code>run_TrafficLight_step1.launch</code>.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>
<p>usage of a ROOM model as library for several systems</p></li>
<li>
<p>creation of a test harness for an actor</p></li>
</ul>
<h3><a href="#traffic-light-step-2" name="traffic-light-step-2"></a>Traffic light - step 2</h3>
<p>The main ROOM model and the mapping model of this example is contained in <code>org.eclipse.etrice.examples.c/model/TrafficLight_step2</code>. It also contains launch configurations for the code generation, for launching the simulator GUI and for running the application.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>This example shows the control of a single block of traffic lights containing a car light and a light for the pedestrians. It illustrates how a stack of abstraction levels is used to conveniently divide the problem into relatively simple parts.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>The 4 levels of this application starts with a <code>TrafficLightHeadquarters</code> on the top. It controls the global operating mode of the traffic light block. The test harness <code>TrafficLightControllerTestHarness</code> is connected to both ports and drives the test in several steps.</p>
<p>On the next level we have a <code>PedestrianTrafficLightController</code> which offers some very general commands like <code>start</code>, <code>stop</code> and <code>standby</code>.</p>
<p>On the second level we find an actor <code>PTrafficLightInterface</code> that offers basic traffic light control in the form of switching the state of each single light separately.</p>
<p>On the base level we have an actor handling a TCP/IP socket connection with a general text protocol.</p>
<p>To run the test first generate the code using <code>gen_TrafficLight_step2.launch</code>, then compile and link it (using the CDTbuild). Since this step uses a GUI with a single block of lights you’ll have to launch the simulator using <code>run_simulator_1_block.launch</code>. Then you can just start the application using <code>run_TrafficLight_step2.launch</code>.</p>
<p>After going through a short initialization and standby phase the traffic light goes into a mode of permanent green for cars. After pressing the ’request’ button in the simulator GUI the light switches to red for cars and green for pedestrians and back to permanent green for cars.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>use abstraction levels to break a problem into smaller pieces.</li>
</ul>
<h3><a href="#traffic-light-step-3" name="traffic-light-step-3"></a>Traffic light - step 3</h3>
<p>The main ROOM model and the mapping model of this example is contained in <code>org.eclipse.etrice.examples.c/model/TrafficLight_step3</code>. It also contains launch configurations for the code generation, for launching the simulator GUI and for running the application.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>This example shows the control of two blocks of traffic lights each containing a car light and a light for the pedestrians. It uses a replicated stack of actors as introduced in step 2.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>The head quarters actor of this example controls two blocks of traffic lights. It already has a replicated port which is now connected to a doubled <code>PedestrianTrafficLightController</code>. Of course the replication then has also to be applied to the other levels of the stack introduced in step 2.</p>
<p>To run the test first generate the code using <code>gen_TrafficLight_step3.launch</code>, then compile and link it (using the CDTbuild). Since this step uses a GUI with a two blocks of lights you’ll have to launch the simulator using <code>run_simulator_2_blocks.launch</code>. Then you can just start the application using <code>run_TrafficLight_step3.launch</code>.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>use replication for multiple instances of the same.</li>
</ul>
<h3><a href="#traffic-light-step-4" name="traffic-light-step-4"></a>Traffic light - step 4</h3>
<p>The main ROOM model and the mapping model of this example is contained in <code>org.eclipse.etrice.examples.c/model/TrafficLight_step4</code>. It also contains launch configurations for the code generation, for launching the simulator GUI and for running the application.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>This example shows the control of two blocks of traffic lights each containing a car light and a light for the pedestrians. It uses a container actor for the three lower levels of the stack introduced in step 2. Then replication has to applied only to the container actor which simplifies the task.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>The head quarters actor of this example controls two blocks of traffic lights. It already has a replicated port which is now connected to a doubled <code>TrafficLightControllerWithInfrastructure</code>. The latter one</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>use hierarchy to group levels functionality to reusable blocks.</li>
</ul>
<h3><a href="#features" name="features"></a>Features</h3>
<p>This project illustrates the various ways how replication can be exploited in ROOM. Replication can be chosen for ports and for actor references. The example enumerates a number of typical combinations of the two possibilities.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>Five different ways to combine replicated ports and replicated actor references are shown in this example.</p>
<p>Each of these combination consists of one ore more receivers and one or more senders.</p>
<p>All five combinations are contained in the actor class <code>ExampleMultiplicity</code>.</p>
<ul>
<li>
<p><code>sender1</code> and <code>receiver1</code> - a single sender and a single receiver, both with plain ports, are connected.</p></li>
<li>
<p><code>multiSender2</code> with a replication factor of 10 is connected to <code>multiReceiver2</code> also with a replication factor of 10 - this is equivalent to 10 single senders each of which is connected to one single out of 10 receivers</p></li>
<li>
<p><code>multiSender3</code> with a replication factor of 2 is connected to <code>receiverMultiPort3</code> which has a port with replication factor 2</p></li>
<li>
<p><code>multiSender4</code> with a replication factor of 10 is connected to <code>multiReceiverMultiPort4</code> with a replicated port with cardinality 2 and replicated 5 times - this is equivalent to 5 receivers where each is connected to two senders</p></li>
<li>
<p><code>multiSender5</code> is connected to</p>
<ul>
<li>
<p><code>receiver5</code> which is a simple receiver not using any replication</p></li>
<li>
<p><code>multiReceiver5</code> which is a replicated receiver</p></li>
<li>
<p>`` which is not replicated but uses a replicated portreceiverMultiPort5</p></li>
<li>
<p><code>multiReceiverMultiPort5</code> which is replicated and has replicated ports</p></li>
</ul>
<p>So <code>multiSender5</code> is connected</p>
<ul>
<li>
<p>once to <code>receiver5</code></p></li>
<li>
<p>three times to <code>multiReceiver5</code></p></li>
<li>
<p>two times to <code>receiverMultiPort5</code> and</p></li>
<li>
<p>four times to <code>multiReceiverMultiPort5</code></p></li>
</ul>
<p>which totals to 10 (implicit) connections and matches the replication factor of 10 of <code>multiSender5</code>.</p>
</li>
</ul>
<h4><a href="#details" name="details"></a>Details</h4>
<p>The head quarters actor of this example controls two blocks of traffic lights. It already has a replicated port which is now connected to a doubled <code>TrafficLightControllerWithInfrastructure</code>. The latter one</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>use hierarchy to group levels of functionality to reusable blocks.</li>
</ul>
<h2><a href="#the-java-examples-project" name="the-java-examples-project"></a>The Java examples project</h2>
<p>The example project <code>org.eclipse.etrice.examples.java</code> currently contains a number of examples that are all related to dynamic actors.</p>
<p>The examples can be generated and executed one by one but not several at the same time. Inside the model folder there exists a sub folder for each example containing all models and launch configurations for code generation and to run the application.</p>
<h3><a href="#dynamic-actors-1" name="dynamic-actors-1"></a>Dynamic Actors 1</h3>
<p>This example is contained in <code>model/dynamicactors1</code>.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>The example demonstrates the usage of an optional actor. It is shown that several actor classes derived from the type of the optional actor reference can be optionally created in place of the optional actor reference. Optional actor instances can also be destroyed and another instance can be created in the free slot.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>The structure of this system is simple.</p>
<p><img src="images/039-DynAct1-Main_instanceTree.jpg" alt="image"></p>
<p>However, this is only the initial system structure. The leaf instance is just a place holder for an optional actor instance. In this place an instance of a compatible type can be created at run time. Compatible types are the type of the reference itself and all of its sub types as long as they are not abstract. Together with the instance all of its contained instances will be created and all ports are connected.</p>
<p>This example demonstrates how an optional actor is created and destroyed and another one of another type is created to hold the same place.</p>
<p><img src="images/039-DynAct1-Container_behavior.jpg" alt="image"></p>
<p>When the example is executed the <code>Container</code> actor first dumps the instance tree to the console (line 56 of the listing below). Then it creates an instance of <code>Optional2</code> (line 57). Now that the <code>p0</code> port of the container is connected a message <code>sayHello()</code> is sent to the newly created actor instance and the instance tree is dumped a second time. As soon as it receives the answer it prints it to the console. Then the optional actor is destroyed again and another one, now of type <code>Optional1</code>, is created and once more <code>sayHello()</code> is sent.</p>
<p>The console output of the running application starts with</p>
<pre><code>*** T H E B E G I N ***
*** MainComponent /LS/main::init ***
type 'quit' to exit
before creation of Optional2
LS
main
RTSystemPort
MessageService_MessageService_PhysicalThread1
Dispatcher
Queue
ActorClass(className=Appl, instancePath=/LS/main/appl)
port RTSystemPort
ActorClass(className=Container, instancePath=/LS/main/appl/cont)
port RTSystemPort
port p0
ScalarOptionalActorInterface(className=Optional, instancePath=/LS/main/appl/cont/opt)
RTSystemPort
port p0
port RTSystemPort0
port RTSystemPort1
</code></pre>
<p>The <code>ScalarOptionalActorInterface(className=Optional, instancePath=/LS/main/appl/cont/opt)</code> is an object which is responsible for the life cycle of the dynamic actor (including its contained instances) and for the mediation of the port connections. It contains a replicated <code>RTSystemPort</code> which is used to trigger the initial transition and the port <code>p0</code> of the interface of the <code>Optional</code> actor class.</p>
<p>After creation of <code>Optional2</code> the interesting part of the dumped tree is</p>
<pre><code>ScalarOptionalActorInterface(className=Optional, instancePath=/LS/main/appl/cont/opt)
RTSystemPort
port p0
ActorClass(className=Optional2, instancePath=/LS/main/appl/cont/opt/opt)
port RTSystemPort
ActorClass(className=AC2, instancePath=/LS/main/appl/cont/opt/opt/sub2)
port RTSystemPort
ActorClass(className=AC3, instancePath=/LS/main/appl/cont/opt/opt/sub2/deep_sub)
port RTSystemPort
port p0
port RTSystemPort0
port RTSystemPort1
port RTSystemPort2
</code></pre>
<p>It can be seen that the sub tree corresponding to <code>Optional2</code> was inserted right below the <code>ScalarOptionalActorInterface</code>.</p>
<p>After deletion of the optional actor the dumped instance tree looks exactly as in the beginning.</p>
<p>To illustrate the dynamic behavior of the system we can finally have a look at the generated sequence diagram [fig:dynact1_msc]. During the sub system initialization three actor instances are created. Then the system is started and the <code>Container</code> actor dynamically creates an instance of <code>Optional2</code>. This is indicated by the note on the life line of <code>/LS/main/appl/cont</code>. Then <code>sayHello()</code> is sent and the answer <code>hello()</code> is received and the optional actor is destroyed again.</p>
<p>The same is repeated with a new optional instance of <code>Optional1</code>.</p>
<p><img src="images/039-DynAct1-MSC.jpg" alt="Sequence diagram of Dynamic Actors Example 1"></p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>
<p>To obtain an executable the launch configuration <code>gen_DynAct1_sys.launch</code> has to be executed. In this case also the SubsystemClass <code>Node_nodeRef1_main</code> is generated as well as factory classes for the valid optional actors. If <code>Optional</code> were not <code>abstract</code> then also for this class a factory is created. However, in this class the relay port isn’t connected and a request <code>sayHello()</code> would be left without reply.</p></li>
<li>
<p>To generate a library the launch configuration <code>gen_DynAct1.launch</code> has to be executed. In this case no factory classes are generated.</p></li>
</ul>
<h3><a href="#dynamic-actors-2" name="dynamic-actors-2"></a>Dynamic Actors 2</h3>
<p>This example is contained in <code>model/dynamicactors2</code>.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>A modified version of <code>dynamicactors1</code> is used to analyze eventual memory leaks of the application.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>In this modified version creation and deletion of optional actors is looped. Each loop consists of 4 steps:</p>
<ol>
<li>
<p>create an instance of <code>Optional2</code></p></li>
<li>
<p>destroy the instance</p></li>
<li>
<p>create an instance of <code>Optional1</code></p></li>
<li>
<p>destroy the instance</p></li>
</ol>
<p>All together 600 steps are performed which corresponds to 300 creations and deletions.</p>
<p>The free memory is printed to the console. Also the overall execution time is measured. After the loop is finished the heap is analyzed using <code>JConsole</code> (which is a part of the Java6 distribution) to dump the heap and <a href="http://www.eclipse.org/mat/"><code>org.eclipse.mat</code></a> to analyze it.</p>
<p>The measured total execution time on a Intel Core 2 Duo at 2.66 GHz was 110 ms. This corresponds to about 370 (\mu)s.</p>
<p>The result of the heap analysis for <code>org.eclipse.etrice.*</code> objects is listed in figure [fig:dynact2_heap]. The small numbers per object and the retained heap size indicate that the application has no memory leak.</p>
<p><img src="images/039-DynAct2-HeapAnalysis.jpg" alt="Heap analysis after 600 steps"></p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>
<p>Calling the garbage collector every time before the free memory is dumped costs a significant amount of time and the execution time is increased to the order of seconds.</p></li>
<li>
<p>The measured free memory is close to constant. Only a small step is observed which wasn’t analyzed further.</p></li>
</ul>
<h3><a href="#dynamic-actors-3" name="dynamic-actors-3"></a>Dynamic Actors 3</h3>
<p>This example is contained in <code>model/dynamicactors3</code>.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>The example demonstrates the usage of an optional actor array. It is shown that several actor classes derived from the type of the optional actor reference can be created as array members. The array members can be destroyed in arbitrary order and the array size grows and shrinks as appropriate.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>This example again is similar to example 1. One difference is that the (scalar) optional actor is replaced by a replicated optional actor (or array of optional actors if you wish). The port of the <code>Container</code> was also changed to a replicated port. All replication factors in this example are of arbitrary multiplicity (*). The sizes vary dynamically and are unbound as far as the model is concerned.</p>
<p>The behavior was changed to the following: Two instances of different classes are created as members of this array and both are deleted and one is created again. The replicated port is used to send (broadcast) messages to the optional actors.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>
<p>the generated MSC <code>main_Async.seq</code> is a good illustration of the dynamic changes in the system structure</p></li>
<li>
<p>careful inspection of the console output reveals that objects are created and destroyed as expected</p></li>
</ul>
<h3><a href="#dynamic-actors-4" name="dynamic-actors-4"></a>Dynamic Actors 4</h3>
<p>This example is contained in <code>model/dynamicactors4</code>.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>The example demonstrates the usage of an optional actor. But here not the actor containing the optional reference is communicating with the optional actor but one level above.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>The <code>Controller</code> which has a reference to the <code>Container</code> is asking the latter for the creation of the dynamic actor. When it receives <code>ok()</code> it is requesting <code>sayHello()</code> from the newly created actor.</p>
<p>After the <code>Controller</code> receives <code>hello()</code> it tells the <code>Container</code> to create another actor which fails because the old one is still in place.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>the generated MSC <code>main_Async.seq</code> is a good illustration of the dynamic changes in the system structure</li>
</ul>
<h3><a href="#dynamic-actors-5" name="dynamic-actors-5"></a>Dynamic Actors 5</h3>
<p>This example is contained in <code>model/dynamicactors5</code>.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>The example shows that the optional actor can not only have relay ports but also external end ports.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>This simple example just shows that the optional actor may directly handle inbound messages by using an external end port rather than the relay port of the previous examples.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>the generated MSC <code>main_Async.seq</code> is a good illustration of the dynamic changes in the system structure</li>
</ul>
<h3><a href="#dynamic-actors-6" name="dynamic-actors-6"></a>Dynamic Actors 6</h3>
<p>This example is contained in <code>model/dynamicactors6</code>.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>The example demonstrates the use of nested dynamic actors.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>In this example the dynamically created actor <code>Optional2</code> has again an optional reference two levels down in its hierarchy. On creation it immediately creates a nested dynamic actor of class <code>Optional1</code> which is sending <code>hello()</code> back to the outer <code>Container</code>.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>
<p>the generated MSC <code>main_Async.seq</code> is a good illustration of the dynamic changes in the system structure</p></li>
<li>
<p>when a dynamic actor is created its structure is there immediately and all ports are connected. But the initial transition is executed asynchronously. So after the outer dynamic actor is created the port of the <code>Container</code> is not yet connected because the initial transition which is responsible for the creation of the inner dynamic actor wasn’t executed yet. So a message sent from this port directly after creation of the outer dynamic actor would get lost.</p></li>
</ul>
<h3><a href="#dynamic-actors-7" name="dynamic-actors-7"></a>Dynamic Actors 7</h3>
<p>This example is contained in <code>model/dynamicactors7</code>.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>The example demonstrates the use of communication between two optional actors.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>In this example two sub trees of dynamic actors are created. The container is sending a message to one of them which is forwarding it to the other one which in turn is replying back to the container.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>the generated MSC <code>main_Async.seq</code> is a good illustration of the dynamic changes in the system structure</li>
</ul>
<h3><a href="#dynamic-actors-8" name="dynamic-actors-8"></a>Dynamic Actors 8</h3>
<p>This example is contained in <code>model/dynamicactors8</code>.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>The example demonstrates the use of the persistence interface for dynamic actors.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>Dynamic actors can be persisted and restored. To this end the user has to pass an <code>java.io.ObjectOutput</code> to the creation method (<code>createOptionalActor()</code>) and an <code>java.io.ObjectInput</code> to the deletion method (<code>destroyOptionalActor()</code>).</p>
<p>The code generation has to be invoked with the <code>-persistable</code> (e.g. by setting the ’generate persistence interface’ flag in the Java Generator tab of the launch configuration). This lets the generator implement the <code>IPersistable</code> interface for actor classes.</p>
<p>The example adds a manually coded very simple <code>FilePersistor</code> with four static methods for creation and deletion of scalar and replicated dynamic actors.</p>
<p>The <code>Container</code> class first creates an optional actor of type <code>Optional1</code> in the scalar reference <code>opt</code>. Then messages are sent to this actor instance which lead to some state changes. Finally it is saved and destroyed. Now another actor class is instantiated in the same actor reference and also destroyed. Then the first instance is loaded from file. It directly starts in the state it had when it was saved. The second part of the example loads copies of the two instances created in the beginning into the <code>optarr</code> reference.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li>the generated MSC <code>main_Async.seq</code> is a good illustration of the dynamic changes in the system structure</li>
</ul>
<h3><a href="#dynamic-actors-9" name="dynamic-actors-9"></a>Dynamic Actors 9</h3>
<p>This example is contained in <code>model/dynamicactors9</code>.</p>
<h4><a href="#purpose" name="purpose"></a>Purpose</h4>
<p>The example demonstrates the use of SAPs in dynamic actors.</p>
<h4><a href="#details" name="details"></a>Details</h4>
<p>This simple example re-uses the PingPong tutorial. The static part of the system introduces a <code>TimingService</code> as SPP and the <code>Receiver</code> embedded in the optional part uses a SAP of this protocol.</p>
<p>The sub system during initialization adds broker ports to the optional actor interface that are connected to all available services.</p>
<p>On the other hand the factory for the optional actor maps SAPs to those broker ports.</p>
<h4><a href="#noteworthy" name="noteworthy"></a>Noteworthy</h4>
<ul>
<li><em>Caution:</em> currently the generator informs about unsatisfied services in dynamic actors. But it is still possible to create such an instance. The consequence is an unbound SAP</li>
</ul>
<hr>
<p><a href="#navbar">back to top</a> <span class="version pull-right">version 3.x</span></p>
</div>
</div>
</div>
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<!-- Include all compiled plugins (below), or include individual files as needed -->
<script src="js/bootstrap.min.js"></script>
<script src="js/metisMenu.min.js"></script>
<script src="js/prettify.js"></script>
<script src="js/custom.js"></script>
</body>
</html>