+ + + - + + + - - C++ Extensions @@ -1244,11 +1258,11 @@ Automatically Generated Example You can find sample applications that use automatically generated type descriptors here: -Automatically generated type descriptor for an enum -Automatically generated type descriptor for an enum class with a custom encode function -Automatically generated type descriptor for a struct -Automatically generated type descriptor for a struct that contains another struct -Automatically generated type descriptor for a typedef and type alias +Automatically generated type descriptor for an enum +Automatically generated type descriptor for an enum class with a custom encode function +Automatically generated type descriptor for a struct +Automatically generated type descriptor for a struct that contains another struct +Automatically generated type descriptor for a typedef and type alias Manually Implemented @@ -1299,7 +1313,7 @@ Manually Implemented Example -You can find a sample application that uses a manually implemented type descriptor here. +You can find a sample application that uses a manually implemented type descriptor here. Field Descriptor A type descriptor for a structured type (class or struct) contains information about the member variables (a.k.a fields) of the type. This information is stored in a field descriptor object typed by the TargetRTS class RTFieldDescriptor. @@ -1326,30 +1340,25 @@ Field Descriptor Example -You can find a sample application where a field descriptor is declared here. +You can find a sample application where a field descriptor is declared here. Inheritance If a class or struct inherits from another class or struct, as in the example above, then the type descriptor of the derived type will have a reference to the type descriptor of the base type. In this case both types need to have a type descriptor. A type descriptor can at most reference one base type descriptor (a.k.a. a super descriptor) which means that only single inheritance is supported for automatically generated type descriptors. If you use multiple inheritance you have to write a manual type descriptor for the derived type. Example -You can find a sample application that uses an automatically implemented type descriptor for a class that inherits from another class here. +You can find a sample application that uses an automatically implemented type descriptor for a class that inherits from another class here. - - - - - -
+ - + + + - - C++ Extensions @@ -1244,11 +1258,11 @@ Automatically Generated Example You can find sample applications that use automatically generated type descriptors here: -Automatically generated type descriptor for an enum -Automatically generated type descriptor for an enum class with a custom encode function -Automatically generated type descriptor for a struct -Automatically generated type descriptor for a struct that contains another struct -Automatically generated type descriptor for a typedef and type alias +Automatically generated type descriptor for an enum +Automatically generated type descriptor for an enum class with a custom encode function +Automatically generated type descriptor for a struct +Automatically generated type descriptor for a struct that contains another struct +Automatically generated type descriptor for a typedef and type alias
+ + + - + + + - - The Art Language -Art is a language for developing stateful and event-driven realtime applications. By stateful we mean that the application consists of objects whose behavior can be described with state machines. By event-driven we mean that these objects communicate with each other by sending events, which can cause their state machines to transition from one state to another. +Art is a language for developing stateful and event-driven realtime applications. By stateful we mean that the application consists of objects whose behavior can be described with state machines. By event-driven we mean that these objects communicate with each other by sending events, which can cause their state machines to transition from one state to another when received. The Art language provides high-level concepts not directly found in the C++ language. All these high-level concepts are transformed into C++ code by the Art compiler. Generated code uses a run-time library known as the TargetRTS (Target RunTime System). The TargetRTS is a C++ library that acts as a layer between the generated code and the underlying platform (hardware, operating system etc) on which the realtime application runs. Art is well suited for describing both the behavior and structure of a realtime application, but it uses C++ as expression and action language. C++ is also used for declaring types, variables, functions etc. As a rule of thumb, Art uses C++ for everything where C++ is a good fit, and only provides new language concepts where no appropriate constructs exist in C++. This means that if you already know C++, you can quickly learn Art too, and existing C++ code you have already written can be used in your Art application. Note that the translation of Art to C++ also involves analysis of the C++ code that is present in the Art files. The code generator supports certain C++ extensions in such embedded C++ code and will "expand" them to C++ code as part of code generation for an Art file. Concepts and Terminology -In Art the concept of a capsule is central. A capsule is like a C++ class, but with a few differences and extensions. A C++ class is passive in the sense that a caller can access its public member functions and variables at any time. Hence a C++ object always executes in the context of the caller, and when a member function is called, the caller is blocked until it returns. A capsule, however, is active and has its own execution context. This means that we never call a capsule member function or access a capsule member variable from outside the capsule itself. Instead we communicate with the capsule by sending events to it. Each capsule has a queue of events it has received and the events will be dispatched to the capsule one by one. The sender of the event is not blocked, as the event will be handled by the capsule asynchronously when it is later dispatched. -The picture below shows 3 capsule instances each holding a queue with events that have been received, but not yet dispatched. Note that this picture is conceptual. In a real implementation several performance optimizations are applied, for example it's common to let a single thread drive more than one capsule instance, and several capsule instances can share a common event queue. But from a conceptual point of view each capsule has its own queue of events that are waiting to be dispatched to it. Events have a priority which determines how they are ordered in the queue. Events with high priority are placed before events with lower priority, and if two events have the same priority they are ordered according to when they arrive. +In Art the concept of a capsule is central. A capsule is like a C++ class, but with a few differences and extensions. A C++ class is passive in the sense that a caller can access its public member functions and variables at any time. Hence a C++ object always executes in the context of the caller, and when a member function is called, the caller is blocked until the function call returns. A capsule, however, is active and has its own execution context. This means that we never call a capsule member function or access a capsule member variable from outside the capsule itself. Instead we communicate with the capsule by sending events to it. Each capsule instance has a queue of events it has received and those events will be dispatched to the capsule instance one by one. The sender of the event is not blocked, as the event will be handled by the capsule instance asynchronously when it is later dispatched. +The picture below shows 3 capsule instances each holding a queue with events that have been received, but not yet dispatched. Note that this picture is conceptual. In a real implementation several performance optimizations are applied, for example it's common to let a single thread drive more than one capsule instance, and several capsule instances can share a common event queue. But from a conceptual point of view each capsule instance has its own queue of events that are waiting to be dispatched to it. Events have a priority which determines how they are ordered in the queue. Events with high priority are placed before events with lower priority, and if two events have the same priority they are ordered according to when they arrive. A capsule may have ports. A port is typed by a protocol which defines the events that may be sent in to the port (these are known as in-events), as well as the events the capsule itself may send out through the port for others to receive (these are called out-events). Ports can be used both for internal and external communication. A port used for external communication is called a service port. Together, the service ports constitute the communication interface of the capsule, and decide what "services" the capsule provides for other capsules to use. A simple capsule which only handles a small number of events, may be able to handle all these events using a single state machine. However, when new ports are added (or new events in protocols typing existing ports), the capsule interface grows and the state machine has to grow with it, since there will be more events for it to handle. Eventually a point is reached where it will not be practical for a capsule to handle any more events in its own state machine, because it has grown too large or complex. If not before, this is the time to define a composite structure for the capsule. A composite structure is created by decomposing a capsule using capsule parts. A capsule part (or, for simplicity, just part) is typed by another capsule and is a way for a capsule to delegate some of its responsibilities to other capsules. Such a decomposition is purely an implementation detail that is not visible from the outside of the capsule. When you send an event to a capsule you cannot know if the capsule will handle the event itself, or if it will forward the event to another capsule typing one of its capsule parts. The ability to decompose a capsule into parts is important for managing complexity. When a capsule has grown too big and complex you can decompose it into capsule parts without changing the communication interface of the capsule. -Ports of capsules typing capsule parts are connected to each other by means of connectors. A connector is a conceptual construct for showing how events are routed in the internal structure of a capsule. At run-time connectors don't exist, and ports are directly connected to each other. Because of this, it's not mandatory to use connectors. You can also choose to dynamically connect (and disconnect) ports at run-time. Although this provides for more flexibility, it has the drawback of making it impossible to statically visualize the communication paths of a capsule. Ports that connect statically to other ports via connectors are called wired ports. Ports that are connected dynamically without use of static connectors are called unwired ports. +Ports of capsules typing capsule parts are connected to each other by means of connectors. A connector is a conceptual construct for showing how events are routed in the composite structure of a capsule. At run-time connectors don't exist, and ports are directly connected to each other. Because of this, it's not mandatory to use connectors. You can also choose to dynamically connect (and disconnect) ports at run-time. Although this provides for more flexibility, it has the drawback of making it impossible to statically visualize the communication paths of a capsule. Ports that connect statically to other ports via connectors are called wired ports. Ports that are connected dynamically without use of static connectors are called unwired ports. The picture below shows the structure of a capsule Top which consists of two capsule parts ping and pong each holding a capsule instance (a Pinger capsule and a Ponger capsule respectively). The connector between the wired ports p on these capsules makes it possible for these capsules to communicate with each other. Communication can also happen using the unwired ports q1 and q2 if they are connected at run-time. The picture also shows that the capsule Ponger is further decomposed using a capsule part inner. All events sent to port p of Ponger will be further routed to port i of the Internal capsule. -Regardless if ports are statically connected by connectors (wired ports), or dynamically connected at run-time (unwired ports), they must be compatible with each other. This means that the out-events of one port must match the in-events of the other port, for the ports to be possible to connect. This constraint ensures that events are never lost when traveling between two connected ports. To make it possible to describe the events that may travel between two connected ports using a single protocol, one of the ports can be declared as conjugated. For a conjugated port the meaning of in-events and out-events are swapped, so that the in-events are the events that may be sent out through the port, and the out-events are the ports that may be sent to the port. In the picture above port q1 is non-conjugated () while port q2 is conjugated (). +Regardless if ports are statically connected by connectors (wired ports), or dynamically connected at run-time (unwired ports), they must be compatible with each other. This means that the out-events of one port must match the in-events of the other port, for the ports to be possible to connect. This constraint ensures that events are never lost when traveling between two connected ports. To make it possible to describe the events that may be sent between two connected ports using a single protocol, one of the ports can be declared as conjugated. For a conjugated port the meaning of in-events and out-events are swapped, so that the in-events are the events that may be sent out through the port, and the out-events are the ports that may be sent to the port. In the picture above port q1 is non-conjugated () while port q2 is conjugated (). Both capsule parts and ports may have multiplicity. You can think about a capsule part with multiplicity > 1 as an array that holds capsule instances at run-time. In the same way you can think about a port with multiplicity > 1 as an array that holds connections to port instances at run-time. The multiplicity of ports and parts must match when connecting two ports with each other. Once again, this constraint ensures that events will not be lost when traveling between the connected ports at run-time. The picture below shows a capsule with a part and a port that both have multiplicity > 1. In structure diagrams such parts and ports are shown as "stacked boxes". -In addition to regular C++ member functions a capsule may have a state machine as its behavior. A state machine describes how an instance of the capsule may move between different states through its life-time. A transition that connects a source state with a target state may be triggered when an event from a capsule's event queue is dispatched. Several conditions must hold true for the transition to trigger. For example, the event must match a trigger that specifies the expected type of event and the port on which it was received. It's also possible to associate a boolean guard condition with the transition and/or with the trigger which must be true for the transition to trigger. A transition may have an effect, which is a piece of C++ code that executes when the transition gets triggered. -The picture below shows a state machine containing three states and three transitions. The presence of transition guard code is shown with a yellow dot and the presence of transition effect code is shown with a blue dot. Both these are C++ code snippets that are embedded in the Art file. +In addition to regular C++ member functions a capsule may have a state machine as its behavior. A state machine describes how an instance of the capsule may move between different states through its life-time. A transition that connects a source state with a target state may be triggered when a received event from a capsule's event queue is dispatched. Several conditions must hold true for the transition to trigger. For example, the event must match a trigger that specifies the expected type of event and the port on which it was received. It's also possible to associate a boolean guard condition with the transition and/or with the trigger which must be true for the transition to trigger. A transition may have an effect, which is a piece of C++ code that executes when the transition gets triggered. +The picture below shows a state machine containing a few states and transitions. The presence of transition guard code is shown with a yellow dot and the presence of transition effect code is shown with a blue dot. Both these are C++ code snippets that are embedded in the Art file. -When a capsule instance is created (this is sometimes referred to as capsule incarnation), it's state machine starts to execute by triggering the transition that goes out from the initial state (the big blue circle in the above diagram). Each state machine must have exactly one such initial state with an outgoing transition. Since this initial transition is triggered automatically when the capsule instance is created it cannot have any constraints like mentioned above. The initial transition is an example of a non-triggered transition since it cannot have triggers. -The path from the source state to the target state can sometimes consist of more than one transition. In that case only the first of these is a triggered transition that may have triggers that specify when it will trigger. Once the first transition in this path has triggered, subsequent non-triggered transitions will always execute, one by another according to how they are connected in the state machine. However, also non-triggered transitions (with the exception of the initial transition) may have guards. Such guards are usually evaluated before the triggered transition triggers to ensure that they all are enabled, so that it's guaranteed that the target state can be reached. There is one exception to this rule, for transitions that leave a choice. Such guards are only evaluated once the choice has been reached to dynamically decide which outgoing transition to take next. This also means that guards of such transitions must be mutually exclusive, or there is a risk that the state machine will get stuck in the choice. +When a capsule instance is created (this is sometimes referred to as capsule incarnation), it's state machine starts to execute by triggering the transition that goes out from the initial state (the circular blue symbol to the left in the above diagram). Each state machine must have exactly one such initial state with an outgoing transition. Since this initial transition is triggered automatically when the capsule instance is created it cannot have constraints such as triggers and guard conditions. The initial transition is an example of a non-triggered transition since it cannot have triggers. +The path from the source state to the target state can sometimes consist of more than one transition. In that case only the first of these is a triggered transition that may have triggers that specify when it will trigger. Once the first transition in this path has triggered, subsequent non-triggered transitions will always execute, one by one according to how they are connected in the state machine. However, also non-triggered transitions (with the exception of the initial transition) may have guards. Such guards are usually evaluated before the triggered transition triggers to ensure that they all are enabled, so that it's guaranteed that the target state can be reached. There is one exception to this rule, for transitions that leave a choice. Such guards are only evaluated once the choice has been reached to dynamically decide which outgoing transition to take next. This also means that guards of such transitions must be written so that at least (and at most) one outgoing transition is enabled, or there is a risk that the state machine will get stuck in the choice. In the state machine shown below the transitions t2 and t5 are triggered transitions, while other transitions are non-triggered. Transition t5 can only be triggered if either the guard of t7 or t6 is true, while t2 can be triggered even if neither the guard of t3 nor t4 is true. The target of transition t5 is a junction which is used for either splitting or merging transition paths depending on evaluated guard conditions. A state may be decomposed by a sub state machine. Such a state is called a composite state and a state machine that has composite states is called a hierarchical state machine. Transitions enter a composite state through an entry point and exit it through an exit point. @@ -1461,13 +1454,13 @@ Concepts and Terminology A state may have an entry action and/or exit action which is a C++ code snippet that gets executed whenever the state is entered or exited. Note that state entry actions for nested states also run when those states are entered because of a deep history. In state diagrams the presence of entry and/or exit actions are shown by icons just below the state name. In the state machine shown below state S1 has an entry action, state S2 has an exit action and state S3 has both an entry and an exit action. -A transition where the source and target state is the same state is called a self-transition. A special kind of self-transition is an internal transition, which is a transition that when triggered doesn't leave the current state. Hence, when an internal transition is triggered the active state configuration remains unchanged, and neither the entry nor exit action of the state gets executed. In the state machine shown below the state has two self-transitions; t which is a regular self-transition (a.k.a. external self-transition) and it which is an internal transition. Since a state may have a large number of internal transitions they are not shown inside the state symbol, but if you select the state symbol you can see them in the Properties view. An icon is shown on those states that contain internal transitions. +A transition where the source and target state is the same state is called a self-transition. A special kind of self-transition is an internal transition, which is a transition that when triggered doesn't leave the current state. Hence, when an internal transition is triggered the active state configuration remains unchanged, and neither the entry nor exit action of the state gets executed. In the state machine shown below the state has two self-transitions; t which is a regular self-transition (a.k.a. external self-transition) and it which is an internal transition. Since a state may have a large number of internal transitions they are not shown inside the state symbol, but if you select the state symbol you can see them in the Properties view. An icon is shown in the upper right corner of states that contain internal transitions. State machines can not only be defined for capsules but also for regular classes. This can be useful if you want a plain passive C++ class to have a state machine. Contrary to a capsule a class may not have ports and doesn't execute in its own context. It's therefore common to associate such a class with a capsule that it can use for sending events through its ports. Transitions of a passive class state machine are triggered by calling trigger operations on the class. Such operations have no code, but just trigger transitions in the class state machine. The realtime application needs to designate one capsule as the top capsule. This is done in the transformation configuration, which is a file containing all the properties used for building the application (e.g. code generator options, compiler settings etc.). There is no language construct in Art for defining a top capsule; any capsule that you define can act as the top capsule. However, in practise you typically decide at an early stage which capsule that will be the top capsule. The top capsule is the entry point of the realtime application. When it starts to execute one instance of the top capsule will be automatically created, and its state machine starts to execute. If you build a library rather than an executable you don't have a top capsule. Embedded C++ Code -Art uses C++ as action and expression language. It also uses C++ for defining types, variables and functions. A C++ code snippet can be embedded into Art at many places by enclosing it with backticks. Here is an example of how to write the code that should execute when a transition triggers: +Art uses C++ as action and expression language. It also uses C++ for defining types, variables and functions. A C++ code snippet can be embedded into an Art file at many places by enclosing it with backticks. Here is an example of how to write the code that should execute when a transition triggers: S1 -> S2 on timer.timeout ` std::cout << "Hello World!" << std::endl; @@ -1564,7 +1557,7 @@ Textual and Graphical Notations Art elements are mostly edited using their textual notation, but diagrams also provide some editing capabilities. However, all edit commands performed from a diagram are actually mapped to corresponding textual modifications of the Art file. Editing from a diagram is therefore simply an alternative, and sometimes more convenient way, of editing the textual Art file. Syntax -Art uses a syntax that should look familiar to developers with knowledge about languages like C++ and Java. +Art uses a syntax that should be familiar to developers with knowledge about languages like C++ and Java. Declarations are terminated with a semicolon ; When multiple elements are declared in the same language construct commas , are used for separating the elements @@ -1750,7 +1743,7 @@ Capsule Constructor Example -You can find a sample application that uses a capsule constructor here. +You can find a sample application that uses a capsule constructor here. Capsule Destructor The destructor of a capsule frees the memory used for representing its states, ports etc. You cannot provide your own code to the destructor implementation. However, the RTActor class, which is the base class of every capsule class, provides a virtual function _predestroy() which you can override in your capsule. This function gets called just before the capsule instance is destroyed and is the place where you should put code that cleans up resources allocated by the capsule. Here is an example: @@ -1769,7 +1762,7 @@ Capsule Destructor It's important to remember to invoke the inherited function by calling SUPER::_predestroy(). Example -You can find a sample application with a capsule that overrides _predestroy() here. +You can find a sample application with a capsule that overrides _predestroy() here. Protocol and Event A protocol defines events that may be sent in to a port (so called in-events) and events that may be sent out from the same port (so called out-events). By grouping events into protocols, and then typing ports with such protocols, we can precisely define which events the capsule may send and receive through that port. @@ -1818,7 +1811,7 @@ Protocol and Event Port A port defines a named point of communication for a capsule. A port is typed by a protocol which defines the events that may be sent in to (in-events) and out from (out-events) the port. A port may be conjugated in order to swap the meaning of in-events and out-events. That is, a capsule may send out-events on its non-conjugated ports, but in-events on its conjugated ports. A port becomes conjugated if you add a tilde (~) after its name. Ports are often named to describe the role or purpose of the communication that takes place on them. By convention names of ports start with lowercase and use camelCase if the name consists of multiple words. -Here is an example of a capsule with a few ports. Note that RTist in Code provides several predefined protocols that can be used right away, for example Timing. Also note that you can declare multiple ports on a single line if the ports are of the same kind (p1 and p2 below are both service ports). +Here is an example of a capsule with a few ports. Note that Code RealTime provides several predefined protocols that can be used right away, for example Timing. Also note that you can declare multiple ports on a single line if the ports are of the same kind (p1 and p2 below are both service ports). capsule Machine { service port control : MachineEvents; behavior port timer : Timing; // predefined Timing protocol @@ -1840,8 +1833,9 @@ Port Example -You can find a sample application that sends events on ports with and without data here. +You can find a sample application that sends events on ports with and without data here. +Note that send() is not the only function you can call. For example, you can call invoke() if you want to wait until the receiver has received and replied to the event. This is useful for implementing synchronous communication between capsules. Port Multiplicity At run-time an instance of a port can be connected to a port instance on another capsule. Such connections is what make a sent event be routed from the port on which it is sent, through a number of non-behavior ports, until it finally reaches a behavior port. By default a port has single multiplicity (1) meaning that at most one such connection can be established. However, you can specify a non-single multiplicity for a port to allow for more connections to be created at run-time. In the example below a Server capsule has a port with multiplicity 100. At run-time an instance of that Server capsule can be connected to 100 different client ports, each of which can send events to the server. @@ -1861,7 +1855,7 @@ Port Multiplicity }; Notification Port -Every protocol contains two implicit events rtBound and rtUnbound. A port can choose to receive those events whenever a connection for the port is established (rtBound) or dropped (rtUnbound) at run-time. Declare a port as a notification port to receive these events. +Every protocol contains two implicit events rtBound and rtUnbound. A port can choose to receive those events whenever a connection for the port is established (rtBound) or dropped (rtUnbound) at run-time. Declare a port as a notification port to receive these events. capsule Server { service notify port clients : ComEvents[100]; @@ -1904,7 +1898,7 @@ Unwired Port registration specifies when an unwired port should be registered registration_name specifies the service name with which the port should be registered -If you choose to register an unwired port programmatically (using the TargetRTS functions registerSPP and registerSAP) you decide at registration time whether the port should be an SAP or SPP port. However, if you choose to instead let the port be registered automatically you need to declare the port as either a subscribe (SAP) or publish (SPP) port. Here is the same example again, but now with automatic registration of the unwired ports using the service name myService: +If you choose to register an unwired port programmatically (using the TargetRTS functions registerSPP() and registerSAP()) you decide at registration time whether the port should be an SAP or SPP port. However, if you choose to instead let the port be registered automatically you need to declare the port as either a subscribe (SAP) or publish (SPP) port. Here is the same example again, but now with automatic registration of the unwired ports using the service name myService: capsule Client { subscribe behavior port sap [[rt::properties( registration_name = "myService") @@ -1922,11 +1916,15 @@ Unwired Port }; Note that the keyword unwired can be implicit when you declare a port as either a subscribe or publish port. + +Example +You can find a sample application that uses an unwired port here. + Connector Connectors describe how events are routed within a capsule by connecting ports in its composite structure. They make it possible to see in a structure diagram which parts of a capsule that can communicate with each other. Each connector connects exactly two ports with each other. A connected port may either be a port of the capsule itself, or a port of a capsule that types one of its capsule parts. A few constraints decide if it's possible to connect two ports: 1) The ports must be wired. Unwired ports cannot be connected. 2) The ports must be typed by the same protocol. -3) The ports' conjugations must match. If the ports are at the same level in the capsule's structure (e.g. both ports belong to capsules typing capsule parts owned by the same capsule), then the connected ports must have the opposite conjugation. This is because events that are sent out from one of the ports must be able to be received by the other port. However, if the ports are at different levels in the capsule's structure (e.g. one of them belongs to a capsule typing a capsule part owned by the capsule and the other belongs to the capsule itself), then the ports must have the same conjugation. This is because in this case events are simply delegated from one capsule to another. +3) The ports' conjugations must match. If the ports are at the same level in the capsule's structure (e.g. both ports belong to capsules typing capsule parts owned by the same capsule), then the connected ports must have the opposite conjugation. This is because events that are sent out from one of the ports must be able to be received by the other port and vice versa. However, if the ports are at different levels in the capsule's structure (e.g. one of them belongs to a capsule typing a capsule part owned by the capsule and the other belongs to the capsule itself), then the ports must have the same conjugation. This is because in this case events are simply delegated from one capsule to another. 4) If a connector is connected to a port and a part (where the port is defined on the capsule that types the part), then the port must be a service port. Only service ports are visible from the outside of a capsule. The example below shows the structure diagram of a capsule Top where we can see two connectors. capsule Top { @@ -1953,7 +1951,7 @@ Connector }; -The connector between p1 and p2 goes between two ports on the same level which is why these ports must have opposite conjugation. The connector between p2 and i goes between two ports at different levels which is why these ports must have the same conjugation. The non-behavior port p2 is a so called relay port (it just relays all events it receives to another port) and the connector between p2 and i is sometimes called a delegation connector to describe the fact that capsule Ponger uses it for delegating some of its responsiblities to the capsule Inner. Note that relay ports can be optimized away so they don't exist at run-time (i.e. at run-time port p1 can be directly connected to i). +The connector between p1 and p2 goes between two ports on the same level which is why these ports must have opposite conjugation. The connector between p2 and i goes between two ports at different levels which is why these ports must have the same conjugation. The non-behavior port p2 is a so called relay port (it just relays all events it receives to another port) and the connector between p2 and i is sometimes called a delegation connector to describe the fact that capsule Ponger uses it for delegating some of its responsiblities to the capsule Internal. Note that relay ports can be optimized away so they don't exist at run-time (i.e. at run-time port p1 can be directly connected to i). A connector doesn't have a direction, so it doesn't matter in which order it connects the two ports. That is, connecting X with Y is equivalent to connecting Y with X. Local Binding A connector can connect two behavior ports on the same capsule (with opposite conjugations). At run-time this will lead to a local binding between these ports. This enables the capsule to send events to itself which sometimes can be useful. Here is an example: @@ -1968,7 +1966,7 @@ Local Binding One reason for a capsule to send events to itself could be to split a big and long-running task into smaller tasks. By sending an event to itself after completion of each small task, the capsule can remain responsive to other events that may arrive in the meantime. When it receives the event it sent it can proceed with the next part of the big task. Example -You can find a sample application that uses a local binding here. +You can find a sample application that uses a local binding here. Part A capsule can be decomposed by means of parts (also called "capsule parts" to emphasize that they are parts of a capsule). A part is a container that at run-time may hold one or many capsule instances. The part has a multiplicity that specifies the maximum number of capsule instances it can contain at run-time, and it has a type which is another capsule. All capsule instances must either be of that specific capsule type, or of a capsule type that inherits from it. @@ -1978,7 +1976,7 @@ Part In a fixed part capsule instances are created automatically when the container capsule is created, and destroyed when the container is destroyed. Fixed parts by default have multiplicity 1. Such a part will always contain one and only one instance of the capsule that types the part. Example -You can find a sample application that has a fixed part with a multiplicity here. +You can find a sample application that has a fixed part with a multiplicity here. 2) Optional part In an optional part capsule instances don't have a strong lifetime relationship with the container capsule as is the case for fixed parts. The capsule instances can be created programmatically using a Frame port at some point after the container capsule has been created, and they can be destroyed before the container capsule is destroyed. However, at the latest they will be automatically destroyed when the container is destroyed. Optional parts by default have multiplicity 0..1. This means that they may either contain zero or one capsule instance at any point in time. The presence of zero in the multiplicity is what makes the part optional. Here is C++ code for creating a capsule instance in an optional part (also known as incarnating the part) and then immediately destroying it: @@ -1992,7 +1990,7 @@ Part If the instantiated capsule has a constructor you need to use a capsule factory for providing the constructor arguments (either provided when doing the incarnation as shown here or specified on the part as described here). Example -You can find a sample application that creates and destroys capsule instances in optional parts here. +You can find a sample application that creates and destroys capsule instances in optional parts here. 3) Plugin part A plugin part is similar to an optional part in that it is populated by capsule instances programmatically. However, the capsule instances are not created in the plugin part but instead imported into the plugin part from another part. Typically such a capsule instance is first created into an optional part, and then at some later point in time imported into a plugin part. Later it can be deported (i.e. removed) from the plugin part and perhaps imported into another plugin part. This makes it possible to create very dynamic composite structures where the same capsule instance can play different roles in different parts over time. Moving a capsule instance by deporting it from one plugin part and then importing it in another plugin part is more efficient than destroying the capsule instance in one optional part and then creating another capsule instance in another optional part. Plugin parts are typically used together with unwired ports. In general it's possible to import a capsule instance into more than one plugin part at the same time, but it can only be imported if its ports are not already bound in its current location. Plugin parts by default have multiplicity 0..1. @@ -2023,7 +2021,7 @@ Part with Capsule Factory rt::create Defines how to create an instance of the capsule. For example, which constructor arguments to pass, which thread to use for running the created capsule instance, at which index to insert the capsule instance into the part (in case it has multiplicity > 1) etc. rt::destroy Defines how to destroy an instance of the capsule. By default it's destroyed using the delete operator. -Here is an example where a part defines a capsule factory that specifies a create function. The create function gets the mandatory constructor parameters rtg_rts and rtg_ref as arguments, as well as an index argument that specifies the index where the created capsule instance would be inserted by default. +Here is an example where a part defines a capsule factory that specifies a create function. The create function gets the mandatory constructor parameters rtg_rts and rtg_ref as arguments, as well as an index argument that specifies the index where the created capsule instance will be inserted. part engine : Engine [[rt::create]] ` return new Engine_Actor(rtg_rts, rtg_ref, true /* custom constructor arg */); @@ -2032,12 +2030,12 @@ Part with Capsule Factory Note that you may want to create a capsule factory for a part also for other reasons than passing custom constructor parameters. For example, you may want to change the default thread (RTController*) that should execute the created capsule instance, or you may want to instantiate an inherited capsule rather than the capsule that types the part. Example -You can find a sample application here where a fixed part uses an rt::create code snippet for invoking a custom capsule constructor. +You can find a sample application here where a fixed part uses an rt::create code snippet for invoking a custom capsule constructor. State Machine State machines are used for specifying the behavior of capsules. It is also possible to provide a state machine for a passive class; see Class with State Machine for more information about that. In this chapter we focus on state machines in capsules. A state machine consists of states and transitions. During its lifetime a capsule instance transitions between the various states of its state machine, as a consequence of receiving events on its behavior ports. When transitioning between two states one or several code snippets may execute. Such code may for example send events to other capsule instances, something that may cause transitions to execute in their state machines. -A state machine may also have pseudo states, which just like states may be connected with transitions, but that unlike states are not places where the state machine should stay for some time. For example, most pseudo states like junctions and entry/exit points merely act as connection points that make it possible to execute more than one transition when transitioning between two states. The notable exception is the choice in which actually the state machine may get stuck for ever, but that would be an error situation that should not happen in a correctly designed state machine. +A state machine may also have pseudo states, which just like states may be connected with transitions, but that unlike states are not places where the state machine should stay for some time. For example, most pseudo states like junctions and entry/exit points merely act as connection points that make it possible to execute more than one transition when transitioning between two states. The notable exception is the choice in which actually the state machine may get stuck for ever, but that would be an error situation that should not happen in a correctly designed state machine. State The states of a state machine are the places where the state machine may stay for some time while waiting for a message to arrive that potentially can cause the state machine to transition to another state. States should have names that describe what is happening while the state machine stays there, or what has happened for the state machine to arrive there. For example, "WaitForInit", "Processing" or "Terminated". By convention state names start with uppercase. You can declare multiple states on the same line using a comma-separated list of state names. It can be good to write a comment in front of the state name, if you want to elaborate more on its meaning than what is possible in the name itself. Here is an example of a state machine with some states: @@ -2057,7 +2055,7 @@ State States may be nested to create a hierarchical state machine. Entry and Exit Action A state may have an entry and/or exit action which is a code snippet that runs whenever the state is entered and/or exited. -state Walk { +state Walking { entry ` server.walk().send(); @@ -2070,11 +2068,11 @@ Entry and Exit Action Example -You can find a sample application where a state has an entry and exit action here. +You can find a sample application where a state has an entry and exit action here. Transition A transition connects a source state (or pseudo state) to a target state (or pseudo state). When a capsule instance handles a message that was received on one of its behavior ports, one or several transitions may execute. -It's not required to give a name to a transition, but it's possible and often makes the state machine easier to understand. At least triggered transitions (i.e. transitions where the source is a state) should have a name. A transition name can be choosen to describe what needs to have happened for the transition to execute, for example "requestReceived", "timeout" etc. By convention transition names start with lowercase and use camelCase if the name consists of multiple words. +It's not required to give a name to a transition, but it's possible and often makes the state machine easier to understand. At least triggered transitions (i.e. transitions where the source is a state) should have a name. A transition name can be choosen to describe what has happened when the transition executes, for example "requestReceived", "timeout" etc. By convention transition names start with lowercase and use camelCase if the name consists of multiple words. A triggered transition has one or several triggers which define when the transition can be triggered. Each trigger specifies a port and an event. The trigger can only trigger its transition if the received message is an instance of the specified event, and was received on the specified port. In addition it's possible to provide guard conditions that must be fulfilled for the trigger to trigger its transition. Such a guard condition can be specified for the transition, but also for each individual trigger. Here is an example of a capsule state machine with two triggered transitions requestReceived and timeout. It also contains an initial transition that has no name. capsule MyCap { @@ -2127,7 +2125,7 @@ Initial Transition Note that the const_rtdata property can be set on any transition, not just the initial transition. It allows the data received when the transition is triggered to be modified. Example -You can find a sample application that has transitions with the property const_rtdata unset here. +You can find a sample application that has transitions with the property const_rtdata unset here. Internal Transition An internal transition doesn't change the active state and therefore doesn't have a target state. An internal transition is always a triggered transition. You define an internal transition inside the state to which it belongs. Here is an example: @@ -2141,22 +2139,9 @@ Internal Transition Note the usage of an asterisk (*) to specify that any event received on myPort will trigger the internal transition when the state machine is in the Done state. Such "receive-any" events can of course be used for a trigger of any transition, but can in particular be useful for internal transitions that should handle all messages received on a port that are not handled by other triggered transitions leaving substates of the state. If another event is added to the port's protocol in the future, such a trigger will handle the new event too without a need for being updated. Example -You can find a sample application that has an internal transition with a "receive-any" event trigger here. +You can find a sample application that has an internal transition with a "receive-any" event trigger here. Internal transitions are examples of so called self-transitions. To learn about other types of self-transitions see this chapter. -Frequent Transition -Sometimes you may have a state where one or a few outgoing transitions can be expected to execute much more frequently than others. You can then set a frequent property on the transition trigger that you expect will trigger the transition frequently. The Art compiler uses this information to optimize generated C++ code so that such transition triggers are evaluated before other triggers that are expected to trigger the transition less frequently. -interrupted: Working -> Stopped on [[rt::properties( - frequent=true - )]] external.interrupt - ` - // Interrupted while working... - `; - - -Note -The frequent property relies on optimization features in the C++ compiler that may or may not be available depending on which target compiler that is used. Only use frequent transitions if profiling has shown that you have a need to do this optimization. - Choice and Junction Choices and junctions are pseudo states that make it possible to split transition flows in a state machine. That is, one incoming transition may be split into multiple outgoing transitions. Which of the outgoing transitions that will execute is decided by evaluating their guard conditions. For a junction the guard conditions are evaluated already before leaving the currently active state. Only if there exists a path of transitions where all guards are fulfilled, will the active state be exited and the transitions can execute. Otherwise the state machine stays in its current state and attempts to find another path of transitions to execute. For a choice the guard conditions are evaluated after leaving the current state, when reaching the choice itself. The outgoing transition which has a fulfilled guard will execute next. @@ -2165,7 +2150,7 @@ Choice and Junction It's important that there always is an outgoing transition for a choice with a fulfilled guard condition. Otherwise the state machine will get stuck in the choice without any chance of getting out of it. The same is true if a junction is used in the initial transition. If such a junction doesn't have an outgoing transition with a fulfilled guard condition then the state machine will stay in the initial state for ever. -Choices and junctions must have names, so they can be referenced as the source or target of transitions. You can choose to use a name that gives a hint about what conditions that are checked in the guards of the outgoing transitions. For example, isEnabled for a choice that checks a boolean condition and checkValue when the condition has some other type. If you follow this approach you can then name the outgoing transitions accordingly. For example true and false for a choice that checks a boolean condition. By convention choice and junction names start with lowercase and use camelCase if consisting of multiple words. Sometimes it may be difficult to come up with a good name and in that case you can choose something short and "technical" like j1, check1 etc. +Choices and junctions must have names, so they can be referenced as the source or target of transitions. You can choose to use a name that gives a hint about what conditions that are checked in the guards of the outgoing transitions. For example, isEnabled for a choice that checks a boolean condition and checkValue when the condition has some other type. If you follow this approach you can then name the outgoing transitions accordingly. For example true and false for a choice that checks a boolean condition. By convention choice and junction names start with lowercase and use camelCase if they consist of multiple words. Sometimes it may be difficult to come up with a good name and in that case you can choose something short and "technical" like j1, check1 etc. Below is an example of a state machine containing a choice and a junction. statemachine { state First, Second, Third; @@ -2225,11 +2210,11 @@ Choice and Junction When multiple triggered transitions converge into a common transition as in the example above, and the events that trigger those transitions have a data parameter, it's best to access that data in the triggered transitions and not in the common transition. This is especially true if the types of those data parameters are not the same, because in that case the rtdata parameter of the function generated for the common transition will be untyped (void*). You can of course still cast it to another type, but that requires that you can know which of the triggered transitions that were triggered. It's therefore better to access the data in the triggered transitions and if necessary store it in a capsule variable which you then can access in the common transition if needed. Example -You can find a sample application that demonstrates usage of a choice and junction here. +You can find a sample application that demonstrates usage of a choice and junction here. Hierarchical State Machine A state machine is hierarchical if it contains at least one composite state, i.e. a state with a nested state machine. A transition that is triggered in the enclosing state machine (i.e. the state machine that contains the composite state) should enter a composite state by specifying an entry point of the composite state as the target. In the nested state machine another transition can connect that entry point to a state in the nested state machine. A transition in the nested state machine may specify an exit point of the composite state as the target. In the enclosing state machine another transition can connect that exit point to a state in the enclosing state machine. -Entry and exit points are pseudo states that need to be named. The names can be chosen to give a hint about when the composite state is entered or exited through them, for example systemStarted or errorDetected. If you want you can prefix the names with ep or ex. It's also common to use short and "technical" names like ep1 or ex1 if a more descriptive name doesn't make sense. By convention entry and exit point names start with lowercase and use camelCase if consisting of multiple words. +Entry and exit points are pseudo states that need to be named. The names can be chosen to give a hint about when the composite state is entered or exited through them, for example systemStarted or errorDetected. If you want you can prefix the names with ep or ex. It's also common to use short and "technical" names like ep1 or ex1 if a more descriptive name doesn't make sense. By convention entry and exit point names start with lowercase and use camelCase if they consist of multiple words. It's also possible to directly enter a composite state without using an entry point. In this case the behavior will depend on whether the composite state is entered for the first time or not. If it is for the first time, the initial transition of the nested state machine will execute after the transition that targets the composite state has executed. Otherwise the composite state will instead be entered using deep history, i.e. by activating the state in the nested state machine that was most recently active (and recursively if that state again is a composite state). Note @@ -2256,18 +2241,18 @@ Hierarchical State Machine Note that a dot (.) is used as scope resolution operator, to make it possible to reference an entry or exit point from the enclosing state machine. Inside the nested state machine the entry and exit points are directly accessible without use of the scope resolution operator (using it there would be an error). -It is possible to only connect an entry point on the "outside". Entering such an entry point will behave in the same way as entering the composite state without using an entry point (see above). It's therefore not recommended. In the same way it's possible to exit a composite state using an exit point that only is connected on the "inside". In this case the composite state is not exited and instead the previously active substate again becomes active (recursively, just like for deep history). This is also not recommended, unless the transition is a local transition. +It is possible to only connect an entry point on the "outside". Entering the state via such an entry point will behave in the same way as entering the composite state without using an entry point (see above). It's therefore not recommended. In the same way it's possible to exit a composite state using an exit point that only is connected on the "inside". In this case the composite state is not exited and instead the previously active substate again becomes active (recursively, just like for deep history). This is also not recommended, unless the transition is a local transition. Example -You can find a sample application that contains a composite state with an entry and exit point here. +You can find a sample application that contains a composite state with an entry and exit point here. -Just like a junction an entry or exit point can have multiple outgoing transitions. Guards on those transitions decide which one to execute, and are evaluated before leaving the current state. Therefore, the same recommendations as for guard conditions of junctions apply. +Just like a junction, an entry or exit point can have multiple outgoing transitions. Guards on those transitions decide which of them to execute, and are evaluated before leaving the current state. Therefore, the same recommendations as for guard conditions of junctions apply for entry and exit points. Deep History Every nested state machine has an implicit pseudo state with the name history* (in state diagrams it's shown as H* to save space). It can be used as a target for any transition inside the nested state machine. When it is reached, the state machine will restore the previously active substate. If that state again is a composite state, its previously active substate will also be restored. This goes on recursively for all nested state machines (which is why it's called a deep history). In the example above we can see that the transition from ep2 targets the deep history pseudo state. This means that if the Nested substate is active and then the transition to ex1 gets triggered, the state Other becomes active. If then the transition to ep2 gets triggered the CompositeState will be entered using deep history so that the Nested substate will again become active. Example -You can find a sample application that uses the deep history pseudo state here. +You can find a sample application that uses the deep history pseudo state here. Local Transition A transition in a nested state machine that connects an entry point and exit point on the same state, and these entry/exit points only are connected on the "inside", is a local transition. A local transition is a self-transition that behaves something in between an internal transition and a regular (a.k.a. external) self-transition. An internal transition defined on a composite state handles a message without exiting neither that composite state, nor any of its substates. However, a local transition will exit the substates, run the effect code, and then enter the substates again. But the composite state itself will not be exited and entered. An external self-transition on the other hand will exit both the composite state and all active substates recursively, run the effect code, and then enter these states again. @@ -2322,7 +2307,7 @@ Local Transition 7) Nested2 is entered. Example -You can find a sample application that has a local transition here. +You can find a sample application that has a local transition here. Class with State Machine Art allows you to create passive classes with state machines. This can be an alternative to using a capsule in case you only need a passive stateful data object, and don't need the ability to send events to it, or to let it execute in its own context. A class with a state machine is more lightweight than a capsule at runtime. @@ -2359,9 +2344,6 @@ Class with State Machine The initial transition cannot access initialization data as can a capsule's initial transition. Instead you can define one or several constructors for the class with parameters needed for passing initialization data when the class-with-statemachine instance is created. See Constructor for more information. -Frequent transitions are not supported. - - The state machine can be hierarchical but the deep history pseudo state is not supported. Instead the shallow history pseudo state can be used. @@ -2420,7 +2402,7 @@ Inheritance Capsule Inheritance A capsule can inherit from another capsule. Only one base capsule is allowed; multiple inheritance is not supported for capsules. In addition a capsule can inherit from any number of C++ classes (or structs). The derived capsule is type compatible with the base capsule in the sense that if you have a capsule part typed by the base capsule, you can at runtime incarnate it with instances of the derived capsule. -Capsule inheritance has multiple dimensions. One dimension is the usual C++ inheritance between classes (remember that a capsule is an active class). In this dimension it is for example possible to redefine (a.k.a override) a virtual member function defined in the base capsule or in another base C++ class. But there is also a second dimension where the state machine of the derived capsule will implicitly inherit from the state machine of the base capsule. This makes it possible to redefine transitions and states. For example, a redefining transition in a derived capsule can change the effect code, the guard condition or the target state or pseudo state. And a redefining state in a derived capsule can change the entry or exit action, as well as any substate or subtransition in case the state is composite and has a nested state machine. It's also possible to completely exclude a state or a transition, either in the top capsule state machine, or in a nested state machine. +Capsule inheritance has multiple dimensions. One dimension is the usual C++ inheritance between classes (remember that a capsule is an active class). In this dimension it is for example possible to redefine (a.k.a override) a virtual member function defined in the base capsule or in another base C++ class. But there is also a second dimension where the state machine of the derived capsule will implicitly inherit from the state machine of the base capsule. This makes it possible to redefine transitions and states. For example, a redefining transition in a derived capsule can change the effect code, the guard condition or the target state or pseudo state. And a redefining state in a derived capsule can change the entry or exit action, as well as any substate or subtransition in case the state is composite and has a nested state machine. It's also possible to completely exclude a state or a transition, either in the capsule's top state machine, or in a nested state machine. Below is an example of a capsule D that inherits from another capsule B. In addition the capsule D inherits from two C++ classes IDataManager and IController. capsule B { [[rt::decl]] @@ -2473,7 +2455,7 @@ Capsule Inheritance In the example we can see that D overrides functions from the base C++ classes that are assumed to be virtual (or pure virtual). For brevity the implementations of these functions have been omitted but would be placed in the rt::impl code snippet. D also overrides a virtual function doSmth() from the base capsule B. The implementation of that function (also placed in the rt::impl code snippet) calls the inherited function by using a macro SUPER. This macro expands to the name of the base capsule class. Using this macro, instead of the base capsule class name, makes it easier to copy/paste code from one capsule to another. Example -You can find a sample application where a capsule inherits from both another capsule and from C++ classes here. +You can find a sample application where a capsule inherits from both another capsule and from C++ classes here. We can also see an example of a state machine redefinition. The initial transition _Initial of B's state machine is redefined in D's state machine so that it targets state DS instead of state BS. In the state diagram of D the state BS and the initial pseudo state are drawn with gray color and dashed outline, to show that they are inherited. The transition _Initial is also drawn with dashed outline, but with a different line style ("dash-dot-dot"), and with a green label to show that it's redefining the inherited initial transition. The state BS2 is excluded in D's state machine. In state diagrams excluded elements are shown with a "crossed" background. @@ -2483,10 +2465,10 @@ Capsule Inheritance Example You can find sample applications where capsule state machines are inherited here: -Redefining a transition effect -Redefining a transition trigger -Redefining a transition guard -Excluding a transition +Redefining a transition effect +Redefining a transition trigger +Redefining a transition guard +Excluding a transition Capsule inheritance also has a third dimension, which relates to its structure. Parts and ports defined in the base capsule are inherited by the derived capsule. Just like for states and transitions, it's possible to redefine or exclude a part or a port. A redefining port can change the type (i.e. protocol), multiplicity and the notification property of the redefined port. A redefining part can change the type, multiplicity and kind (fixed, optional or plugin) of the redefined part. @@ -2517,7 +2499,7 @@ Capsule Inheritance Example -You can find a sample application where parts are inherited here. +You can find a sample application where parts are inherited here. Class Inheritance A class with state machine can inherit from other classes with state machines, or from C++ classes (or structs). Multiple inheritance is supported. @@ -2560,48 +2542,10 @@ Protocol Inheritance Example You can find sample applications using protocol inheritance here: -A derived protocol inherits events from a base protocol -A derived protocol redefines the parameter type of an inherited event +A derived protocol inherits events from a base protocol +A derived protocol redefines the parameter type of an inherited event
+ - + + + - - The Art Language -Art is a language for developing stateful and event-driven realtime applications. By stateful we mean that the application consists of objects whose behavior can be described with state machines. By event-driven we mean that these objects communicate with each other by sending events, which can cause their state machines to transition from one state to another. +Art is a language for developing stateful and event-driven realtime applications. By stateful we mean that the application consists of objects whose behavior can be described with state machines. By event-driven we mean that these objects communicate with each other by sending events, which can cause their state machines to transition from one state to another when received. The Art language provides high-level concepts not directly found in the C++ language. All these high-level concepts are transformed into C++ code by the Art compiler. Generated code uses a run-time library known as the TargetRTS (Target RunTime System). The TargetRTS is a C++ library that acts as a layer between the generated code and the underlying platform (hardware, operating system etc) on which the realtime application runs. Art is well suited for describing both the behavior and structure of a realtime application, but it uses C++ as expression and action language. C++ is also used for declaring types, variables, functions etc. As a rule of thumb, Art uses C++ for everything where C++ is a good fit, and only provides new language concepts where no appropriate constructs exist in C++. This means that if you already know C++, you can quickly learn Art too, and existing C++ code you have already written can be used in your Art application. Note that the translation of Art to C++ also involves analysis of the C++ code that is present in the Art files. The code generator supports certain C++ extensions in such embedded C++ code and will "expand" them to C++ code as part of code generation for an Art file. Concepts and Terminology -In Art the concept of a capsule is central. A capsule is like a C++ class, but with a few differences and extensions. A C++ class is passive in the sense that a caller can access its public member functions and variables at any time. Hence a C++ object always executes in the context of the caller, and when a member function is called, the caller is blocked until it returns. A capsule, however, is active and has its own execution context. This means that we never call a capsule member function or access a capsule member variable from outside the capsule itself. Instead we communicate with the capsule by sending events to it. Each capsule has a queue of events it has received and the events will be dispatched to the capsule one by one. The sender of the event is not blocked, as the event will be handled by the capsule asynchronously when it is later dispatched. -The picture below shows 3 capsule instances each holding a queue with events that have been received, but not yet dispatched. Note that this picture is conceptual. In a real implementation several performance optimizations are applied, for example it's common to let a single thread drive more than one capsule instance, and several capsule instances can share a common event queue. But from a conceptual point of view each capsule has its own queue of events that are waiting to be dispatched to it. Events have a priority which determines how they are ordered in the queue. Events with high priority are placed before events with lower priority, and if two events have the same priority they are ordered according to when they arrive. +In Art the concept of a capsule is central. A capsule is like a C++ class, but with a few differences and extensions. A C++ class is passive in the sense that a caller can access its public member functions and variables at any time. Hence a C++ object always executes in the context of the caller, and when a member function is called, the caller is blocked until the function call returns. A capsule, however, is active and has its own execution context. This means that we never call a capsule member function or access a capsule member variable from outside the capsule itself. Instead we communicate with the capsule by sending events to it. Each capsule instance has a queue of events it has received and those events will be dispatched to the capsule instance one by one. The sender of the event is not blocked, as the event will be handled by the capsule instance asynchronously when it is later dispatched. +The picture below shows 3 capsule instances each holding a queue with events that have been received, but not yet dispatched. Note that this picture is conceptual. In a real implementation several performance optimizations are applied, for example it's common to let a single thread drive more than one capsule instance, and several capsule instances can share a common event queue. But from a conceptual point of view each capsule instance has its own queue of events that are waiting to be dispatched to it. Events have a priority which determines how they are ordered in the queue. Events with high priority are placed before events with lower priority, and if two events have the same priority they are ordered according to when they arrive. A capsule may have ports. A port is typed by a protocol which defines the events that may be sent in to the port (these are known as in-events), as well as the events the capsule itself may send out through the port for others to receive (these are called out-events). Ports can be used both for internal and external communication. A port used for external communication is called a service port. Together, the service ports constitute the communication interface of the capsule, and decide what "services" the capsule provides for other capsules to use. A simple capsule which only handles a small number of events, may be able to handle all these events using a single state machine. However, when new ports are added (or new events in protocols typing existing ports), the capsule interface grows and the state machine has to grow with it, since there will be more events for it to handle. Eventually a point is reached where it will not be practical for a capsule to handle any more events in its own state machine, because it has grown too large or complex. If not before, this is the time to define a composite structure for the capsule. A composite structure is created by decomposing a capsule using capsule parts. A capsule part (or, for simplicity, just part) is typed by another capsule and is a way for a capsule to delegate some of its responsibilities to other capsules. Such a decomposition is purely an implementation detail that is not visible from the outside of the capsule. When you send an event to a capsule you cannot know if the capsule will handle the event itself, or if it will forward the event to another capsule typing one of its capsule parts. The ability to decompose a capsule into parts is important for managing complexity. When a capsule has grown too big and complex you can decompose it into capsule parts without changing the communication interface of the capsule. -Ports of capsules typing capsule parts are connected to each other by means of connectors. A connector is a conceptual construct for showing how events are routed in the internal structure of a capsule. At run-time connectors don't exist, and ports are directly connected to each other. Because of this, it's not mandatory to use connectors. You can also choose to dynamically connect (and disconnect) ports at run-time. Although this provides for more flexibility, it has the drawback of making it impossible to statically visualize the communication paths of a capsule. Ports that connect statically to other ports via connectors are called wired ports. Ports that are connected dynamically without use of static connectors are called unwired ports. +Ports of capsules typing capsule parts are connected to each other by means of connectors. A connector is a conceptual construct for showing how events are routed in the composite structure of a capsule. At run-time connectors don't exist, and ports are directly connected to each other. Because of this, it's not mandatory to use connectors. You can also choose to dynamically connect (and disconnect) ports at run-time. Although this provides for more flexibility, it has the drawback of making it impossible to statically visualize the communication paths of a capsule. Ports that connect statically to other ports via connectors are called wired ports. Ports that are connected dynamically without use of static connectors are called unwired ports. The picture below shows the structure of a capsule Top which consists of two capsule parts ping and pong each holding a capsule instance (a Pinger capsule and a Ponger capsule respectively). The connector between the wired ports p on these capsules makes it possible for these capsules to communicate with each other. Communication can also happen using the unwired ports q1 and q2 if they are connected at run-time. The picture also shows that the capsule Ponger is further decomposed using a capsule part inner. All events sent to port p of Ponger will be further routed to port i of the Internal capsule. -Regardless if ports are statically connected by connectors (wired ports), or dynamically connected at run-time (unwired ports), they must be compatible with each other. This means that the out-events of one port must match the in-events of the other port, for the ports to be possible to connect. This constraint ensures that events are never lost when traveling between two connected ports. To make it possible to describe the events that may travel between two connected ports using a single protocol, one of the ports can be declared as conjugated. For a conjugated port the meaning of in-events and out-events are swapped, so that the in-events are the events that may be sent out through the port, and the out-events are the ports that may be sent to the port. In the picture above port q1 is non-conjugated () while port q2 is conjugated (). +Regardless if ports are statically connected by connectors (wired ports), or dynamically connected at run-time (unwired ports), they must be compatible with each other. This means that the out-events of one port must match the in-events of the other port, for the ports to be possible to connect. This constraint ensures that events are never lost when traveling between two connected ports. To make it possible to describe the events that may be sent between two connected ports using a single protocol, one of the ports can be declared as conjugated. For a conjugated port the meaning of in-events and out-events are swapped, so that the in-events are the events that may be sent out through the port, and the out-events are the ports that may be sent to the port. In the picture above port q1 is non-conjugated () while port q2 is conjugated (). Both capsule parts and ports may have multiplicity. You can think about a capsule part with multiplicity > 1 as an array that holds capsule instances at run-time. In the same way you can think about a port with multiplicity > 1 as an array that holds connections to port instances at run-time. The multiplicity of ports and parts must match when connecting two ports with each other. Once again, this constraint ensures that events will not be lost when traveling between the connected ports at run-time. The picture below shows a capsule with a part and a port that both have multiplicity > 1. In structure diagrams such parts and ports are shown as "stacked boxes". -In addition to regular C++ member functions a capsule may have a state machine as its behavior. A state machine describes how an instance of the capsule may move between different states through its life-time. A transition that connects a source state with a target state may be triggered when an event from a capsule's event queue is dispatched. Several conditions must hold true for the transition to trigger. For example, the event must match a trigger that specifies the expected type of event and the port on which it was received. It's also possible to associate a boolean guard condition with the transition and/or with the trigger which must be true for the transition to trigger. A transition may have an effect, which is a piece of C++ code that executes when the transition gets triggered. -The picture below shows a state machine containing three states and three transitions. The presence of transition guard code is shown with a yellow dot and the presence of transition effect code is shown with a blue dot. Both these are C++ code snippets that are embedded in the Art file. +In addition to regular C++ member functions a capsule may have a state machine as its behavior. A state machine describes how an instance of the capsule may move between different states through its life-time. A transition that connects a source state with a target state may be triggered when a received event from a capsule's event queue is dispatched. Several conditions must hold true for the transition to trigger. For example, the event must match a trigger that specifies the expected type of event and the port on which it was received. It's also possible to associate a boolean guard condition with the transition and/or with the trigger which must be true for the transition to trigger. A transition may have an effect, which is a piece of C++ code that executes when the transition gets triggered. +The picture below shows a state machine containing a few states and transitions. The presence of transition guard code is shown with a yellow dot and the presence of transition effect code is shown with a blue dot. Both these are C++ code snippets that are embedded in the Art file. -When a capsule instance is created (this is sometimes referred to as capsule incarnation), it's state machine starts to execute by triggering the transition that goes out from the initial state (the big blue circle in the above diagram). Each state machine must have exactly one such initial state with an outgoing transition. Since this initial transition is triggered automatically when the capsule instance is created it cannot have any constraints like mentioned above. The initial transition is an example of a non-triggered transition since it cannot have triggers. -The path from the source state to the target state can sometimes consist of more than one transition. In that case only the first of these is a triggered transition that may have triggers that specify when it will trigger. Once the first transition in this path has triggered, subsequent non-triggered transitions will always execute, one by another according to how they are connected in the state machine. However, also non-triggered transitions (with the exception of the initial transition) may have guards. Such guards are usually evaluated before the triggered transition triggers to ensure that they all are enabled, so that it's guaranteed that the target state can be reached. There is one exception to this rule, for transitions that leave a choice. Such guards are only evaluated once the choice has been reached to dynamically decide which outgoing transition to take next. This also means that guards of such transitions must be mutually exclusive, or there is a risk that the state machine will get stuck in the choice. +When a capsule instance is created (this is sometimes referred to as capsule incarnation), it's state machine starts to execute by triggering the transition that goes out from the initial state (the circular blue symbol to the left in the above diagram). Each state machine must have exactly one such initial state with an outgoing transition. Since this initial transition is triggered automatically when the capsule instance is created it cannot have constraints such as triggers and guard conditions. The initial transition is an example of a non-triggered transition since it cannot have triggers. +The path from the source state to the target state can sometimes consist of more than one transition. In that case only the first of these is a triggered transition that may have triggers that specify when it will trigger. Once the first transition in this path has triggered, subsequent non-triggered transitions will always execute, one by one according to how they are connected in the state machine. However, also non-triggered transitions (with the exception of the initial transition) may have guards. Such guards are usually evaluated before the triggered transition triggers to ensure that they all are enabled, so that it's guaranteed that the target state can be reached. There is one exception to this rule, for transitions that leave a choice. Such guards are only evaluated once the choice has been reached to dynamically decide which outgoing transition to take next. This also means that guards of such transitions must be written so that at least (and at most) one outgoing transition is enabled, or there is a risk that the state machine will get stuck in the choice. In the state machine shown below the transitions t2 and t5 are triggered transitions, while other transitions are non-triggered. Transition t5 can only be triggered if either the guard of t7 or t6 is true, while t2 can be triggered even if neither the guard of t3 nor t4 is true. The target of transition t5 is a junction which is used for either splitting or merging transition paths depending on evaluated guard conditions. A state may be decomposed by a sub state machine. Such a state is called a composite state and a state machine that has composite states is called a hierarchical state machine. Transitions enter a composite state through an entry point and exit it through an exit point. @@ -1461,13 +1454,13 @@ Concepts and Terminology A state may have an entry action and/or exit action which is a C++ code snippet that gets executed whenever the state is entered or exited. Note that state entry actions for nested states also run when those states are entered because of a deep history. In state diagrams the presence of entry and/or exit actions are shown by icons just below the state name. In the state machine shown below state S1 has an entry action, state S2 has an exit action and state S3 has both an entry and an exit action. -A transition where the source and target state is the same state is called a self-transition. A special kind of self-transition is an internal transition, which is a transition that when triggered doesn't leave the current state. Hence, when an internal transition is triggered the active state configuration remains unchanged, and neither the entry nor exit action of the state gets executed. In the state machine shown below the state has two self-transitions; t which is a regular self-transition (a.k.a. external self-transition) and it which is an internal transition. Since a state may have a large number of internal transitions they are not shown inside the state symbol, but if you select the state symbol you can see them in the Properties view. An icon is shown on those states that contain internal transitions. +A transition where the source and target state is the same state is called a self-transition. A special kind of self-transition is an internal transition, which is a transition that when triggered doesn't leave the current state. Hence, when an internal transition is triggered the active state configuration remains unchanged, and neither the entry nor exit action of the state gets executed. In the state machine shown below the state has two self-transitions; t which is a regular self-transition (a.k.a. external self-transition) and it which is an internal transition. Since a state may have a large number of internal transitions they are not shown inside the state symbol, but if you select the state symbol you can see them in the Properties view. An icon is shown in the upper right corner of states that contain internal transitions. State machines can not only be defined for capsules but also for regular classes. This can be useful if you want a plain passive C++ class to have a state machine. Contrary to a capsule a class may not have ports and doesn't execute in its own context. It's therefore common to associate such a class with a capsule that it can use for sending events through its ports. Transitions of a passive class state machine are triggered by calling trigger operations on the class. Such operations have no code, but just trigger transitions in the class state machine. The realtime application needs to designate one capsule as the top capsule. This is done in the transformation configuration, which is a file containing all the properties used for building the application (e.g. code generator options, compiler settings etc.). There is no language construct in Art for defining a top capsule; any capsule that you define can act as the top capsule. However, in practise you typically decide at an early stage which capsule that will be the top capsule. The top capsule is the entry point of the realtime application. When it starts to execute one instance of the top capsule will be automatically created, and its state machine starts to execute. If you build a library rather than an executable you don't have a top capsule. Embedded C++ Code -Art uses C++ as action and expression language. It also uses C++ for defining types, variables and functions. A C++ code snippet can be embedded into Art at many places by enclosing it with backticks. Here is an example of how to write the code that should execute when a transition triggers: +Art uses C++ as action and expression language. It also uses C++ for defining types, variables and functions. A C++ code snippet can be embedded into an Art file at many places by enclosing it with backticks. Here is an example of how to write the code that should execute when a transition triggers: S1 -> S2 on timer.timeout ` std::cout << "Hello World!" << std::endl; @@ -1564,7 +1557,7 @@ Textual and Graphical Notations Art elements are mostly edited using their textual notation, but diagrams also provide some editing capabilities. However, all edit commands performed from a diagram are actually mapped to corresponding textual modifications of the Art file. Editing from a diagram is therefore simply an alternative, and sometimes more convenient way, of editing the textual Art file. Syntax -Art uses a syntax that should look familiar to developers with knowledge about languages like C++ and Java. +Art uses a syntax that should be familiar to developers with knowledge about languages like C++ and Java. Declarations are terminated with a semicolon ; When multiple elements are declared in the same language construct commas , are used for separating the elements @@ -1750,7 +1743,7 @@ Capsule Constructor Example -You can find a sample application that uses a capsule constructor here. +You can find a sample application that uses a capsule constructor here. Capsule Destructor The destructor of a capsule frees the memory used for representing its states, ports etc. You cannot provide your own code to the destructor implementation. However, the RTActor class, which is the base class of every capsule class, provides a virtual function _predestroy() which you can override in your capsule. This function gets called just before the capsule instance is destroyed and is the place where you should put code that cleans up resources allocated by the capsule. Here is an example: @@ -1769,7 +1762,7 @@ Capsule Destructor It's important to remember to invoke the inherited function by calling SUPER::_predestroy(). Example -You can find a sample application with a capsule that overrides _predestroy() here. +You can find a sample application with a capsule that overrides _predestroy() here. Protocol and Event A protocol defines events that may be sent in to a port (so called in-events) and events that may be sent out from the same port (so called out-events). By grouping events into protocols, and then typing ports with such protocols, we can precisely define which events the capsule may send and receive through that port. @@ -1818,7 +1811,7 @@ Protocol and Event Port A port defines a named point of communication for a capsule. A port is typed by a protocol which defines the events that may be sent in to (in-events) and out from (out-events) the port. A port may be conjugated in order to swap the meaning of in-events and out-events. That is, a capsule may send out-events on its non-conjugated ports, but in-events on its conjugated ports. A port becomes conjugated if you add a tilde (~) after its name. Ports are often named to describe the role or purpose of the communication that takes place on them. By convention names of ports start with lowercase and use camelCase if the name consists of multiple words. -Here is an example of a capsule with a few ports. Note that RTist in Code provides several predefined protocols that can be used right away, for example Timing. Also note that you can declare multiple ports on a single line if the ports are of the same kind (p1 and p2 below are both service ports). +Here is an example of a capsule with a few ports. Note that Code RealTime provides several predefined protocols that can be used right away, for example Timing. Also note that you can declare multiple ports on a single line if the ports are of the same kind (p1 and p2 below are both service ports). capsule Machine { service port control : MachineEvents; behavior port timer : Timing; // predefined Timing protocol @@ -1840,8 +1833,9 @@ Port Example -You can find a sample application that sends events on ports with and without data here. +You can find a sample application that sends events on ports with and without data here. +Note that send() is not the only function you can call. For example, you can call invoke() if you want to wait until the receiver has received and replied to the event. This is useful for implementing synchronous communication between capsules. Port Multiplicity At run-time an instance of a port can be connected to a port instance on another capsule. Such connections is what make a sent event be routed from the port on which it is sent, through a number of non-behavior ports, until it finally reaches a behavior port. By default a port has single multiplicity (1) meaning that at most one such connection can be established. However, you can specify a non-single multiplicity for a port to allow for more connections to be created at run-time. In the example below a Server capsule has a port with multiplicity 100. At run-time an instance of that Server capsule can be connected to 100 different client ports, each of which can send events to the server. @@ -1861,7 +1855,7 @@ Port Multiplicity }; Notification Port -Every protocol contains two implicit events rtBound and rtUnbound. A port can choose to receive those events whenever a connection for the port is established (rtBound) or dropped (rtUnbound) at run-time. Declare a port as a notification port to receive these events. +Every protocol contains two implicit events rtBound and rtUnbound. A port can choose to receive those events whenever a connection for the port is established (rtBound) or dropped (rtUnbound) at run-time. Declare a port as a notification port to receive these events. capsule Server { service notify port clients : ComEvents[100]; @@ -1904,7 +1898,7 @@ Unwired Port registration specifies when an unwired port should be registered registration_name specifies the service name with which the port should be registered -If you choose to register an unwired port programmatically (using the TargetRTS functions registerSPP and registerSAP) you decide at registration time whether the port should be an SAP or SPP port. However, if you choose to instead let the port be registered automatically you need to declare the port as either a subscribe (SAP) or publish (SPP) port. Here is the same example again, but now with automatic registration of the unwired ports using the service name myService: +If you choose to register an unwired port programmatically (using the TargetRTS functions registerSPP() and registerSAP()) you decide at registration time whether the port should be an SAP or SPP port. However, if you choose to instead let the port be registered automatically you need to declare the port as either a subscribe (SAP) or publish (SPP) port. Here is the same example again, but now with automatic registration of the unwired ports using the service name myService: capsule Client { subscribe behavior port sap [[rt::properties( registration_name = "myService") @@ -1922,11 +1916,15 @@ Unwired Port }; Note that the keyword unwired can be implicit when you declare a port as either a subscribe or publish port. + +Example +You can find a sample application that uses an unwired port here. + Connector Connectors describe how events are routed within a capsule by connecting ports in its composite structure. They make it possible to see in a structure diagram which parts of a capsule that can communicate with each other. Each connector connects exactly two ports with each other. A connected port may either be a port of the capsule itself, or a port of a capsule that types one of its capsule parts. A few constraints decide if it's possible to connect two ports: 1) The ports must be wired. Unwired ports cannot be connected. 2) The ports must be typed by the same protocol. -3) The ports' conjugations must match. If the ports are at the same level in the capsule's structure (e.g. both ports belong to capsules typing capsule parts owned by the same capsule), then the connected ports must have the opposite conjugation. This is because events that are sent out from one of the ports must be able to be received by the other port. However, if the ports are at different levels in the capsule's structure (e.g. one of them belongs to a capsule typing a capsule part owned by the capsule and the other belongs to the capsule itself), then the ports must have the same conjugation. This is because in this case events are simply delegated from one capsule to another. +3) The ports' conjugations must match. If the ports are at the same level in the capsule's structure (e.g. both ports belong to capsules typing capsule parts owned by the same capsule), then the connected ports must have the opposite conjugation. This is because events that are sent out from one of the ports must be able to be received by the other port and vice versa. However, if the ports are at different levels in the capsule's structure (e.g. one of them belongs to a capsule typing a capsule part owned by the capsule and the other belongs to the capsule itself), then the ports must have the same conjugation. This is because in this case events are simply delegated from one capsule to another. 4) If a connector is connected to a port and a part (where the port is defined on the capsule that types the part), then the port must be a service port. Only service ports are visible from the outside of a capsule. The example below shows the structure diagram of a capsule Top where we can see two connectors. capsule Top { @@ -1953,7 +1951,7 @@ Connector }; -The connector between p1 and p2 goes between two ports on the same level which is why these ports must have opposite conjugation. The connector between p2 and i goes between two ports at different levels which is why these ports must have the same conjugation. The non-behavior port p2 is a so called relay port (it just relays all events it receives to another port) and the connector between p2 and i is sometimes called a delegation connector to describe the fact that capsule Ponger uses it for delegating some of its responsiblities to the capsule Inner. Note that relay ports can be optimized away so they don't exist at run-time (i.e. at run-time port p1 can be directly connected to i). +The connector between p1 and p2 goes between two ports on the same level which is why these ports must have opposite conjugation. The connector between p2 and i goes between two ports at different levels which is why these ports must have the same conjugation. The non-behavior port p2 is a so called relay port (it just relays all events it receives to another port) and the connector between p2 and i is sometimes called a delegation connector to describe the fact that capsule Ponger uses it for delegating some of its responsiblities to the capsule Internal. Note that relay ports can be optimized away so they don't exist at run-time (i.e. at run-time port p1 can be directly connected to i). A connector doesn't have a direction, so it doesn't matter in which order it connects the two ports. That is, connecting X with Y is equivalent to connecting Y with X. Local Binding A connector can connect two behavior ports on the same capsule (with opposite conjugations). At run-time this will lead to a local binding between these ports. This enables the capsule to send events to itself which sometimes can be useful. Here is an example: @@ -1968,7 +1966,7 @@ Local Binding One reason for a capsule to send events to itself could be to split a big and long-running task into smaller tasks. By sending an event to itself after completion of each small task, the capsule can remain responsive to other events that may arrive in the meantime. When it receives the event it sent it can proceed with the next part of the big task. Example -You can find a sample application that uses a local binding here. +You can find a sample application that uses a local binding here. Part A capsule can be decomposed by means of parts (also called "capsule parts" to emphasize that they are parts of a capsule). A part is a container that at run-time may hold one or many capsule instances. The part has a multiplicity that specifies the maximum number of capsule instances it can contain at run-time, and it has a type which is another capsule. All capsule instances must either be of that specific capsule type, or of a capsule type that inherits from it. @@ -1978,7 +1976,7 @@ Part In a fixed part capsule instances are created automatically when the container capsule is created, and destroyed when the container is destroyed. Fixed parts by default have multiplicity 1. Such a part will always contain one and only one instance of the capsule that types the part. Example -You can find a sample application that has a fixed part with a multiplicity here. +You can find a sample application that has a fixed part with a multiplicity here. 2) Optional part In an optional part capsule instances don't have a strong lifetime relationship with the container capsule as is the case for fixed parts. The capsule instances can be created programmatically using a Frame port at some point after the container capsule has been created, and they can be destroyed before the container capsule is destroyed. However, at the latest they will be automatically destroyed when the container is destroyed. Optional parts by default have multiplicity 0..1. This means that they may either contain zero or one capsule instance at any point in time. The presence of zero in the multiplicity is what makes the part optional. Here is C++ code for creating a capsule instance in an optional part (also known as incarnating the part) and then immediately destroying it: @@ -1992,7 +1990,7 @@ Part If the instantiated capsule has a constructor you need to use a capsule factory for providing the constructor arguments (either provided when doing the incarnation as shown here or specified on the part as described here). Example -You can find a sample application that creates and destroys capsule instances in optional parts here. +You can find a sample application that creates and destroys capsule instances in optional parts here. 3) Plugin part A plugin part is similar to an optional part in that it is populated by capsule instances programmatically. However, the capsule instances are not created in the plugin part but instead imported into the plugin part from another part. Typically such a capsule instance is first created into an optional part, and then at some later point in time imported into a plugin part. Later it can be deported (i.e. removed) from the plugin part and perhaps imported into another plugin part. This makes it possible to create very dynamic composite structures where the same capsule instance can play different roles in different parts over time. Moving a capsule instance by deporting it from one plugin part and then importing it in another plugin part is more efficient than destroying the capsule instance in one optional part and then creating another capsule instance in another optional part. Plugin parts are typically used together with unwired ports. In general it's possible to import a capsule instance into more than one plugin part at the same time, but it can only be imported if its ports are not already bound in its current location. Plugin parts by default have multiplicity 0..1. @@ -2023,7 +2021,7 @@ Part with Capsule Factory rt::create Defines how to create an instance of the capsule. For example, which constructor arguments to pass, which thread to use for running the created capsule instance, at which index to insert the capsule instance into the part (in case it has multiplicity > 1) etc. rt::destroy Defines how to destroy an instance of the capsule. By default it's destroyed using the delete operator. -Here is an example where a part defines a capsule factory that specifies a create function. The create function gets the mandatory constructor parameters rtg_rts and rtg_ref as arguments, as well as an index argument that specifies the index where the created capsule instance would be inserted by default. +Here is an example where a part defines a capsule factory that specifies a create function. The create function gets the mandatory constructor parameters rtg_rts and rtg_ref as arguments, as well as an index argument that specifies the index where the created capsule instance will be inserted. part engine : Engine [[rt::create]] ` return new Engine_Actor(rtg_rts, rtg_ref, true /* custom constructor arg */); @@ -2032,12 +2030,12 @@ Part with Capsule Factory Note that you may want to create a capsule factory for a part also for other reasons than passing custom constructor parameters. For example, you may want to change the default thread (RTController*) that should execute the created capsule instance, or you may want to instantiate an inherited capsule rather than the capsule that types the part. Example -You can find a sample application here where a fixed part uses an rt::create code snippet for invoking a custom capsule constructor. +You can find a sample application here where a fixed part uses an rt::create code snippet for invoking a custom capsule constructor. State Machine State machines are used for specifying the behavior of capsules. It is also possible to provide a state machine for a passive class; see Class with State Machine for more information about that. In this chapter we focus on state machines in capsules. A state machine consists of states and transitions. During its lifetime a capsule instance transitions between the various states of its state machine, as a consequence of receiving events on its behavior ports. When transitioning between two states one or several code snippets may execute. Such code may for example send events to other capsule instances, something that may cause transitions to execute in their state machines. -A state machine may also have pseudo states, which just like states may be connected with transitions, but that unlike states are not places where the state machine should stay for some time. For example, most pseudo states like junctions and entry/exit points merely act as connection points that make it possible to execute more than one transition when transitioning between two states. The notable exception is the choice in which actually the state machine may get stuck for ever, but that would be an error situation that should not happen in a correctly designed state machine. +A state machine may also have pseudo states, which just like states may be connected with transitions, but that unlike states are not places where the state machine should stay for some time. For example, most pseudo states like junctions and entry/exit points merely act as connection points that make it possible to execute more than one transition when transitioning between two states. The notable exception is the choice in which actually the state machine may get stuck for ever, but that would be an error situation that should not happen in a correctly designed state machine. State The states of a state machine are the places where the state machine may stay for some time while waiting for a message to arrive that potentially can cause the state machine to transition to another state. States should have names that describe what is happening while the state machine stays there, or what has happened for the state machine to arrive there. For example, "WaitForInit", "Processing" or "Terminated". By convention state names start with uppercase. You can declare multiple states on the same line using a comma-separated list of state names. It can be good to write a comment in front of the state name, if you want to elaborate more on its meaning than what is possible in the name itself. Here is an example of a state machine with some states: @@ -2057,7 +2055,7 @@ State States may be nested to create a hierarchical state machine. Entry and Exit Action A state may have an entry and/or exit action which is a code snippet that runs whenever the state is entered and/or exited. -state Walk { +state Walking { entry ` server.walk().send(); @@ -2070,11 +2068,11 @@ Entry and Exit Action Example -You can find a sample application where a state has an entry and exit action here. +You can find a sample application where a state has an entry and exit action here. Transition A transition connects a source state (or pseudo state) to a target state (or pseudo state). When a capsule instance handles a message that was received on one of its behavior ports, one or several transitions may execute. -It's not required to give a name to a transition, but it's possible and often makes the state machine easier to understand. At least triggered transitions (i.e. transitions where the source is a state) should have a name. A transition name can be choosen to describe what needs to have happened for the transition to execute, for example "requestReceived", "timeout" etc. By convention transition names start with lowercase and use camelCase if the name consists of multiple words. +It's not required to give a name to a transition, but it's possible and often makes the state machine easier to understand. At least triggered transitions (i.e. transitions where the source is a state) should have a name. A transition name can be choosen to describe what has happened when the transition executes, for example "requestReceived", "timeout" etc. By convention transition names start with lowercase and use camelCase if the name consists of multiple words. A triggered transition has one or several triggers which define when the transition can be triggered. Each trigger specifies a port and an event. The trigger can only trigger its transition if the received message is an instance of the specified event, and was received on the specified port. In addition it's possible to provide guard conditions that must be fulfilled for the trigger to trigger its transition. Such a guard condition can be specified for the transition, but also for each individual trigger. Here is an example of a capsule state machine with two triggered transitions requestReceived and timeout. It also contains an initial transition that has no name. capsule MyCap { @@ -2127,7 +2125,7 @@ Initial Transition Note that the const_rtdata property can be set on any transition, not just the initial transition. It allows the data received when the transition is triggered to be modified. Example -You can find a sample application that has transitions with the property const_rtdata unset here. +You can find a sample application that has transitions with the property const_rtdata unset here. Internal Transition An internal transition doesn't change the active state and therefore doesn't have a target state. An internal transition is always a triggered transition. You define an internal transition inside the state to which it belongs. Here is an example: @@ -2141,22 +2139,9 @@ Internal Transition Note the usage of an asterisk (*) to specify that any event received on myPort will trigger the internal transition when the state machine is in the Done state. Such "receive-any" events can of course be used for a trigger of any transition, but can in particular be useful for internal transitions that should handle all messages received on a port that are not handled by other triggered transitions leaving substates of the state. If another event is added to the port's protocol in the future, such a trigger will handle the new event too without a need for being updated. Example -You can find a sample application that has an internal transition with a "receive-any" event trigger here. +You can find a sample application that has an internal transition with a "receive-any" event trigger here. Internal transitions are examples of so called self-transitions. To learn about other types of self-transitions see this chapter. -Frequent Transition -Sometimes you may have a state where one or a few outgoing transitions can be expected to execute much more frequently than others. You can then set a frequent property on the transition trigger that you expect will trigger the transition frequently. The Art compiler uses this information to optimize generated C++ code so that such transition triggers are evaluated before other triggers that are expected to trigger the transition less frequently. -interrupted: Working -> Stopped on [[rt::properties( - frequent=true - )]] external.interrupt - ` - // Interrupted while working... - `; - - -Note -The frequent property relies on optimization features in the C++ compiler that may or may not be available depending on which target compiler that is used. Only use frequent transitions if profiling has shown that you have a need to do this optimization. - Choice and Junction Choices and junctions are pseudo states that make it possible to split transition flows in a state machine. That is, one incoming transition may be split into multiple outgoing transitions. Which of the outgoing transitions that will execute is decided by evaluating their guard conditions. For a junction the guard conditions are evaluated already before leaving the currently active state. Only if there exists a path of transitions where all guards are fulfilled, will the active state be exited and the transitions can execute. Otherwise the state machine stays in its current state and attempts to find another path of transitions to execute. For a choice the guard conditions are evaluated after leaving the current state, when reaching the choice itself. The outgoing transition which has a fulfilled guard will execute next. @@ -2165,7 +2150,7 @@ Choice and Junction It's important that there always is an outgoing transition for a choice with a fulfilled guard condition. Otherwise the state machine will get stuck in the choice without any chance of getting out of it. The same is true if a junction is used in the initial transition. If such a junction doesn't have an outgoing transition with a fulfilled guard condition then the state machine will stay in the initial state for ever.
