doc/engine.dox

   1 /*! \page engine Engine
   2
   3 \section toc Table of contents
   4
   5   - \ref engine_intro
   6   - \ref basic_concepts
   7   - \ref engine_executor
   8
   9 \section engine_intro Introduction
  10
  11 The engine is in charge to :
  12
  13     - edit
  14     - check consistency
  15     - schedule
  16     - execute
  17
  18 graphs of execution independently from the context (\ref engine_runtime) the graph is destined to run.
  19
  20 \section basic_concepts Basic concepts in YACS::ENGINE
  21
  22 The understanding of YACS::ENGINE implementation needs a well
  23 knowledge of the following concepts :
  24
  25 - \ref engine_node
  26 - \ref engine_ports
  27 - \ref engine_links
  28 - \ref engine_types
  29 - \ref engine_context
  30 - \ref engine_placement
  31
  32 \section engine_executor Executor
  33
  34 The executor is in charge to run a graph of execution. Executor is
  35 TOTALLY independant from Node and Port implementation. The only APIs seen
  36 from YACS::ENGINE::Executor are YACS::ENGINE::Scheduler and YACS::ENGINE::Task. So, from the Executor point of
  37 view, a graph of execution is a scheduler scheduling tasks.
  38 The responsability of executor is to launch, concurrently or not, tasks selected by
  39 scheduler and to
  40 notify to tasks and to the scheduler what it is going to do and what happend
  41 during tasks' execution.
  42 There are several launching mode in executor. Here the common modes :
  43 - launch tasks until scheduler declares that all is finished.
  44 - launch tasks until a given task is upon to be launched.
  45 - launch tasks one by one. (step by step)
  46
  47 */
  48
  49 /*! \page engineConcepts Engine concepts
  50
  51 \section engine_node Nodes
  52
  53 A Node is an entity performing a treatement or job using ingoing data
  54 given in ingoing \ref engine_ports
  55 provided by other Nodes or 'manually' set and providing itself data in outgoing \ref engine_ports. A
  56 Node is eventually put into a scope (see \ref engine_hierarchy) in
  57 which all it's links with other Nodes can be performed. The most
  58 little scope if it exists of a Node is referenced by YACS::ENGINE::Node::_father.
  59
  60 There are 2 types of Node :
  61
  62 - Node performing a job NOT splitable into several simpler jobs. In
  63 this case job is called task. This type of Node can be dowcasted into
  64 YACS::ENGINE::ElementaryNode. That's why, YACS::ENGINE::ElementaryNode inherits from YACS::ENGINE::Task
  65 and YACS::ENGINE::Node.
  66
  67 - Node performing job splittable into several jobs. This type of
  68 Node can be dowcasted into YACS::ENGINE::ComposedNode. As this specific
  69 type of Node is composed of several Nodes it is in charge of schedule
  70 them. That's why, YACS::ENGINE::ComposedNode inherits from YACS::ENGINE::Scheduler and YACS::ENGINE::Node.
  71
  72 \subsection engine_hierarchy Node hierarchy
  73
  74 - It has been called hierarchy 'MyHierarchy' of a node 'MyNode' the biggest tree which each node of
  75 this tree is an instance of ComposedNode and each leaves are instances
  76 of ElementaryNode. One of these leaves/nodes is 'MyNode'. The links between leaves/nodes nodes/nodes are
  77 established by the fatherness stored in each instance of Node
  78 (YACS::ENGINE::Node::_father).
  79 - The unique node of
  80 this tree only linked down (with _father equal to 0) and having no
  81 father is called \b RootNode of 'MyHierarchy'.
  82 - A \b level \b of \b hierarchy of 'MyHierarchy' is the set of node/leaf having
  83 the same father.
  84 - A \b scope of a the hierarchy 'MyHierarchy' is a subtree of
  85 'MyHierarchy' tree. A scope is represented by the head node of this subtree.
  86
  87 \section engine_ports Ports
  88
  89 A YACS::ENGINE::Port is an interface of a YACS::ENGINE::Node from the
  90 outside. Ports can have several semantics.
  91
  92 - \ref engine_control_flow
  93 - \ref engine_data_flow
  94 - \ref engine_data_stream
  95
  96 \subsection engine_control_flow Control flow
  97
  98 The semantic of this port is to put constraints on the sequence of
  99 execution to synchronize nodes, on THE SAME
 100 LEVEL of \ref engine_hierarchy between them.
 101
 102 \subsection engine_data_flow Data
 103
 104 Instances of these type of ports inherits from YACS::ENGINE::DataFlowPort.
 105 This type of port represents data exchange protocol performed
 106 physically by implementation in \ref
 107 engine_runtime at the end of execution an instance of an ElementaryNode. So contrary to \ref
 108 engine_data_stream, this data exchange protocol is performed following
 109 \ref engine_control_flow synchronization.
 110
 111 \subsection engine_data_stream DataStream
 112
 113 Instances of these type of ports inherits from
 114 YACS::ENGINE::DataStreamPort. DataStream ports are ports for data
 115 exchange NOT synchronized by \ref engine_control_flow.
 116
 117 \section engine_links Links
 118
 119 A link in YACS does not lie onto a C++ object. A link exists in
 120 YACS::ENGINE model only like
 121 a sorted pair (YACS::ENGINE::OutPort, YACS::ENGINE::InPort).
 122 The semantic of elements of pair can be different (\ref engine_data_flow
 123 or \ref engine_data_stream ). This pair
 124 is stored in both YACS::ENGINE::OutPort side and YACS::ENGINE::InPort
 125 side. The storage YACS::ENGINE::InPort side is only for
 126 edition facility (Node, Port suppression), but at execution time, only links info
 127 YACS::ENGINE::OutPort side is used.
 128
 129 A link is constructed by the call to
 130 YACS::ENGINE::ComposedNode::edAddLink method. The instance of
 131 YACS::ENGINE::ComposedNode on which apply edAddLink must be so that
 132 inPort and OutPort are both in its scope.
 133
 134 \subsection engine_links_cpx Point of view of engine at run time
 135
 136 It is important to note that a link defined by edAddLink method can
 137 hide potentially a serie of elementary links. This is particalary true
 138 when 2 dataflow ports inside 2 different loops are linked each other ;
 139 in this case \ref engine_data_flow / \ref engine_data_stream
 140 conversion is requested.
 141 An elementary link is a link in which the semantic of both elements in pair
 142 are exactly the same. So the complexity linked to modification of port
 143 semantic in a link is managed at edition time so that at run time only
 144 elementary links are seen.
 145
 146 \section engine_types Data types
 147
 148 YACS::ENGINE::TypeCode instances are destined to describe data
 149   structure of a piece of data expected by an instance of
 150   YACS::ENGINE::DataPort (for type checking at edition : static type
 151   checking) or held in YACS::ENGINE::Any instance (for type checking
 152   at execution : dynamic type checking).
 153 All data exchanged by calculation nodes through input and output
 154 data ports have a type.
 155
 156 The type is given by the port that holds the data by calling
 157 its YACS::ENGINE::DataPort::edGetType() method.
 158 All types are instances of the YACS::ENGINE::TypeCode class or one of
 159 its derived classes : YACS::ENGINE::TypeCode_objref, YACS::ENGINE::TypeCode_seq.
 160
 161 \section engine_context Context
 162
 163 A context is a set of libraries allowing directly or indirectly from C++ calls to :
 164
 165  - launch on demand, a computation or a job specified uniquely by a
 166    string of character and a list of inputs and giving in return a
 167    list of data in specific data formats.
 168  - handle data of these specific data formats. Each of these data
 169    formats overlapping all or part of data overlapped by YACS::ENGINE::Any.
 170
 171 Concretely it takes form of set of :
 172
 173  - middlewares (CORBA, SOAP, MPI, PVM ...)
 174  - high level langage interpreters (as python, perl, shell) callable
 175  from C++.
 176  - plateform (<a href="http://www.salome-platform.org">SALOME</a>)
 177
 178 \section engine_runtime Runtime
 179
 180 A runtime exists in a given \ref engine_context. A runtime is in charge to :
 181
 182 - treat physically the basic execution of elementary tasks in a given context
 183 - the traduction of data in this context.
 184 - to perform the physical deployment of the execution.
 185
 186 The runtime simply appears in engine as an interface
 187 that a concrete runtime must implement to be piloted by YACS::ENGINE.
 188
 189 \section engine_placement Deployment
 190
 191 This the 3rd point of view of a graph of execution, after
 192 links between nodes (see \ref engine_links ) and hierarchy in nodes (
 193 \ref engine_hierarchy ).
 194 Deployment concept is accessible in interface YACS::ENGINE::Task with the
 195 concept of YACS::ENGINE::ComponentInstance and YACS::ENGINE::Container.
 196
 197 - a ComponentInstance is a common environement \b shared by a set of
 198   YACS::ENGINE::ServiceNode. Typically ServiceNodes sharing a same
 199   ComponentInstance are sharing a same state taking different form
 200   (environement var and/or memory space and/or internal variables...).
 201 - a Container is a common process \b shared by several ComponentInstances.
 202
 203 A task needed to be placed or deployed
 204 at runtime has to return something different from 0 on call to
 205 YACS::ENGINE::Task::getComponent(). YACS::ENGINE::ServiceNode is the
 206 abstract class representing all executable nodes needed to be
 207 deployed.
 208
 209 It's important to note that the placement (or deployment) of
 210 ServiceNodes can be performed at different moment at runtime.
 211
 212 - Either it is performed once for all YACS::ENGINE::Container before
 213 launching any task. This placement startegy is \b absolutly required for batch
 214 mode. This condition is checked by the YACS::ENGINE::Executor by
 215 calling YACS::ENGINE::Scheduler::isPlacementPredictableB4Run.
 216 - or it is done at the last moment on call of
 217 YACS::ENGINE::Load when execution of a ServiceNode is required by
 218 Executor on running process.
 219
 220
 221
 222 */