plugins/org.eclipse.etrice.doc/featuremodel/etrice.roomlanguage.featurizer

FeaturizerModel eTriceROOMLanguage

	imports "etrice.featurizer"


Package ROOMLanguage 
	description '''The Real Time Object Oriented Modeling (ROOM).'''
	text '''
		eTrice comprises several models:

		\begin{itemize}
		\item the ROOM model (*.room) -- defines model classes and the logical structure of the model
		\item the Config model (*.config) -- defines configuration values for attributes
		\item the Physical model (*.etphys) -- defines the structure and properties of the physical system
		\item the Mapping model (*.etmap) -- defines a mapping from logical elements to physical elements
		\end{itemize}
		
		In the following diagram the models and their relations are depicted. The meaning of the arrows is: uses/references.
		\begin{center}
			\includegraphics[width=.5\textwidth]{images/080-models.jpg}
		\end{center}
	'''
	contains LogicalModel 
	contains PhysicalModel 
	contains MappingModel
	contains ConfigModel
;

Feature AnnotationType
description '''AnnotationTypes can be used to tag ROOM classes for further custom processing.'''
text '''
	They provide the ability to associate custom properties to ROOM classes, that adjust or toogle features, like generation or the runtime behavior.
	eTrice has some built-in annotations, which can be found in Annotations.room within the eTrice modellib.

	See section Annotations for further reading.
'''
stable
;

Feature Annotation
description '''An Annotation can be attached to a ROOM classes to apply the properties of its AnnotationType.'''
text '''
	It refers to an AnnotationType and may have to pass key value pairs. Its notation is similar to Java:
	\begin{lstlisting}
		@AnnotationType1
		@AnnotationType2(key1="STRING", key2=3, ...)
	\end{lstlisting}

	See section Annotations for further reading.
'''
example '''
	import room.basic.annotations.* from "../../org.eclipse.etrice.modellib.c/model/Annotations.room"

	ActorClass ComponentAbstraction {
		Interface {
			conjugated Port port1: Protocol1
		}
		Structure {
			external Port port1
		}
		Behavior {
			// custom/external state machine implementation
			@BehaviorManual
		}
	}
'''
isOfType AnnotationType
stable
;

Feature Inheritance
	description '''A class can specify a super class and inherits elements from the super class hierarchy.'''
	text '''
		
	'''
	example '''
		\begin{lstlisting}[language=ROOM]
		ActorClass ActorSubClass extends ActorBaseClass {
			// inherits all elements from super type hierarchy
		}
		
		ActorClass ActorBaseClass {
			Interface {
				Port port1 : ProtocolBaseClass
			}
			Structure {
				Attribute attribute1 : uint32
			}
			Behavior {
				Operation operation1(){
					"return;"
				}
			}
		}
		
		ProtocolClass ProtocolSubClass extends ProtocolBaseClass {
			// inherits all elements from super type hierarchy
		}
		
		ProtocolClass ProtocolBaseClass {
			incoming {
				Message message1()
			}
		}
		
		DataClass DataSubClass extends DataBaseClass {
			// inherits all elements from super type hierarchy
		}
		
		DataClass DataBaseClass {
			Attribute attribute1 : uint32
		}
	\end{lstlisting}
	'''
	prototype	
;

