summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorThomas Jung2011-08-18 10:36:36 (EDT)
committerThomas Jung2011-08-18 10:36:36 (EDT)
commit56bd1f2aa6ef579679477833c02ab5b3fdaaaacc (patch)
tree6a8a97a77743e993db25f036b9a4628d3f053a1f
parent265c705007fd8628f89734095b026a9f4411d10d (diff)
downloadorg.eclipse.etrice-56bd1f2aa6ef579679477833c02ab5b3fdaaaacc.zip
org.eclipse.etrice-56bd1f2aa6ef579679477833c02ab5b3fdaaaacc.tar.gz
org.eclipse.etrice-56bd1f2aa6ef579679477833c02ab5b3fdaaaacc.tar.bz2
[doc] all documentation generated generated
-rw-r--r--plugins/org.eclipse.etrice.doc/build/etrice.textile73
-rw-r--r--plugins/org.eclipse.etrice.doc/build/etrice.xml87
-rw-r--r--plugins/org.eclipse.etrice.doc/help/BasicConcepts.html69
-rw-r--r--plugins/org.eclipse.etrice.doc/help/ExecutionModels.html3
-rw-r--r--plugins/org.eclipse.etrice.doc/help/ImplementtheBehavior.html3
-rw-r--r--plugins/org.eclipse.etrice.doc/help/IntroductiontotheROOMLanguage.html33
-rw-r--r--plugins/org.eclipse.etrice.doc/help/Summary3.html14
-rw-r--r--plugins/org.eclipse.etrice.doc/help/TutorialHelloWorld.html5
-rw-r--r--plugins/org.eclipse.etrice.doc/html/etrice.html127
-rw-r--r--plugins/org.eclipse.etrice.doc/manual/etrice.pdfbin2999868 -> 3057208 bytes
-rw-r--r--plugins/org.eclipse.etrice.doc/toc.xml7
11 files changed, 367 insertions, 54 deletions
diff --git a/plugins/org.eclipse.etrice.doc/build/etrice.textile b/plugins/org.eclipse.etrice.doc/build/etrice.textile
index 9788faf..1437d13 100644
--- a/plugins/org.eclipse.etrice.doc/build/etrice.textile
+++ b/plugins/org.eclipse.etrice.doc/build/etrice.textile
@@ -33,7 +33,7 @@ This chapter will give a rough overview of what ROOM (*R* eal time *O* bject *O*
h3. Where does it come from?
-Room was developed in the 1990th on the background of the upcoming mobile applications with the goal to manage the complexity of such huge SW-Systems. From the very beginning ROOM has focused on a certain type of SW-Systems and, is in contrast to the UML, well suited for this kind of systems. In this sense, ROOM is a DSL (Domain Specific Language) for distributed, event driven, real time systems.
+Room was developed in the 1990th on the background of the upcoming mobile applications with the goal to manage the complexity of such huge SW-Systems. From the very beginning ROOM has focused on a certain type of SW-Systems and, is in contrast to the UML, well suited for this kind of systems. In this sense, ROOM is a DSL (Domain Specific Language) for distributed, event driven, real time systems.
Bran Selic, Garth Gullekson and Paul T. Ward have published the concepts 1994 in the book "REAL-TIME OBJECT-ORIENTED MODELING". The company ??object time?? (TM) developed a ROOM tool which was taken over from ??Rational SW?? (TM) and later on from ??IBM?? (TM). Unfortunately the tool is no longer maintained from ??IBM?? (TM). The company ??Protos SW Gmbh?? (TM) also developed a ROOM tool called ??trice?? (TM) for controlling production machines. ??Trice?? (TM) is the predecessor of eTrice (see Introduction to eTrice).
@@ -56,7 +56,7 @@ As an example take a look at a washing machine. The system has to react on user
So, the system can by characterized as timeliness, concurrent and reactive. As long as the washing machine does not transform to a laundry dryer by themself, the system has no dynamic internal structure and as long as all functions are running on a single microcontroller the (SW)-system is not distributed.
ROOM fits perfect to such a system.
-A SW system which mainly consists of transformations like signal processing or image processing (pure algorithms) cannot be characterized with any of the above mentioned properties. However, in the real world most of the SW systems will be a combination of both. ROOM can be mixed up with non model code.
+A SW system which mainly consists of data transformations like signal/image processing or loop controller (PID regulator) cannot be characterized with any of the above mentioned properties. However, in the real world most of the SW systems will be a combination of both. ROOM can be combined with such systems, so that for example an actor provides a ??run to completion?? context for calculating a image processing algorithm.
h3. What is the relation between OOP and ROOM?
@@ -64,11 +64,11 @@ The relation between classic object oriented programming and ROOM is comparable
!images/010-RoomIntroduction01.png!
-As the figure illustrates, the classic object paradigm does not care about concurrency issues. The threads of control will be provided from the underlying operating system.
+As the figure illustrates, the classic object paradigm does not care about concurrency issues. The threads of control will be provided from the underlying operating system and the user is responsible to avoid access violations by using operating system mechanisms (semaphore, mutex).
!images/010-RoomIntroduction02.png!
-ROOM provides the concept of a logical machine (called actor) with it´s own thread of control. It provides some kind of cooperative communication infrastructure with "run to completion" semantic. That makes developing of business logic easy and save (see basic concepts).
+ROOM provides the concept of a logical machine (called actor) with it´s own thread of control. It provides some kind of cooperative communication infrastructure with "run to completion" semantic. That makes developing of business logic easy and save (see basic concepts). The logical machine provides an encapsulation shell including concurrency issues (see chapter "Run to completion").
!images/010-RoomIntroduction03.png!
@@ -76,11 +76,13 @@ This thinking of an object is much more general than the classic one.
h3. What are the benefits of ROOM?
-The main benefits are:
-- ROOM provides model execution, which makes it easy to find defects early enough, to reduce expensive debugging during the testing phase or even in the costumer environment.
-- ROOM promotes component building which is essential to make SW reusable
-- Graphical modeling makes it easy to understand, maintain and share code with other developers
-- higher abstraction in combination with automated code generation provides very efficient mechanisms to the developer.
+ROOM has a lot of benefits and it depends on the users point of view which is the most important one. From a general point of view the most important benefit is, that ROOM allows to create SW systems very efficient, robust and safe due to the fact that it provides some abstract, high level modeling concepts combined with code generation and a small efficient runtime environment.
+
+In detail:
+* ROOM models contain well defined interfaces (protocols). That makes it easy to reuse components in different applications or e.g. in a test harness.
+* Graphical modeling makes it easy to understand, maintain and share code with other developers
+* Higher abstraction in combination with automated code generation provides very efficient mechanisms to the developer.
+* ROOM provides graphical model execution, which makes it easy to understand the application or find defects in a very early phase.
h3. Which consequences must be taken into account?
@@ -90,10 +92,44 @@ Care must be taken during introduction of the new methodology. Due to the fact t
h2. Basic Concepts
-port, protocol, actor, interface, asynchronous communication
-hierarchical FSM, hierarchical structure
+h3. Actor, Port, Protocol
+
+The basic elements of ROOM are the actor with its ports and protocols. The protocol provides a formal interface description. The port is an interaction point where the actor interacts with its outside world. Each port has exactly one protocol attached. The sum of all ports builds up the complete interface of an actor. Each port can receive messages with or without data which is defined in the protocol. Each message will be handled from the actors behavior (state machine) or will be delegated to the actors internal structure.
+
+The actor provides access protection for it´s own attributes (including complex types (classic objects)), including concurrency protection. An actor has neither public attributes nor public operations. The only interaction with the outside world takes place via interface ports. This ensures a high degree of reuse ability on actor level and provides an effective and safe programming model to the developer.
+
+Receiving a message via a port will trigger the internal state machine. A transition will be executed depending on the message and the actual state. Within this transition, detailed code will be executed and response messages can be sent.
+
+"receiving a message":images\010-room-introduction01.avi
+
+With this model, a complex behavior will be divided into many relatively simple, linked actors. To say it the other way round: The complex behavior will be provided by a network of relatively simple components which are communicating with each other via well defined interfaces.
+
+
+h3. Hierarchy in Structure and FSM
+
+ROOM provides two types of hierarchy. Behavioral hierarchy and structural hierarchy. Structural hierarchy means that actors can be nested to any level. Usually you will add more and more details to your application with each nesting level. That means you can focus yourself on any level of abstraction with always the same element, the actor. Structural hierarchy provides a power full mechanism to divide your problem in smaller pieces, so that you can focus the level of abstraction you want to work on.
+
+The actors behavior will be described with a state machine. The states itself may contain sub states. This is also a possibility to focus on an abstraction level. Take the simple FSM from the blinky actor from the blinky tutorial:
+
+!images\020-Blinky15.png!
+From an abstract point of view there is a state "blinking". But a simple LED is not able to blink autonomously. Therefore you have to add more details to your model to make a LED blinking, but for the current work it is not of interest how blinking is realized. This will be done in the next lower level of the hierarchy.
+With this very simple example you can easily imagine how power full this mechanisms is.
+
+The hierarchical FSM provides a rich tool box to describe real world problems. (see "room concepts").
+
+h3. Run to Completion
+
+"Run to completion" (RTC) is a very central concept of ROOM. It enables the developer to concentrate on the functional aspects of the system. The developer must not take care about concurrency issues all the time. This job is concentrated to the system designer in a very flexible way.
+What does "run to completion" mean:
+RTC means that an actor, which is processing a message, can not be receive the next message as long as the processing of the current message has not been finished. Receiving of the next message will be queued from the underlying run time system.
+
+Note: It is very important not to confuse run to completion and preemption. Run to completion means that an actor will finish the processing of a message before he can receive a new one (regardless of its priority). That does not mean that an actor cannot be preempted from an higher prior thread of control. Even a message from this higher prior thread of control will be queued till the current processing has been finished.
+
+With this mechanism all actor internal attributes and data structures are protected. Due to the fact that multiple actors share one thread of control, all objects are protected which are accessed from one thread of control but multiple actors. This provides the possibility to decompose complex functionality to several actors without the risk to produce access violations.
+
+h3. Layering
h2. Benefits
@@ -111,6 +147,10 @@ not implemented yet
h3. Hybrid Execution Model
not implemented yet
+port, protocol, actor, interface, asynchronous communication
+hierarchical FSM, hierarchical structure
+
+run to completion
h1. Tutorial HelloWorld
@@ -125,6 +165,8 @@ In this tutorial you will build your first very simple eTrice model. The goal is
# run the model
# open the message sequence chart
+"video":images\015-HelloWorld01.avi
+
h2. Create a new model from scratch
The easiest way to create a new eTrice Project is to use the eclipse project wizard. From the eclipse file menu select ??File->New->Project?? and create a new eTrice project and name it ??HelloWorld??
@@ -395,6 +437,7 @@ Navigate to the Top level state by double clicking the ??/blinking?? state. Crea
!images/020-Blinky15.PNG!
The trigger event from ??off?? to ??blinking?? is the ??start?? event from the ??ControlPort??.The trigger event from ??blinking?? to ??off?? is the ??stop?? event from the ??ControlPort??.
+Note: The transition from ??blinking?? to ??off?? is a so called group transition. This is a outgoing transition from a super state (state with sub states) without specifying the concrete leave state (state without sub states). An incoming transition to a super state is called history transition.
Action code of the init transition is:
@@ -683,10 +726,12 @@ h2. Summary
Within the first loop an integer value will be incremented from ??MrPong?? and sent back to ??MrPing??. As long as the guard is true ??MrPing?? sends back the value.
-Within the ??next?? transition, ??MrPing?? creates a data class and sends the default values. Than ??MrPing?? changes the values and sends the class again. At this point you should note that during the send operation, a copy of the data class will be created and sent. Otherwise it would not be possible to send the same object two times, even more it would not be possible to send a stack object at all.
-In future versions of eTrice an additional mechanism to send references will be implemented. However, keep in mind that sending references transfers the responsibility of the life cycle of the sent object to the user. It looks simple but is a very common source of failures.
-
+Within the ??next?? transition, ??MrPing?? creates a data class and sends the default values. Than ??MrPing?? changes the values and sends the class again. At this point you should note that during the send operation, a copy of the data class will be created and sent. Otherwise it would not be possible to send the same object two times, even more it would not be possible to send a stack object at all.
+However, for performance reasons some applications requires sending data by value. In this case the user is responsible for the life cycle of the object. In Java the VM takes care about the life cycle of an object. This is not the case for C/C++. Consider that a object which is created within a transition of a state machine will be destroyed when the transition is finished. The receiving FSM would receive an invalid reference. Therefore care must be taken by sending references.
+For sending data by reference you simply have to add the keyword ??ref?? to the protocol definition.
+
+bc. Message ping(data: DemoData ref)
h1. Tutorial Pedestrian Lights
diff --git a/plugins/org.eclipse.etrice.doc/build/etrice.xml b/plugins/org.eclipse.etrice.doc/build/etrice.xml
index db70564..61268f1 100644
--- a/plugins/org.eclipse.etrice.doc/build/etrice.xml
+++ b/plugins/org.eclipse.etrice.doc/build/etrice.xml
@@ -51,7 +51,7 @@
</itemizedlist>
<section id="Wheredoesitcomefrom">
<title>Where does it come from?</title>
- <para>Room was developed in the 1990th on the background of the upcoming mobile applications with the goal to manage the complexity of such huge SW-Systems. From the very beginning ROOM has focused on a certain type of SW-Systems and, is in contrast to the UML, well suited for this kind of systems. In this sense, ROOM is a DSL (Domain Specific Language) for distributed, event driven, real time systems. </para>
+ <para>Room was developed in the 1990th on the background of the upcoming mobile applications with the goal to manage the complexity of such huge SW-Systems. From the very beginning ROOM has focused on a certain type of SW-Systems and, is in contrast to the UML, well suited for this kind of systems. In this sense, ROOM is a DSL (Domain Specific Language) for distributed, event driven, real time systems. </para>
<para>Bran Selic, Garth Gullekson and Paul T. Ward have published the concepts 1994 in the book &#8222;REAL-TIME OBJECT-ORIENTED MODELING”. The company
<citation>object time</citation> &#8482; developed a ROOM tool which was taken over from
<citation>Rational SW</citation> &#8482; and later on from
@@ -90,7 +90,9 @@
<para>As an example take a look at a washing machine. The system has to react on user interactions, has to handle some error conditions like a closed water tap or a defective lye pump. It has to react simultaneously to all this inputs. It has to close the water valve in a certain time to avoid flooding the basement.
So, the system can by characterized as timeliness, concurrent and reactive. As long as the washing machine does not transform to a laundry dryer by themself, the system has no dynamic internal structure and as long as all functions are running on a single microcontroller the (SW)-system is not distributed.
ROOM fits perfect to such a system.</para>
- <para>A SW system which mainly consists of transformations like signal processing or image processing (pure algorithms) cannot be characterized with any of the above mentioned properties. However, in the real world most of the SW systems will be a combination of both. ROOM can be mixed up with non model code. </para>
+ <para>A SW system which mainly consists of data transformations like signal/image processing or loop controller (PID regulator) cannot be characterized with any of the above mentioned properties. However, in the real world most of the SW systems will be a combination of both. ROOM can be combined with such systems, so that for example an actor provides a
+ <citation>run to completion</citation> context for calculating a image processing algorithm.
+ </para>
</section>
<section id="WhatistherelationbetweenOOPandROOM">
<title>What is the relation between OOP and ROOM?</title>
@@ -102,7 +104,7 @@
</imageobject>
</mediaobject>
</para>
- <para>As the figure illustrates, the classic object paradigm does not care about concurrency issues. The threads of control will be provided from the underlying operating system.</para>
+ <para>As the figure illustrates, the classic object paradigm does not care about concurrency issues. The threads of control will be provided from the underlying operating system and the user is responsible to avoid access violations by using operating system mechanisms (semaphore, mutex).</para>
<para>
<mediaobject>
<imageobject>
@@ -110,7 +112,7 @@
</imageobject>
</mediaobject>
</para>
- <para>ROOM provides the concept of a logical machine (called actor) with it´s own thread of control. It provides some kind of cooperative communication infrastructure with &#8222;run to completion” semantic. That makes developing of business logic easy and save (see basic concepts). </para>
+ <para>ROOM provides the concept of a logical machine (called actor) with it´s own thread of control. It provides some kind of cooperative communication infrastructure with &#8222;run to completion” semantic. That makes developing of business logic easy and save (see basic concepts). The logical machine provides an encapsulation shell including concurrency issues (see chapter &#8222;Run to completion”). </para>
<para>
<mediaobject>
<imageobject>
@@ -122,11 +124,22 @@
</section>
<section id="WhatarethebenefitsofROOM">
<title>What are the benefits of ROOM?</title>
- <para>The main benefits are:
- - ROOM provides model execution, which makes it easy to find defects early enough, to reduce expensive debugging during the testing phase or even in the costumer environment.
- - ROOM promotes component building which is essential to make SW reusable
- - Graphical modeling makes it easy to understand, maintain and share code with other developers
- - higher abstraction in combination with automated code generation provides very efficient mechanisms to the developer. </para>
+ <para>ROOM has a lot of benefits and it depends on the users point of view which is the most important one. From a general point of view the most important benefit is, that ROOM allows to create SW systems very efficient, robust and safe due to the fact that it provides some abstract, high level modeling concepts combined with code generation and a small efficient runtime environment. </para>
+ <para>In detail:</para>
+ <itemizedlist>
+ <listitem>
+ <para>ROOM models contain well defined interfaces (protocols). That makes it easy to reuse components in different applications or e.g. in a test harness. </para>
+ </listitem>
+ <listitem>
+ <para>Graphical modeling makes it easy to understand, maintain and share code with other developers</para>
+ </listitem>
+ <listitem>
+ <para>Higher abstraction in combination with automated code generation provides very efficient mechanisms to the developer. </para>
+ </listitem>
+ <listitem>
+ <para>ROOM provides graphical model execution, which makes it easy to understand the application or find defects in a very early phase. </para>
+ </listitem>
+ </itemizedlist>
</section>
<section id="Whichconsequencesmustbetakenintoaccount">
<title>Which consequences must be taken into account?</title>
@@ -136,8 +149,42 @@
</section>
<section id="BasicConcepts">
<title>Basic Concepts</title>
- <para>port, protocol, actor, interface, asynchronous communication
- hierarchical FSM, hierarchical structure</para>
+ <section id="ActorPortProtocol">
+ <title>Actor, Port, Protocol</title>
+ <para>The basic elements of ROOM are the actor with its ports and protocols. The protocol provides a formal interface description. The port is an interaction point where the actor interacts with its outside world. Each port has exactly one protocol attached. The sum of all ports builds up the complete interface of an actor. Each port can receive messages with or without data which is defined in the protocol. Each message will be handled from the actors behavior (state machine) or will be delegated to the actors internal structure.</para>
+ <para>The actor provides access protection for it´s own attributes (including complex types (classic objects)), including concurrency protection. An actor has neither public attributes nor public operations. The only interaction with the outside world takes place via interface ports. This ensures a high degree of reuse ability on actor level and provides an effective and safe programming model to the developer. </para>
+ <para>Receiving a message via a port will trigger the internal state machine. A transition will be executed depending on the message and the actual state. Within this transition, detailed code will be executed and response messages can be sent.</para>
+ <para>
+ <ulink url="images\010-room-introduction01.avi">receiving a message</ulink>
+ </para>
+ <para>With this model, a complex behavior will be divided into many relatively simple, linked actors. To say it the other way round: The complex behavior will be provided by a network of relatively simple components which are communicating with each other via well defined interfaces.</para>
+ </section>
+ <section id="HierarchyinStructureandFSM">
+ <title>Hierarchy in Structure and FSM</title>
+ <para>ROOM provides two types of hierarchy. Behavioral hierarchy and structural hierarchy. Structural hierarchy means that actors can be nested to any level. Usually you will add more and more details to your application with each nesting level. That means you can focus yourself on any level of abstraction with always the same element, the actor. Structural hierarchy provides a power full mechanism to divide your problem in smaller pieces, so that you can focus the level of abstraction you want to work on. </para>
+ <para>The actors behavior will be described with a state machine. The states itself may contain sub states. This is also a possibility to focus on an abstraction level. Take the simple FSM from the blinky actor from the blinky tutorial: </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images\020-Blinky15.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>From an abstract point of view there is a state &#8222;blinking”. But a simple LED is not able to blink autonomously. Therefore you have to add more details to your model to make a LED blinking, but for the current work it is not of interest how blinking is realized. This will be done in the next lower level of the hierarchy. </para>
+ <para>With this very simple example you can easily imagine how power full this mechanisms is.</para>
+ <para>The hierarchical FSM provides a rich tool box to describe real world problems. (see &#8222;room concepts”).</para>
+ </section>
+ <section id="RuntoCompletion">
+ <title>Run to Completion</title>
+ <para>&#8222;Run to completion” (RTC) is a very central concept of ROOM. It enables the developer to concentrate on the functional aspects of the system. The developer must not take care about concurrency issues all the time. This job is concentrated to the system designer in a very flexible way.
+ What does &#8222;run to completion” mean:
+ RTC means that an actor, which is processing a message, can not be receive the next message as long as the processing of the current message has not been finished. Receiving of the next message will be queued from the underlying run time system.</para>
+ <para>Note: It is very important not to confuse run to completion and preemption. Run to completion means that an actor will finish the processing of a message before he can receive a new one (regardless of its priority). That does not mean that an actor cannot be preempted from an higher prior thread of control. Even a message from this higher prior thread of control will be queued till the current processing has been finished. </para>
+ <para>With this mechanism all actor internal attributes and data structures are protected. Due to the fact that multiple actors share one thread of control, all objects are protected which are accessed from one thread of control but multiple actors. This provides the possibility to decompose complex functionality to several actors without the risk to produce access violations.</para>
+ </section>
+ <section id="Layering">
+ <title>Layering</title>
+ </section>
</section>
<section id="Benefits">
<title>Benefits</title>
@@ -162,6 +209,9 @@
<section id="HybridExecutionModel">
<title>Hybrid Execution Model
not implemented yet</title>
+ <para>port, protocol, actor, interface, asynchronous communication
+ hierarchical FSM, hierarchical structure</para>
+ <para>run to completion</para>
</section>
</section>
</chapter>
@@ -187,6 +237,9 @@
<para>open the message sequence chart</para>
</listitem>
</orderedlist>
+ <para>
+ <ulink url="images\015-HelloWorld01.avi">video</ulink>
+ </para>
</section>
<section id="Createanewmodelfromscratch">
<title>Create a new model from scratch</title>
@@ -741,6 +794,9 @@ carLights.setState(TrafficLight3.OFF);
<citation>off</citation> is the
<citation>stop</citation> event from the
<citation>ControlPort</citation>.
+ Note: The transition from
+ <citation>blinking</citation> to
+ <citation>off</citation> is a so called group transition. This is a outgoing transition from a super state (state with sub states) without specifying the concrete leave state (state without sub states). An incoming transition to a super state is called history transition.
</para>
<para>Action code of the init transition is:</para>
<literallayout><code>carLights = light.getCarLights();
@@ -1146,9 +1202,14 @@ carLights.setState(TrafficLight3.OFF);
<para>Within the
<citation>next</citation> transition,
<citation>MrPing</citation> creates a data class and sends the default values. Than
- <citation>MrPing</citation> changes the values and sends the class again. At this point you should note that during the send operation, a copy of the data class will be created and sent. Otherwise it would not be possible to send the same object two times, even more it would not be possible to send a stack object at all.
- In future versions of eTrice an additional mechanism to send references will be implemented. However, keep in mind that sending references transfers the responsibility of the life cycle of the sent object to the user. It looks simple but is a very common source of failures.
+ <citation>MrPing</citation> changes the values and sends the class again. At this point you should note that during the send operation, a copy of the data class will be created and sent. Otherwise it would not be possible to send the same object two times, even more it would not be possible to send a stack object at all.
+ However, for performance reasons some applications requires sending data by value. In this case the user is responsible for the life cycle of the object. In Java the VM takes care about the life cycle of an object. This is not the case for C/C++. Consider that a object which is created within a transition of a state machine will be destroyed when the transition is finished. The receiving FSM would receive an invalid reference. Therefore care must be taken by sending references.
+ </para>
+ <para>For sending data by reference you simply have to add the keyword
+ <citation>ref</citation> to the protocol definition.
</para>
+ <literallayout><code>Message ping(data: DemoData ref)
+</code></literallayout>
</section>
</chapter>
<chapter id="TutorialPedestrianLights">
diff --git a/plugins/org.eclipse.etrice.doc/help/BasicConcepts.html b/plugins/org.eclipse.etrice.doc/help/BasicConcepts.html
index 5baf858..223ffb9 100644
--- a/plugins/org.eclipse.etrice.doc/help/BasicConcepts.html
+++ b/plugins/org.eclipse.etrice.doc/help/BasicConcepts.html
@@ -20,8 +20,73 @@
</div>
</div>
</div>
-<p>port, protocol, actor, interface, asynchronous communication
- hierarchical FSM, hierarchical structure</p>
+<div class="section" title="Actor, Port, Protocol">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="ActorPortProtocol"></a>Actor, Port, Protocol</h3>
+</div>
+</div>
+</div>
+<p>The basic elements of ROOM are the actor with its ports and protocols. The protocol provides a formal interface description. The port is an interaction point where the actor interacts with its outside world. Each port has exactly one protocol attached. The sum of all ports builds up the complete interface of an actor. Each port can receive messages with or without data which is defined in the protocol. Each message will be handled from the actors behavior (state machine) or will be delegated to the actors internal structure.</p>
+<p>The actor provides access protection for it&acute;s own attributes (including complex types (classic objects)), including concurrency protection. An actor has neither public attributes nor public operations. The only interaction with the outside world takes place via interface ports. This ensures a high degree of reuse ability on actor level and provides an effective and safe programming model to the developer. </p>
+<p>Receiving a message via a port will trigger the internal state machine. A transition will be executed depending on the message and the actual state. Within this transition, detailed code will be executed and response messages can be sent.</p>
+<p>
+
+<a class="ulink" href="images\010-room-introduction01.avi" target="_new">receiving a message</a>
+
+</p>
+<p>With this model, a complex behavior will be divided into many relatively simple, linked actors. To say it the other way round: The complex behavior will be provided by a network of relatively simple components which are communicating with each other via well defined interfaces.</p>
+</div>
+<div class="section" title="Hierarchy in Structure and FSM">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="HierarchyinStructureandFSM"></a>Hierarchy in Structure and FSM</h3>
+</div>
+</div>
+</div>
+<p>ROOM provides two types of hierarchy. Behavioral hierarchy and structural hierarchy. Structural hierarchy means that actors can be nested to any level. Usually you will add more and more details to your application with each nesting level. That means you can focus yourself on any level of abstraction with always the same element, the actor. Structural hierarchy provides a power full mechanism to divide your problem in smaller pieces, so that you can focus the level of abstraction you want to work on. </p>
+<p>The actors behavior will be described with a state machine. The states itself may contain sub states. This is also a possibility to focus on an abstraction level. Take the simple FSM from the blinky actor from the blinky tutorial: </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images\020-Blinky15.png"></div>
+<p>
+
+</p>
+<p>From an abstract point of view there is a state &bdquo;blinking&rdquo;. But a simple LED is not able to blink autonomously. Therefore you have to add more details to your model to make a LED blinking, but for the current work it is not of interest how blinking is realized. This will be done in the next lower level of the hierarchy. </p>
+<p>With this very simple example you can easily imagine how power full this mechanisms is.</p>
+<p>The hierarchical FSM provides a rich tool box to describe real world problems. (see &bdquo;room concepts&rdquo;).</p>
+</div>
+<div class="section" title="Run to Completion">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="RuntoCompletion"></a>Run to Completion</h3>
+</div>
+</div>
+</div>
+<p>&bdquo;Run to completion&rdquo; (RTC) is a very central concept of ROOM. It enables the developer to concentrate on the functional aspects of the system. The developer must not take care about concurrency issues all the time. This job is concentrated to the system designer in a very flexible way.
+ What does &bdquo;run to completion&rdquo; mean:
+ RTC means that an actor, which is processing a message, can not be receive the next message as long as the processing of the current message has not been finished. Receiving of the next message will be queued from the underlying run time system.</p>
+<p>Note: It is very important not to confuse run to completion and preemption. Run to completion means that an actor will finish the processing of a message before he can receive a new one (regardless of its priority). That does not mean that an actor cannot be preempted from an higher prior thread of control. Even a message from this higher prior thread of control will be queued till the current processing has been finished. </p>
+<p>With this mechanism all actor internal attributes and data structures are protected. Due to the fact that multiple actors share one thread of control, all objects are protected which are accessed from one thread of control but multiple actors. This provides the possibility to decompose complex functionality to several actors without the risk to produce access violations.</p>
+</div>
+<div class="section" title="Layering">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="Layering"></a>Layering</h3>
+</div>
+</div>
+</div>
+</div>
</div>
</body>
</html>
diff --git a/plugins/org.eclipse.etrice.doc/help/ExecutionModels.html b/plugins/org.eclipse.etrice.doc/help/ExecutionModels.html
index ca458d4..d3ff458 100644
--- a/plugins/org.eclipse.etrice.doc/help/ExecutionModels.html
+++ b/plugins/org.eclipse.etrice.doc/help/ExecutionModels.html
@@ -68,6 +68,9 @@
</div>
</div>
</div>
+<p>port, protocol, actor, interface, asynchronous communication
+ hierarchical FSM, hierarchical structure</p>
+<p>run to completion</p>
</div>
</div>
</body>
diff --git a/plugins/org.eclipse.etrice.doc/help/ImplementtheBehavior.html b/plugins/org.eclipse.etrice.doc/help/ImplementtheBehavior.html
index f7fd951..a508f31 100644
--- a/plugins/org.eclipse.etrice.doc/help/ImplementtheBehavior.html
+++ b/plugins/org.eclipse.etrice.doc/help/ImplementtheBehavior.html
@@ -194,6 +194,9 @@ carLights.setState(TrafficLight3.OFF);<br>
[<span class="citation">off</span>] is the
[<span class="citation">stop</span>] event from the
[<span class="citation">ControlPort</span>].
+ Note: The transition from
+ [<span class="citation">blinking</span>] to
+ [<span class="citation">off</span>] is a so called group transition. This is a outgoing transition from a super state (state with sub states) without specifying the concrete leave state (state without sub states). An incoming transition to a super state is called history transition.
</p>
<p>Action code of the init transition is:</p>
<div class="literallayout">
diff --git a/plugins/org.eclipse.etrice.doc/help/IntroductiontotheROOMLanguage.html b/plugins/org.eclipse.etrice.doc/help/IntroductiontotheROOMLanguage.html
index e9a798e..a9738cf 100644
--- a/plugins/org.eclipse.etrice.doc/help/IntroductiontotheROOMLanguage.html
+++ b/plugins/org.eclipse.etrice.doc/help/IntroductiontotheROOMLanguage.html
@@ -79,7 +79,7 @@
</div>
</div>
</div>
-<p>Room was developed in the 1990th on the background of the upcoming mobile applications with the goal to manage the complexity of such huge SW-Systems. From the very beginning ROOM has focused on a certain type of SW-Systems and, is in contrast to the UML, well suited for this kind of systems. In this sense, ROOM is a DSL (Domain Specific Language) for distributed, event driven, real time systems. </p>
+<p>Room was developed in the 1990th on the background of the upcoming mobile applications with the goal to manage the complexity of such huge SW-Systems. From the very beginning ROOM has focused on a certain type of SW-Systems and, is in contrast to the UML, well suited for this kind of systems. In this sense, ROOM is a DSL (Domain Specific Language) for distributed, event driven, real time systems. </p>
<p>Bran Selic, Garth Gullekson and Paul T. Ward have published the concepts 1994 in the book &bdquo;REAL-TIME OBJECT-ORIENTED MODELING&rdquo;. The company
[<span class="citation">object time</span>] &trade; developed a ROOM tool which was taken over from
[<span class="citation">Rational SW</span>] &trade; and later on from
@@ -127,7 +127,9 @@
<p>As an example take a look at a washing machine. The system has to react on user interactions, has to handle some error conditions like a closed water tap or a defective lye pump. It has to react simultaneously to all this inputs. It has to close the water valve in a certain time to avoid flooding the basement.
So, the system can by characterized as timeliness, concurrent and reactive. As long as the washing machine does not transform to a laundry dryer by themself, the system has no dynamic internal structure and as long as all functions are running on a single microcontroller the (SW)-system is not distributed.
ROOM fits perfect to such a system.</p>
-<p>A SW system which mainly consists of transformations like signal processing or image processing (pure algorithms) cannot be characterized with any of the above mentioned properties. However, in the real world most of the SW systems will be a combination of both. ROOM can be mixed up with non model code. </p>
+<p>A SW system which mainly consists of data transformations like signal/image processing or loop controller (PID regulator) cannot be characterized with any of the above mentioned properties. However, in the real world most of the SW systems will be a combination of both. ROOM can be combined with such systems, so that for example an actor provides a
+ [<span class="citation">run to completion</span>] context for calculating a image processing algorithm.
+ </p>
</div>
<div class="section" title="What is the relation between OOP and ROOM?">
<div class="titlepage">
@@ -147,7 +149,7 @@
<p>
</p>
-<p>As the figure illustrates, the classic object paradigm does not care about concurrency issues. The threads of control will be provided from the underlying operating system.</p>
+<p>As the figure illustrates, the classic object paradigm does not care about concurrency issues. The threads of control will be provided from the underlying operating system and the user is responsible to avoid access violations by using operating system mechanisms (semaphore, mutex).</p>
<p>
</p>
@@ -156,7 +158,7 @@
<p>
</p>
-<p>ROOM provides the concept of a logical machine (called actor) with it&acute;s own thread of control. It provides some kind of cooperative communication infrastructure with &bdquo;run to completion&rdquo; semantic. That makes developing of business logic easy and save (see basic concepts). </p>
+<p>ROOM provides the concept of a logical machine (called actor) with it&acute;s own thread of control. It provides some kind of cooperative communication infrastructure with &bdquo;run to completion&rdquo; semantic. That makes developing of business logic easy and save (see basic concepts). The logical machine provides an encapsulation shell including concurrency issues (see chapter &bdquo;Run to completion&rdquo;). </p>
<p>
</p>
@@ -176,11 +178,24 @@
</div>
</div>
</div>
-<p>The main benefits are:
- - ROOM provides model execution, which makes it easy to find defects early enough, to reduce expensive debugging during the testing phase or even in the costumer environment.
- - ROOM promotes component building which is essential to make SW reusable
- - Graphical modeling makes it easy to understand, maintain and share code with other developers
- - higher abstraction in combination with automated code generation provides very efficient mechanisms to the developer. </p>
+<p>ROOM has a lot of benefits and it depends on the users point of view which is the most important one. From a general point of view the most important benefit is, that ROOM allows to create SW systems very efficient, robust and safe due to the fact that it provides some abstract, high level modeling concepts combined with code generation and a small efficient runtime environment. </p>
+<p>In detail:</p>
+<div class="itemizedlist">
+<ul class="itemizedlist" type="disc">
+<li class="listitem">
+<p>ROOM models contain well defined interfaces (protocols). That makes it easy to reuse components in different applications or e.g. in a test harness. </p>
+</li>
+<li class="listitem">
+<p>Graphical modeling makes it easy to understand, maintain and share code with other developers</p>
+</li>
+<li class="listitem">
+<p>Higher abstraction in combination with automated code generation provides very efficient mechanisms to the developer. </p>
+</li>
+<li class="listitem">
+<p>ROOM provides graphical model execution, which makes it easy to understand the application or find defects in a very early phase. </p>
+</li>
+</ul>
+</div>
</div>
<div class="section" title="Which consequences must be taken into account?">
<div class="titlepage">
diff --git a/plugins/org.eclipse.etrice.doc/help/Summary3.html b/plugins/org.eclipse.etrice.doc/help/Summary3.html
index 9a85aab..a7d8c68 100644
--- a/plugins/org.eclipse.etrice.doc/help/Summary3.html
+++ b/plugins/org.eclipse.etrice.doc/help/Summary3.html
@@ -28,9 +28,19 @@
<p>Within the
[<span class="citation">next</span>] transition,
[<span class="citation">MrPing</span>] creates a data class and sends the default values. Than
- [<span class="citation">MrPing</span>] changes the values and sends the class again. At this point you should note that during the send operation, a copy of the data class will be created and sent. Otherwise it would not be possible to send the same object two times, even more it would not be possible to send a stack object at all.
- In future versions of eTrice an additional mechanism to send references will be implemented. However, keep in mind that sending references transfers the responsibility of the life cycle of the sent object to the user. It looks simple but is a very common source of failures.
+ [<span class="citation">MrPing</span>] changes the values and sends the class again. At this point you should note that during the send operation, a copy of the data class will be created and sent. Otherwise it would not be possible to send the same object two times, even more it would not be possible to send a stack object at all.
+ However, for performance reasons some applications requires sending data by value. In this case the user is responsible for the life cycle of the object. In Java the VM takes care about the life cycle of an object. This is not the case for C/C++. Consider that a object which is created within a transition of a state machine will be destroyed when the transition is finished. The receiving FSM would receive an invalid reference. Therefore care must be taken by sending references.
</p>
+<p>For sending data by reference you simply have to add the keyword
+ [<span class="citation">ref</span>] to the protocol definition.
+ </p>
+<div class="literallayout">
+<p>
+<code class="code">Message&nbsp;ping(data:&nbsp;DemoData&nbsp;ref)<br>
+
+</code>
+</p>
+</div>
</div>
</body>
</html>
diff --git a/plugins/org.eclipse.etrice.doc/help/TutorialHelloWorld.html b/plugins/org.eclipse.etrice.doc/help/TutorialHelloWorld.html
index 4106b28..0678f92 100644
--- a/plugins/org.eclipse.etrice.doc/help/TutorialHelloWorld.html
+++ b/plugins/org.eclipse.etrice.doc/help/TutorialHelloWorld.html
@@ -71,6 +71,11 @@
</li>
</ol>
</div>
+<p>
+
+<a class="ulink" href="images\015-HelloWorld01.avi" target="_new">video</a>
+
+</p>
</div>
</div>
</body>
diff --git a/plugins/org.eclipse.etrice.doc/html/etrice.html b/plugins/org.eclipse.etrice.doc/html/etrice.html
index c132f9c..fe9cbd2 100644
--- a/plugins/org.eclipse.etrice.doc/html/etrice.html
+++ b/plugins/org.eclipse.etrice.doc/html/etrice.html
@@ -285,7 +285,7 @@
</div>
</div>
</div>
-<p>Room was developed in the 1990th on the background of the upcoming mobile applications with the goal to manage the complexity of such huge SW-Systems. From the very beginning ROOM has focused on a certain type of SW-Systems and, is in contrast to the UML, well suited for this kind of systems. In this sense, ROOM is a DSL (Domain Specific Language) for distributed, event driven, real time systems. </p>
+<p>Room was developed in the 1990th on the background of the upcoming mobile applications with the goal to manage the complexity of such huge SW-Systems. From the very beginning ROOM has focused on a certain type of SW-Systems and, is in contrast to the UML, well suited for this kind of systems. In this sense, ROOM is a DSL (Domain Specific Language) for distributed, event driven, real time systems. </p>
<p>Bran Selic, Garth Gullekson and Paul T. Ward have published the concepts 1994 in the book &bdquo;REAL-TIME OBJECT-ORIENTED MODELING&rdquo;. The company
[<span class="citation">object time</span>] &trade; developed a ROOM tool which was taken over from
[<span class="citation">Rational SW</span>] &trade; and later on from
@@ -333,7 +333,9 @@
<p>As an example take a look at a washing machine. The system has to react on user interactions, has to handle some error conditions like a closed water tap or a defective lye pump. It has to react simultaneously to all this inputs. It has to close the water valve in a certain time to avoid flooding the basement.
So, the system can by characterized as timeliness, concurrent and reactive. As long as the washing machine does not transform to a laundry dryer by themself, the system has no dynamic internal structure and as long as all functions are running on a single microcontroller the (SW)-system is not distributed.
ROOM fits perfect to such a system.</p>
-<p>A SW system which mainly consists of transformations like signal processing or image processing (pure algorithms) cannot be characterized with any of the above mentioned properties. However, in the real world most of the SW systems will be a combination of both. ROOM can be mixed up with non model code. </p>
+<p>A SW system which mainly consists of data transformations like signal/image processing or loop controller (PID regulator) cannot be characterized with any of the above mentioned properties. However, in the real world most of the SW systems will be a combination of both. ROOM can be combined with such systems, so that for example an actor provides a
+ [<span class="citation">run to completion</span>] context for calculating a image processing algorithm.
+ </p>
</div>
<div class="section" title="What is the relation between OOP and ROOM?">
<div class="titlepage">
@@ -353,7 +355,7 @@
<p>
</p>
-<p>As the figure illustrates, the classic object paradigm does not care about concurrency issues. The threads of control will be provided from the underlying operating system.</p>
+<p>As the figure illustrates, the classic object paradigm does not care about concurrency issues. The threads of control will be provided from the underlying operating system and the user is responsible to avoid access violations by using operating system mechanisms (semaphore, mutex).</p>
<p>
</p>
@@ -362,7 +364,7 @@
<p>
</p>
-<p>ROOM provides the concept of a logical machine (called actor) with it&acute;s own thread of control. It provides some kind of cooperative communication infrastructure with &bdquo;run to completion&rdquo; semantic. That makes developing of business logic easy and save (see basic concepts). </p>
+<p>ROOM provides the concept of a logical machine (called actor) with it&acute;s own thread of control. It provides some kind of cooperative communication infrastructure with &bdquo;run to completion&rdquo; semantic. That makes developing of business logic easy and save (see basic concepts). The logical machine provides an encapsulation shell including concurrency issues (see chapter &bdquo;Run to completion&rdquo;). </p>
<p>
</p>
@@ -382,11 +384,24 @@
</div>
</div>
</div>
-<p>The main benefits are:
- - ROOM provides model execution, which makes it easy to find defects early enough, to reduce expensive debugging during the testing phase or even in the costumer environment.
- - ROOM promotes component building which is essential to make SW reusable
- - Graphical modeling makes it easy to understand, maintain and share code with other developers
- - higher abstraction in combination with automated code generation provides very efficient mechanisms to the developer. </p>
+<p>ROOM has a lot of benefits and it depends on the users point of view which is the most important one. From a general point of view the most important benefit is, that ROOM allows to create SW systems very efficient, robust and safe due to the fact that it provides some abstract, high level modeling concepts combined with code generation and a small efficient runtime environment. </p>
+<p>In detail:</p>
+<div class="itemizedlist">
+<ul class="itemizedlist" type="disc">
+<li class="listitem">
+<p>ROOM models contain well defined interfaces (protocols). That makes it easy to reuse components in different applications or e.g. in a test harness. </p>
+</li>
+<li class="listitem">
+<p>Graphical modeling makes it easy to understand, maintain and share code with other developers</p>
+</li>
+<li class="listitem">
+<p>Higher abstraction in combination with automated code generation provides very efficient mechanisms to the developer. </p>
+</li>
+<li class="listitem">
+<p>ROOM provides graphical model execution, which makes it easy to understand the application or find defects in a very early phase. </p>
+</li>
+</ul>
+</div>
</div>
<div class="section" title="Which consequences must be taken into account?">
<div class="titlepage">
@@ -410,8 +425,73 @@
</div>
</div>
</div>
-<p>port, protocol, actor, interface, asynchronous communication
- hierarchical FSM, hierarchical structure</p>
+<div class="section" title="Actor, Port, Protocol">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="ActorPortProtocol"></a>Actor, Port, Protocol</h3>
+</div>
+</div>
+</div>
+<p>The basic elements of ROOM are the actor with its ports and protocols. The protocol provides a formal interface description. The port is an interaction point where the actor interacts with its outside world. Each port has exactly one protocol attached. The sum of all ports builds up the complete interface of an actor. Each port can receive messages with or without data which is defined in the protocol. Each message will be handled from the actors behavior (state machine) or will be delegated to the actors internal structure.</p>
+<p>The actor provides access protection for it&acute;s own attributes (including complex types (classic objects)), including concurrency protection. An actor has neither public attributes nor public operations. The only interaction with the outside world takes place via interface ports. This ensures a high degree of reuse ability on actor level and provides an effective and safe programming model to the developer. </p>
+<p>Receiving a message via a port will trigger the internal state machine. A transition will be executed depending on the message and the actual state. Within this transition, detailed code will be executed and response messages can be sent.</p>
+<p>
+
+<a class="ulink" href="images\010-room-introduction01.avi" target="_new">receiving a message</a>
+
+</p>
+<p>With this model, a complex behavior will be divided into many relatively simple, linked actors. To say it the other way round: The complex behavior will be provided by a network of relatively simple components which are communicating with each other via well defined interfaces.</p>
+</div>
+<div class="section" title="Hierarchy in Structure and FSM">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="HierarchyinStructureandFSM"></a>Hierarchy in Structure and FSM</h3>
+</div>
+</div>
+</div>
+<p>ROOM provides two types of hierarchy. Behavioral hierarchy and structural hierarchy. Structural hierarchy means that actors can be nested to any level. Usually you will add more and more details to your application with each nesting level. That means you can focus yourself on any level of abstraction with always the same element, the actor. Structural hierarchy provides a power full mechanism to divide your problem in smaller pieces, so that you can focus the level of abstraction you want to work on. </p>
+<p>The actors behavior will be described with a state machine. The states itself may contain sub states. This is also a possibility to focus on an abstraction level. Take the simple FSM from the blinky actor from the blinky tutorial: </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images\020-Blinky15.png"></div>
+<p>
+
+</p>
+<p>From an abstract point of view there is a state &bdquo;blinking&rdquo;. But a simple LED is not able to blink autonomously. Therefore you have to add more details to your model to make a LED blinking, but for the current work it is not of interest how blinking is realized. This will be done in the next lower level of the hierarchy. </p>
+<p>With this very simple example you can easily imagine how power full this mechanisms is.</p>
+<p>The hierarchical FSM provides a rich tool box to describe real world problems. (see &bdquo;room concepts&rdquo;).</p>
+</div>
+<div class="section" title="Run to Completion">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="RuntoCompletion"></a>Run to Completion</h3>
+</div>
+</div>
+</div>
+<p>&bdquo;Run to completion&rdquo; (RTC) is a very central concept of ROOM. It enables the developer to concentrate on the functional aspects of the system. The developer must not take care about concurrency issues all the time. This job is concentrated to the system designer in a very flexible way.
+ What does &bdquo;run to completion&rdquo; mean:
+ RTC means that an actor, which is processing a message, can not be receive the next message as long as the processing of the current message has not been finished. Receiving of the next message will be queued from the underlying run time system.</p>
+<p>Note: It is very important not to confuse run to completion and preemption. Run to completion means that an actor will finish the processing of a message before he can receive a new one (regardless of its priority). That does not mean that an actor cannot be preempted from an higher prior thread of control. Even a message from this higher prior thread of control will be queued till the current processing has been finished. </p>
+<p>With this mechanism all actor internal attributes and data structures are protected. Due to the fact that multiple actors share one thread of control, all objects are protected which are accessed from one thread of control but multiple actors. This provides the possibility to decompose complex functionality to several actors without the risk to produce access violations.</p>
+</div>
+<div class="section" title="Layering">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="Layering"></a>Layering</h3>
+</div>
+</div>
+</div>
+</div>
</div>
<div class="section" title="Benefits">
<div class="titlepage">
@@ -480,6 +560,9 @@
</div>
</div>
</div>
+<p>port, protocol, actor, interface, asynchronous communication
+ hierarchical FSM, hierarchical structure</p>
+<p>run to completion</p>
</div>
</div>
</div>
@@ -521,6 +604,11 @@
</li>
</ol>
</div>
+<p>
+
+<a class="ulink" href="images\015-HelloWorld01.avi" target="_new">video</a>
+
+</p>
</div>
<div class="section" title="Create a new model from scratch">
<div class="titlepage">
@@ -1240,6 +1328,9 @@ carLights.setState(TrafficLight3.OFF);<br>
[<span class="citation">off</span>] is the
[<span class="citation">stop</span>] event from the
[<span class="citation">ControlPort</span>].
+ Note: The transition from
+ [<span class="citation">blinking</span>] to
+ [<span class="citation">off</span>] is a so called group transition. This is a outgoing transition from a super state (state with sub states) without specifying the concrete leave state (state without sub states). An incoming transition to a super state is called history transition.
</p>
<p>Action code of the init transition is:</p>
<div class="literallayout">
@@ -1812,9 +1903,19 @@ carLights.setState(TrafficLight3.OFF);&nbsp;<br>
<p>Within the
[<span class="citation">next</span>] transition,
[<span class="citation">MrPing</span>] creates a data class and sends the default values. Than
- [<span class="citation">MrPing</span>] changes the values and sends the class again. At this point you should note that during the send operation, a copy of the data class will be created and sent. Otherwise it would not be possible to send the same object two times, even more it would not be possible to send a stack object at all.
- In future versions of eTrice an additional mechanism to send references will be implemented. However, keep in mind that sending references transfers the responsibility of the life cycle of the sent object to the user. It looks simple but is a very common source of failures.
+ [<span class="citation">MrPing</span>] changes the values and sends the class again. At this point you should note that during the send operation, a copy of the data class will be created and sent. Otherwise it would not be possible to send the same object two times, even more it would not be possible to send a stack object at all.
+ However, for performance reasons some applications requires sending data by value. In this case the user is responsible for the life cycle of the object. In Java the VM takes care about the life cycle of an object. This is not the case for C/C++. Consider that a object which is created within a transition of a state machine will be destroyed when the transition is finished. The receiving FSM would receive an invalid reference. Therefore care must be taken by sending references.
+ </p>
+<p>For sending data by reference you simply have to add the keyword
+ [<span class="citation">ref</span>] to the protocol definition.
</p>
+<div class="literallayout">
+<p>
+<code class="code">Message&nbsp;ping(data:&nbsp;DemoData&nbsp;ref)<br>
+
+</code>
+</p>
+</div>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;6.&nbsp;Tutorial Pedestrian Lights">
diff --git a/plugins/org.eclipse.etrice.doc/manual/etrice.pdf b/plugins/org.eclipse.etrice.doc/manual/etrice.pdf
index 3db5d63..42db7f1 100644
--- a/plugins/org.eclipse.etrice.doc/manual/etrice.pdf
+++ b/plugins/org.eclipse.etrice.doc/manual/etrice.pdf
Binary files differ
diff --git a/plugins/org.eclipse.etrice.doc/toc.xml b/plugins/org.eclipse.etrice.doc/toc.xml
index d6de1aa..1617b7f 100644
--- a/plugins/org.eclipse.etrice.doc/toc.xml
+++ b/plugins/org.eclipse.etrice.doc/toc.xml
@@ -13,7 +13,12 @@
<topic href="help/IntroductiontotheROOMLanguage.html#WhatarethebenefitsofROOM" label="What are the benefits of ROOM?"></topic>
<topic href="help/IntroductiontotheROOMLanguage.html#Whichconsequencesmustbetakenintoaccount" label="Which consequences must be taken into account?"></topic>
</topic>
-<topic href="help/BasicConcepts.html" label="Basic Concepts"></topic>
+<topic href="help/BasicConcepts.html" label="Basic Concepts">
+<topic href="help/BasicConcepts.html#ActorPortProtocol" label="Actor, Port, Protocol"></topic>
+<topic href="help/BasicConcepts.html#HierarchyinStructureandFSM" label="Hierarchy in Structure and FSM"></topic>
+<topic href="help/BasicConcepts.html#RuntoCompletion" label="Run to Completion"></topic>
+<topic href="help/BasicConcepts.html#Layering" label="Layering"></topic>
+</topic>
<topic href="help/Benefits.html" label="Benefits"></topic>
<topic href="help/ExecutionModels.html" label="Execution Models">
<topic href="help/ExecutionModels.html#LogicalMachine" label="Logical Machine"></topic>