.. include:: alias.rst

|rcm| Overview
==============

The |rcm| is an executable coordination model and its syntactic elements are:

* States (state machines)
* Links (to states)
* Barriers
* Ports
* Connections

The first three syntactic elements (states, links and barriers) are
nodes in |rcm|'s state machines. Ports are properties of states and
connections connect different nodes with each other. States execute code, barriers are
used to implement concurrency and links allow to re-use existing state
machines.


States
^^^^^^

States are the central entity for executing code. Hence, they are the
only node type that contains script code to be executed. More
specifically, states have:

* An entry script: the script that is executed once when the state has
  been activated.
* Action scripts: one or many script blocks. Each script block must 
  contain one condition expression. Action scripts are executed while 
  a state is active (until it is deactivated) given their condition 
  expression evaluates to ``true``.
* An exit script: the script that is executed once when the state has been
  deactivated. If the entry script of a state has been executed, its
  exit script will be executed as well at some point.

States can be parameterized with parameter values. Incomplete
parameter values (e.g. structs with missing fields - possibly nested)
are allowed in top-level states at upload time to provide default
parameter functionality. But they will be rejected when trying to execute
them. See the description of Link nodes for details.

In addition, each state can optionally contain child nodes which can
also be active as long as the outer state stays active. If the outer
state is deactivated, all children are preempted.

The parameter value of a state is available in all state scripts and
condition expressions of actions and ports but is read-only. In
addition, scripts can set a state's result value which is available
in all scripts and expressions of the state itself and also in the
parameters of sibling states or action and port conditions of the
parent state.

States contain a set of ports which control deactivation of the state
and consequential transition to the next state if there is one. In
addition, states can be organized hierarchically. Hence, each state
also stores (named) child nodes, the parameters of these child nodes
and the connections between them.

Links
^^^^^

Links reference a different state and behave exactly like actual
states, inheriting the ports, children, scripts and parameter values
from the linked state. A link can specify connections for its
inherited ports and instantiate the linked state with different
parameter values.

The parameter value of the linked state acts as a default value for
the parameter value of the link. That is, if a parameter value is
present in exactly one of link or linked state, that one is used, and
if both are present, the parameter value of the link is used. Absence
of a parameter is signaled by not including it as field in the struct
of parameters, not by means of a null value. A null value behaves like a
regular parameter value and can overwrite a default parameter
value. If the parameter values of the link and linked state are
structs, their fields are merged using the above rule. That is, if
fields with the same name exist in both, the one in the link parameter
value is used, or they are merged recursively if they are themselves
structs. Any fields that occur exclusively in either the link or
linked state, according to their name, are used.

Should a link reference another link instead of a state, the final
parameter value is computed inside-out: from the state machine to the
outer link.

Like states, top-level links with incomplete parameter values can be
created, but not executed.


Barriers
^^^^^^^^

Barriers implement split and join semantics and are the only
possibility to create parallel behavior in |rcm| state machines as a
regular state can only activate a single port. They are only activated
when all incoming connections are ready and activate all states
connected through outgoing connections simultaneously. It must be
noted that barriers can only be connected to states and not to other
barriers.

Ports
^^^^^

Ports control if a state should be deactivated. Ports are defined with
a port name, a port condition and a port priority. The port name is
used to identify a port when it is used in connections while the
priority value is used to determine the order of port evaluation. The
port condition is an expression that, if it evaluates to ``true``,
causes the owning state to be deactivated and a (possibly) connected
state to be activated.

Connections
^^^^^^^^^^^

Connections connect states, links and barriers with each other. When
connecting two states or links with each other, the connection is
defined over the name of the source state or link, the name of a port
in the source node and the name of the destination node (can be a
state, link or barrier). Connections between barriers and states and
between barriers and links are defined with only the name of the
source node and the name of the destination node. Connections between
two barriers are not allowed.