Feature PhysicalModel
	description '''The PhysicalModel defines the setup of your nodes with their attributes like threads and mode of execution.'''
	text '''
		The model describes the physical view of your system:
		\begin{lstlisting}[language=etPhys]
		PhysicalSystem PhysSys1 {
			NodeRef server : ServerNode
			NodeRef embeddedClient : MCNode
		}
		\end{lstlisting}

		The central element is a NodeClass, that models the executional aspects of a device (node).
		At first, it can be associated with a RuntimeClass, which specifies if your device supports multiple threads.
		'priomin' and 'priomax' define the range of priorities, that can be assigned to threads.

		\begin{lstlisting}[language=etPhys]
		NodeClass NodeClass1 {
			runtime = RuntimeClass1
			priomin = -10
			priomax = 10

			// Thread definitions ...
		}

		RuntimeClass RuntimeClass1 {
			model = multiThreaded // or singleThreaded
		}
		\end{lstlisting}

		A thread has to specify the following properties:
		\begin{itemize}
			\item \textbf{execmode}: defines the execution type, see more at ExecutionType
			\begin{itemize}
				\item blocked: message-driven only, thread wakes up if message arrives and is put to sleep after all action is done
				\item polled: data-driven only, thread is executed cyclic. The 'interval' property is mandatory in this case.
				\item mixed: combines both execution types
			\end{itemize}
			\item \textbf{msgblocksize}: the size in bytes of a message
			\item \textbf{msgpoolsize}:  the amount of messages, that the thread's message queue can store
		\end{itemize}
		Note: 'msgblocksize' and 'msgpoolsize' also apply to the polled execution due the internal implementation via message passing.
		 The size of the message queue can be calculated as follows: msgpoolsize * msgblocksize bytes 

		\begin{lstlisting}[language=etPhys]
		DefaultThread ThreadMessaging {
			execmode = polled
			prio = 0
			stacksize = 1024
			msgblocksize = 32
			msgpoolsize = 10
		}

		Thread ThreadPolled {
			execmode = polled
			prio = 0
			interval = 100ms
			stacksize = 1024
			msgblocksize = 32
			msgpoolsize = 10
		}
		\end{lstlisting}
	'''
	stable
;

Feature MappingModel
	description '''The MappingModel describes the mapping of elements of the LogicalModel to elements of the PhysicalModel.'''
	text '''
		It enables the complete decoupling of the LogicalModel and the PhysicalModel, thus providing a maximum flexibility and reuse for the models.
		
		The model starts with an import part, where you can import .room and .etphys models. They should contain at least one LogicalSystem and one PhysicalSystem.
		The following mapping entry puts both in relation, meaning that all subsystems and actors contained in the hierarchical structure of the LogicalSystem should be executed within the given PhysicalSystem.
		With an SubSystemMapping you can distribute your subsystems to nodes. Afterwards you can map the logical threads within this subsystems to physical threads.
		\begin{lstlisting}[language=etMap]
		MappingModel PingPongMapping {
			import PingPong_Model.* from "PingPong.room"
			import GenericPhysicalModel.* from "GenericPhysical.etphys"
		
			Mapping LogSys -> PhysSys1 {
				SubSystemMapping subSystemRef -> nodeRef1 {
					ThreadMapping defaultThread -> PhysicalThread1
				}
			}
		
		}
		\end{lstlisting}
	'''
	uses LogicalModel
	uses PhysicalModel
	stable
;

Feature ConfigModel
	description '''The ConfigModel describes the Attribute configuration of ActorInstances and PortInstances. '''
	text '''
		The scope of this model is the configuration of Attributes of the LogicalModel.
		Thus it provides enhanced capabilities for assigning default values to Attributes, which are:
		\begin{itemize}
			\item type safe value assignment
			\item setting on class level
			\item setting on instance level
		\end{itemize}
		Values defined for class attributes are used for all instances unless there is an instance value configured for the same attribute.
		The configuration is available for actors and ports, thus ActorClasses/ActorRefs and ProtocolClasses/Ports.

		\begin{lstlisting}[language=Config]
		ConfigModel ExampleConfig {
			import Example.* from "Example.room"

			ActorClassConfig ActorClass1 {
				Attr attribute1 = 4
			}

			ActorInstanceConfig LogSys/subsysRef/actor1 {
				Attr attribute1 = 7
			}
		}
		\end{lstlisting}
	'''
	uses Attribute
	stable
;

Feature LogicalModel
	description '''The LogicalModel describes the logical structure and behavior of a ROOM application.'''
	text '''
		The ROOM model defines DataTypes, ProtocolClasses, ActorClasses, SubSystemClasses and LogicalSystems.
		Thereby the three latter form a hierarchy. The LogicalSystem is the top level element of the structure. 
		It contains references to SubSystemClass elements. The SubSystemClass in turn contains 
		references to ActorClass elements which again contain (recursively) references to 
		ActorClass elements. The complete structural hierarchy implies a tree which has the 
		LogicalSystem as root and where each reference stands for a new node with possibly further 
		branches.
	'''
	contains LogicalSystem
	contains SubSystemClass
	contains ActorClass
	contains ProtocolClass
	contains DataType
	contains AnnotationType
	
	stable
	;

