openstack/taskflow
Code Issues Proposed changes

Merge "Update engine docs with new validation stage"

Browse Source
This commit is contained in:
Jenkins 2015-03-15 05:39:35 +00:00 committed by Gerrit Code Review
commit f890a096de
1 changed files with 31 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
doc/source/engines.rst
View File

@ -221,39 +221,46 @@ are setup.
Compiling Compiling
--------- ---------
During this stage the flow will be converted into an internal graph During this stage (see :py:func:`~taskflow.engines.base.Engine.compile`) the
representation using a flow will be converted into an internal graph representation using a
:py:class:`~taskflow.engines.action_engine.compiler.Compiler` (the default compiler (the default implementation for patterns is the
implementation for patterns is the
:py:class:`~taskflow.engines.action_engine.compiler.PatternCompiler`). This :py:class:`~taskflow.engines.action_engine.compiler.PatternCompiler`). This
class compiles/converts the flow objects and contained atoms into a class compiles/converts the flow objects and contained atoms into a
`networkx`_ directed graph that contains the equivalent atoms defined in the `networkx`_ directed graph (and tree structure) that contains the equivalent
flow and any nested flows & atoms as well as the constraints that are created atoms defined in the flow and any nested flows & atoms as well as the
by the application of the different flow patterns. This graph is then what will constraints that are created by the application of the different flow
be analyzed & traversed during the engines execution. At this point a few patterns. This graph (and tree) are what will be analyzed & traversed during
helper object are also created and saved to internal engine variables (these the engines execution. At this point a few helper object are also created and
object help in execution of atoms, analyzing the graph and performing other saved to internal engine variables (these object help in execution of
internal engine activities). At the finishing of this stage a atoms, analyzing the graph and performing other internal engine
activities). At the finishing of this stage a
:py:class:`~taskflow.engines.action_engine.runtime.Runtime` object is created :py:class:`~taskflow.engines.action_engine.runtime.Runtime` object is created
which contains references to all needed runtime components. which contains references to all needed runtime components.
Preparation Preparation
----------- -----------
This stage starts by setting up the storage needed for all atoms in the This stage (see :py:func:`~taskflow.engines.base.Engine.prepare`) starts by
previously created graph, ensuring that corresponding setting up the storage needed for all atoms in the compiled graph, ensuring
:py:class:`~taskflow.persistence.logbook.AtomDetail` (or subclass of) objects that corresponding :py:class:`~taskflow.persistence.logbook.AtomDetail` (or
are created for each node in the graph. Once this is done final validation subclass of) objects are created for each node in the graph.
occurs on the requirements that are needed to start execution and what
:py:class:`~taskflow.storage.Storage` provides. If there is any atom or flow Validation
requirements not satisfied then execution will not be allowed to continue. ----------
This stage (see :py:func:`~taskflow.engines.base.Engine.validate`) performs
any final validation of the compiled (and now storage prepared) engine. It
compares the requirements that are needed to start execution and
what is currently provided or will be produced in the future. If there are
*any* atom requirements that are not satisfied (no known current provider or
future producer is found) then execution will **not** be allowed to continue.
Execution Execution
--------- ---------
The graph (and helper objects) previously created are now used for guiding The graph (and helper objects) previously created are now used for guiding
further execution. The flow is put into the ``RUNNING`` :doc:`state <states>` further execution (see :py:func:`~taskflow.engines.base.Engine.run`). The
and a flow is put into the ``RUNNING`` :doc:`state <states>` and a
:py:class:`~taskflow.engines.action_engine.runner.Runner` implementation :py:class:`~taskflow.engines.action_engine.runner.Runner` implementation
object starts to take over and begins going through the stages listed object starts to take over and begins going through the stages listed
below (for a more visual diagram/representation see below (for a more visual diagram/representation see
@ -262,10 +269,10 @@ the :ref:`engine state diagram <engine states>`).
.. note:: .. note::
The engine will respect the constraints imposed by the flow. For example, The engine will respect the constraints imposed by the flow. For example,
if Engine is executing a :py:class:`.linear_flow.Flow` then it is if an engine is executing a :py:class:`~taskflow.patterns.linear_flow.Flow`
constrained by the dependency-graph which is linear in this case, and hence then it is constrained by the dependency graph which is linear in this
using a Parallel Engine may not yield any benefits if one is looking for case, and hence using a parallel engine may not yield any benefits if one
concurrency. is looking for concurrency.
Resumption Resumption
^^^^^^^^^^ ^^^^^^^^^^