Feature LogicalSystem
	description '''The LogicalSystem is the top-level structural class. It assembles the overall distributed system by means of sub systems.'''
	text '''
		It describes the logical topology of your system and is composed of sub systems (SubSystemRefs). Thus it is the notationally root of every instance path or actor hierarchy.
	'''
	contains SubSystemRef
	contains Binding
	contains LayerConnection
	contains Annotation
	stable
;

Feature ActorClass
	description '''An actor is the basic structural building block for building systems with ROOM.'''
	
	text '''
		An ActorClass consists of three main parts:
		\begin{itemize}
		\item \textbf{Interface} (external interface) specifies the communication to 'outside' actors and consists of Ports.
		\item \textbf{Structure} (internal interface) contains Ports, Attributes and ActorRefs. These elements are accessible from the Behavior part of the actor (in contrary to the external interface above). An ActorClass can be composed of other actors again by declaring ActorRefs. Also this part declares the connection of ports in form of Bindings and LayerConnections.
		\item \textbf{Behavior} is described by the StateMachine. It can receive and send messages from the ports, declared in the Structure above. The Attributes can be used to store data during an state transition. Furthermore it is possible to declare Operations. They can be used to define reusable logic, that is invoked during a state transition.
		\end{itemize}	
		
		\includegraphics[scale=0.7]{images/040-ActorClass.png}
		\begin{lstlisting}
		 ActorClass ExampleActorClass {
			 Interface {
				 Port port1: ProtocolClass1
				 Port port4: ProtocolClass1
			 }
			 Structure {
				 external Port port1
				 conjugated Port port2: ProtocolClass1
				 conjugated Port port3: ProtocolClass1
				 
				 ActorRef ActorRef_A: ActorClass2
				 ActorRef ActorRef_B: ActorClass3
				 
				 Binding port2 and ActorRef_A.port5
				 // ...
			 }
			 Behavior {
				 // ...
			 }
		 }
		 \end{lstlisting}
	'''
	
	example '''
		
	'''
	help '''
		```room
		// prefixes: abstract and (eventdriven, datadriven, async, sync)
		ActorClass ActorName ["generated doc"] {
			Interface {
				Port port1 ...
				SPP spp1 ...
			}
			Structure ["generated doc"] {
				usercode1 { "" }
				usercode2 { "" }
				usercode3 { "" } 
				external Port port1
				Port internalPort2 ...
				ActorRef ...
				Attribute ...
				
				ServiceImplementation of spp1
				Binding ...
				LayerConnection ...
			}
			Behavior ["generated doc"] {
				Operation ActorName() { /* constructor */ }
				Operation ~ActorName() { /* destructor */ }
				Operation ...
				StateMachine ...
			}
		```
	'''
	
	contains ExecutionType
	contains ActorRef
	contains Port
	contains SAP
	contains SPP
	contains Binding
	contains LayerConnection
	contains Attribute
	contains Operation
	contains StateMachine
	contains Annotation
	uses Inheritance
	stable
;

Feature SubSystemClass
	description '''The SubSystem is main Actor of an executable part of the system. '''
	
	text '''
		
	'''

	contains ActorRef
	contains RelayPort
	contains SPP
	contains Binding
	contains LayerConnection
	contains Annotation
	stable
;
	


Feature StateMachine
	shortName '''State Machine'''
	description '''A StateMachine describes the state based, event driven behavior of an ActorClass'''
	text '''
		In ROOM each actor class can implement its behavior using a state machine. Events occurring at the end ports of an actor will be forwarded to and processed by the state machine. Events possibly trigger state transitions.
		\includegraphics[scale=.7]{images/300-PingPongReceiverFSM.png}
	'''
	uses Inheritance
	stable
	;

Feature SubSystemRef
	shortName '''Sub System Reference'''
 	description '''A Sub System Reference is an instance of an SubSystemClass'''
 	isOfType SubSystemClass
 	stable
;

abstract Feature Replication
	description '''Replication is mechanism for multi instantiation for ActorRefs and Ports.'''
	text '''
		ActorRefs and Ports can be instantiated several times under the same name. The notation is similar to arrays in programming languages.
	
		This possibility provides an elegant way of scaling of your system without redundancy. Note the ActorRef can be arbitray complex
		\begin{lstlisting}[language=ROOM]
			ActorRef sensor : Sensor 			// one instance
			ActorRef sensor[1] : Sensor			// one instance
			ActorRef sensorArray[5] : Sensor	// five instances  
		\end{lstlisting}
		
		Replication can also applied to Ports. One use case is to establish a communication with multiple actors through one port interface.
		\begin{lstlisting}[language=ROOM]
			Port service[5] : TimingService 	// five instances
			Port service[*]: TimingService		// automatic, as many as needed
		\end{lstlisting}
	'''
stable
;

Feature ActorRef
	shortName '''Actor Reference'''
	description '''An ActorRef is an instance of an ActorClass.'''
	text '''
	\begin{itemize}
		\item ActorClass: The type of the ActorRef
		\item Multiplicity: The number of instances. A number greater than one can be seen as an array of instances
		\item Reference Type: Can be fixed or optional. Fixed requires an integer multiplicity and results in an static instantiation with an fixed number of instances during runtime . Optional denotes an dynamic instantiation, where ActorRefs can be created in arbitrary number during runtime. In this case, the multiplicity has to be set to '*'
	\end{itemize}
	'''
	example '''
		\begin{lstlisting}[language=ROOM]
		SubSystemClass SubSystemExample {
			ActorRef mainActor : ActorClassExample
			
			LogicalThread default_thread
		}
		
		ActorClass ActorClassExample {
			Structure {
				ActorRef sender : Sender
				ActorRef receiver : Receiver
				
				Binding receiver.port and sender.port
			}
		}
		
		ActorClass ActorClassExampleReplicated {
			Structure {
				ActorRef sender[3]: Sender
				ActorRef receiver[3] : Receiver
				
				Binding receiver.port and sender.port
				/* Equivalent to:
				 *  Binding receiver[1].port and sender[1].port
				 *  Binding receiver[2].port and sender[2].port
				 * ....
				 */		
			}
		}
		\end{lstlisting}
		\begin{figure}[H]
		\includegraphics[width=.7\textwidth]{images/300-ActorRefInstanceDiagram.jpg}
		\caption*{Instance hierarchy of ActorRef Example (\textsf{System(System)} not shown in code snippet)}
		\end{figure}
	'''
	isOfType ActorClass
	uses Replication
	property multiplicity values {"1..n", "*"}
	stable
;

Feature Binding
	description '''A Binding connects two Ports with each other.'''
	text '''
		In essence, a binding is a abstraction for an underlying communication channel whose function is to convey messages from one port to the other.
		The precise semantics of these channels are not defined in the Binding. Instead, they are determined by the ProtocolClasses that are associated with the Ports at the end of the Binding.
	
		\begin{lstlisting}
		 ActorClass ExampleActorClass {
			Structure {
				 conjugated Port sender: ProtocolClass1
				 ActorRef actorRef: ActorClass2
				 
				 Binding sender and actorRef.receiver
			 }
		 }
		 \end{lstlisting}
	'''
	uses Port endpoint1
	uses Port endpoint2
	stable
;

Feature LayerConnection
	description '''A LayerConnection associates a SPP to an ActorRef, resulting in an connection of all SAPs on its instance hierarchy.'''
	text '''
		\begin{itemize}
		\item An actor class can define a Service Provision Point (SPP) to publish a specific service, defined by a protocol class
		\item An actor class can define a Service Access Point (SAP) if it needs a service, defined by a protocol class
		\item For a given actor hierarchy, a LayerConnection defines which SAP will be satisfied by (connected to) which SPP
		\end{itemize}
	'''
	uses SAP SAPoint
	uses SPP SPPoint
	stable
;

Feature ExecutionType
	description '''Determines the execution type of an actor.'''
	text '''
		Since from ROOM models executable code can be generated, it is important to define the way the actors are 
		executed and communicate with each other. The combination of communication and execution is called the 
		\emph{execution model}. Therefore the ExecutionType of an actor and the CommunicationType of the ports has to be considered.

		The ExecutionType of an ActorClass specifies in which way its instance (ActorRef) should be executed:
		\begin{itemize}
		\item \textbf{execution by receive event}: The message queue or the event dispatcher calls a 
		\textbf{receive event} function of the message receiver and thereby executes the processing of the event.
		\item \textbf{polled execution}: The objects are processed by a cyclic \textbf{execute} call
		\item \textit{\textbf{execution by function call}: The caller executes the called object via function call} (not supported yet)
		\item \textbf{mixture}: An asynchronous execution combines an event dispachter and a polled execution.
		\end{itemize}

		Thereby the ExecutionType determines the execution mode of the actor's logical thread:
		\includegraphics[width=.7\textwidth]{images/010-RoomIntroduction03.png}
				
		The actual execution of the underlying physical thread can be specified in the PhysicalModel in conjunction with the MappingModel.

		ExecutionType relates to the \hyperlink{ref:CommunicationType}{CommunicationType}, e.g. if an actor uses data-driven ports, it should support an polled execution.
	'''
	example '''
		\begin{lstlisting}
		eventdriven ActorClass EventdrivenActor ["default is eventdriven"] {
			// only event-driven Ports and ActorRefs allowed
		}
		
		datadriven ActorClass DatadrivenActor {
			// only data-driven Ports and ActorRefs allowed
		}
		
		async ActorClass MixedActor{
			// both data/event-driven Ports and ActorRefs allowed
		}
		\end{lstlisting}
	'''
	uses CommunicationType
	property mode values { "eventdriven", "datadriven", "async", "sync" }
	
	stable
;

Feature CommunicationType 
	description '''The CommunicationType defines the communication semantics of a ProtocolClass.'''
	text '''
		Since from ROOM models executable code can be generated, it is important to define the way the actors are 
		executed and communicate with each other. The combination of communication and execution is called the 
		\emph{execution model}. Therefore the ExecutionType of an actor and the CommunicationType of the ports has to be considered.

		The CommunicationType of a ProtocolClass (and thus of a Port) specifies in which way the communication should happen:

		\begin{itemize}
		\item \textbf{message driven} -- asynchronous, non blocking, no return value:\\
		Usually the message driven communication is implemented with message queues. Message queues are inherently asynchronous and enable a very good decoupling of the communicating parties.
		\item \textbf{data driven} -- asynchronous, non blocking, no return value:\\
		In data driven communication sender and receiver often have a shared block of data. The sender writes the data and the receiver polls the data.
		\item \textit{\textbf{function call} -- synchronous, blocking, return value:\\
		Regular function call as known in most programming languages.} (not supported yet)
		\end{itemize}

		CommunicationType relates with the \hyperlink{ref:ExecutionType}{ExecutionType} of an ActorClass, e.g. a data-driven port needs a cyclic thread, that polls the shared data.
	'''
	example '''
		\begin{lstlisting}[language=ROOM]
	
		import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room"
	
		ProtocolClass EventdrivenProtocolClass1 [ "default is eventdriven" ] {
			// explicit: eventdriven ProtocolClass EventdrivenProtocolClass {
			incoming {
				Message msg1() ["message without data"]
				Message msg2(data: int32) ["message with data"]
			}
			outgoing {
				Message msg4()  ["eventdriven ProtocolClass can have message into two directions"]
			}
		}
	
		datadriven ProtocolClass DatadrivenProtocolClass {
			incoming {
				Message signal1 (data: int32) ["a datadriven message needs data"]
			}
			// datadriven ProtocolClass can only have incoming messages (signals)
		}
		
		//  sync is not supported yet
		//	sync ProtocolClass SyncProtcolClass { 
		//		
		//	}
		\end{lstlisting}
	'''
	property type values {"eventdriven", "datadriven", "sync"}
	stable
;

Feature ProtocolClass
	description '''A ProtocolClass defines messages and is the interface specification for a Port'''
	text '''
		A ProtocolClass provides a reusable interface specification for ports. It defines a set of incoming and outgoing Messages that can be exchanged between two ports.
		The exact semantics of a message is defined by the CommunicationType.
		Protocol classes have only textual notation.

		\begin{lstlisting}
		ProtocolClass SimpleProtocolClass {
			incoming {
				Message msg1(data: int32}
				Message msg2()
			}
			outgoing {
				Message msg3(data: DataClass1}
				Message msg4()
			}
		}
		\end{lstlisting}
	'''
	example '''
	\begin{lstlisting}
	import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room"

	// eventdriven ProtocolClass (asynchronous message passing, bidirectional)
	eventdriven ProtocolClass ProtocolClassEvt {
		// ProtocolClass ProtocolClassEvt { // same like above because eventdriven is default 
		incoming {
			// incoming means incoming for a regular port and outgoing for a conjugated port
			Message message1() // message without data
			Message message2(data: int32) // message with simple data
			Message message3(data: DMessageData) // message with complex data (DataClass)

		}
		outgoing {
		// outgoing means outgoing for a regular port and incoming for a conjugated port
			Message message1(data: int32) // incoming and outgoing Messages can have the same name to enable symmetric protocols
		}
	}

	// DataClass for sending complex data via message
	DataClass DMessageData {
		Attribute SomeData: int16
		Attribute SomeMoreData: int32
	}

	// datadriven ProtocolClass (asynchronous data flow, unidirectional)
	datadriven ProtocolClass ProtocolClassData {
		incoming {
			// incoming means incoming for a regular port and outgoing for a conjugated port
			Message value1(value: int32) // a datadriven message (signal) always needs data
			Message value2(value: int16) // datadriven message with simple data
			Message value3(value: DMessageData) // datadriven message with complex data (DataClass)

		}
		// no outgoing messages for datadriven ports allowed 
	}
	\end{lstlisting}
	'''
	contains CommunicationType
	contains Attribute
	contains Operation
	contains Annotation
	uses Inheritance
	
	stable
	;

abstract Feature DataType
	description '''A DataType can take 4 forms and types data elements like an Attribute or Operation argument.'''
	stable
;

Feature PrimitiveType
	description '''A PrimitiveType is an abstraction of a target language's basic type (e.g. integer or boolean).'''
	example '''
		The eTrice built-in types can be found in the \textsf{org.eclipse.etrice.modellib} project. In most cases the \textsf{Types.room} is already included:
		\begin{lstlisting}[language=ROOM]
		// Follow import by Open Declaration (F3)
		import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room"
		\end{lstlisting}
	'''
	isA DataType
	property targetName values {"<identifer name>"}
	stable
	;
	
Feature EnumerationType
	description '''An EnumerationType declares an enumeration similar to most well-known languages.'''
	example '''
	\begin{lstlisting}[language=ROOM]
	Enumeration EOnOff {
		Off = 0, // explicit value=0
		On = 1 // explicit value=1 

	}

	Enumeration EDay {
		SUN,
		MON,
		TUE,
		WED,
		THU,
		FRI,
		SAT // implicit enumeration 0..6
	}
	\end{lstlisting}
	'''
	isA DataType
	property literals values {"<name>"}
	stable;

Feature DataClass 
	description '''A DataClass is a composition of Attributes.'''
	text '''
		Intended to model a type that primarily consists of data, which is usually grouped together in some manner. DataClasses roughly translate to Java classes without interaction or C \textsf{struct}s.
		
		\begin{lstlisting}[language=ROOM]		
		DataClass TCPConnectionData {
			Attribute IPAddr: string
			Attribute TcpPort: int32
		}
		\end{lstlisting}
	'''
	example '''
		\begin{lstlisting}[language=ROOM]
		DataClass SimpleDataClass {
			Attribute attribute1: uint16
			Attribute attribute2: uint32
		}

		DataClass DataClassExample {
			Attribute attribute1: uint32
			Attribute attribute2: SimpleDataClass
			Attribute attribute3: voidType ref
			
			Operation operation1(param1: uint32, param2: uint16): boolean {
				"return true;"
			}
		}
		\end{lstlisting}
	'''
	isA DataType
	contains Attribute
	contains Operation
	contains Annotation
	uses Inheritance
	stable;

Feature ExternalType 
	description '''An ExternalType is used to make an target language type accessible in ROOM.'''
	example '''
		\begin{lstlisting}[language=ROOM]
		// Include is needed when used (e.g. in ActorClassWithExternalType)
		ExternalType someStructType -> "struct FILE_HANDLE"
		
		ActorClass ActorClassWithExternalType{
			Structure {
				usercode1 {
					"// #include <___.h> /* User includes here*/"
				}
				Attribute someHandle : someStructType ref // needs include
			}
			Behavior {
				Operation operation1(param1: charPtr) {
					// external calls or casts may need includes
					"write(someHandle, param1);"
				}
			}
		}
		\end{lstlisting}
	'''
	isA DataType
	property targetName values {"<identifier name>"}
	stable;

Feature Attribute
	description '''An Attribute is a member variable of a class'''
	text '''
		An Attribute can be be used to store arbitrary data. There are two common conceptual purpose of use:

		\begin{itemize}
			\item model current system state (state machine variable)
			\item store reference to more fine-grained components (e.g. c pointer to handle)
		\end{itemize}
		Attributes can be defined in ActorClasses, DataClasses and ProtocolClasses.
	'''
	example '''
		\begin{lstlisting}[language=ROOM]
		import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room"
		
		DataClass SimpleDataClass {
			Attribute attribute1: int16
			Attribute attribute2: uint32
		}

		ActorClass ActorClassWithAttributes {
			Structure {
				Attribute attribute1: int32 			["attribute of a PrimitiveType" ]
				Attribute attribute2: SimpleDataClass 	[ "attribute of a DataClass" ]
			}
		}

		ActorClass ActorClassWithAttributes2 {
			Structure {
				Attribute arrayAttribute[8] : uint32 [ "attribute with multiplicity"]
				Attribute refAttribue : voidType ref [ "attribute as a reference (void pointer)"]
			}
		}
	
		ActorClass ActorClassWithAttributeInitialization {
			Structure {
				Attribute attribute1: uint32 = "3"
				Attribute attribute2: SimpleDataClass = "{1, 2}"
				Attribute arrayAttribute[8] : uint32 = "0" // or {0,0,0, ...}
				Attribute refAttribue : voidType ref = "NULL" // set reference in constructor or in state machine
			}
		}
		\end{lstlisting}
	'''
	help '''
		```room
		Attribute boolAttribute: boolean
		Attribute arrayAttribute[8] : int32 = "0"
		Attribute refAttribue : voidType ref = "NULL"
		```
	'''
	isOfType DataType
	property defaultValueLiteral values { "<target code>"}
	property multiplicity values {"1..n"}
	stable
	
	
;

Feature Operation
	description '''An Operation is a member function of a class.'''
	text '''
		Operations can be used to define a piece of reusable logic. The definition consists of:
		\begin{itemize}
			\item Arbitrary amount of arguments
			\item Return type
			\item User code body, which can access the structural part of the containing class (e.g. attributes)
		\end{itemize}
	'''
	example '''
		\begin{lstlisting}[language=ROOM]
		import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room"
	
		DataClass DataClassWithOperation {
			Attribute attribute1 : uint32
			
			Operation operation1(param1: uint32, param2: int32): boolean {
				"return attribute1 > (param1 - param2);"
			}
		}
		
		ActorClass ActorClassWithOperation {
			Structure {
				Attribute attribute1 : uint32
			}
			Behavior {
				Operation operation1(param1: uint32, param2: int32): boolean {
					"return attribute1 > (param1 - param2);"
				}
			}
		}
		
		ActorClass ActorClassWithOperation2 {
			Structure {
				usercode1 {
					"// #include <___.h> /* User includes here*/"
				}
				Attribute someHandle : voidType ref
			}
			Behavior {
				Operation operation1(param1: charPtr) {
					// external calls or casts may need includes
					"write(someHandle, param1);"
				}
			}
		}
		\end{lstlisting}
	'''
	uses DataType
	property returnType values { "<DataType>" }
	property arguments values { "<name> : <DataType>" }
	
	stable
;

abstract Feature Port
	description '''A Port is an instance of a ProtocolClass and the interface for an ActorClass.'''
	text '''
		Once a ProtocolClass has been created, it can be used to define actor interfaces. This is accomplished by means of Ports. 
		A Port is a declaration that the set of messages defined by its ProtocolClass is now part of the actor's interface.
		It provides strong decoupling of ActorClasses from each other, thus enabling easy testability, reusability and deployment of actors to different threads or nodes.

		\begin{lstlisting}[language=ROOM]
		ActorClass Example {
			Structure{
				Port port0 : ProtocolClass1
			}
			Behavior {
				// send/receive message from port0
			}
		}
		\end{lstlisting}
		
		For communication between two actors to take place, a connection must be established between a port on one of the actors and a port on the other.
		One condition is, that both Ports have compatible ProtocolClasses. In most cases the Ports simply refer to the same protocol.
		In addition, a ProtocolClass has an imposed directionality - it defines one subset of messages as incoming and the complementary subset as outgoing.
		Which subset is labelled as incoming and outgoing is arbitray, it simply depends on the point of view, that was taken when defining.
		Therefore Ports can be 'regular' and 'conjugated'. When two actors communicate by a connected pair of Ports, one Port has to be regular and the other conjugated.
		The ProtocolClass' incoming messages are on one side received by the regular Port and on the other sent by the conjugated Port (outgoing message vice versa).

		A connection of Ports is denoted by a Binding. 
	'''
	isOfType ProtocolClass
	uses Replication
	property conjugated values { "regular", "conjugated"}
	property multiplicity values {"1..n", "*"}
	stable
;

Feature RelayPort
	description '''A RelayPort forwards its messages without exposing them to the internal interface of the ActorClass.'''
	text '''
		\begin{lstlisting}[language=ROOM]
		ActorClass RelayPortExample{
			Interface {
				Port relayPort : PSimpleProtocol
			}
			Structure {
				ActorRef actorRef1 : SimpleActorClass2
				
				// relayPort can be directed to port of an ActorRef
				Binding relayPort and actorRef1.externalPort
			}
			Behavior {
				// relayPort not available !
			}
		}
		\end{lstlisting}
		\includegraphics[scale=.7]{images/300-RelayPort.png}
	'''
	isA Port
	stable
;


Feature ExternalEndPort 
	description '''A ExternalEndPort is an interface Port, that is made accessible to the internal interface of an ActorClass.'''
	text '''
		\begin{lstlisting}[language=ROOM]
		ActorClass ExternalEndPortExample {
			Interface {
				// externalEndPort is connect from 'outside' and thus needs a Binding from containing ActorClass
				Port externalEndPort : PSimpleProtocol
			}
			Structure {
				external Port externalEndPort
			}
			Behavior {
				// send/receive messages from externalEndPort
			}
		}
		\end{lstlisting}
	'''
	isA Port
	stable
;

Feature InternalEndPort
	description '''A InternalEndPort is an local Port, that is declared in the internal interface of an ActorClass.'''
	text '''
		\begin{lstlisting}[language=ROOM]
		ActorClass InternalEndPortExample {
			Structure {
				Port internalEndPort : PSimpleProtocol
				ActorRef actorRef1 : SimpleActorClass
				
				// internalEndPort lives 'local' and
				// thus needs a Binding to port of a ActorRef
				Binding internalEndPort and actorRef1.externalPort2 
			}
			Behavior {
				// send/receive messages from internalEndPorts
			}
		}
		\end{lstlisting}
		\includegraphics[scale=.7]{images/300-InternalEndPort.png}
	'''
	isA Port
	stable
;

Feature SAP
	shortName '''Service Access Point'''
	description '''A Service Access Point is similar to a Port, but uses a LayerConnection for wiring.'''
	text '''
		\emph{\large Under construction}
		\begin{itemize}
		\item An actor class can define a Service Provision Point (SPP) to publish a specific service, defined by a protocol class
		\item An actor class can define a Service Access Point (SAP) if it needs a service, defined by a protocol class
		\item For a given actor hierarchy, a LayerConnection defines which SAP will be satisfied by (connected to) which SPP
		\end{itemize}
	'''
	isOfType ProtocolClass
	stable
; 

Feature ServiceImplementation
	shortName '''SPP Implementation'''
	description '''The implementation of an Service Provision Point (SPP).'''
	text '''
	'''
	uses SPP
	stable
;

Feature SPP
	shortName '''Service Provision Point'''
	description '''A Service Provision Point is the counterpart of a SAP'''
	text '''
		\emph{Under construction}
		\begin{itemize}
		\item An actor class can define a Service Provision Point (SPP) to publish a specific service, defined by a protocol class
		\item An actor class can define a Service Access Point (SAP) if it needs a service, defined by a protocol class
		\item For a given actor hierarchy, a LayerConnection defines which SAP will be satisfied by (connected to) which SPP
		\end{itemize}
	'''
	isOfType ProtocolClass
	stable
;