From c1127efab01c12d8918b2d6c8b4b41b822fda697 Mon Sep 17 00:00:00 2001
From: Joshua Harlow <harlowja@yahoo-inc.com>
Date: Wed, 22 Apr 2015 14:21:44 -0700
Subject: [PATCH] Add + use diagram explaining retry controller area of
 influence

Change-Id: If2b5bb1460ad98a3ba65705727b2482e8428e8d8
---
 doc/diagrams/area_of_influence.graffle.tgz | Bin 0 -> 2710 bytes
 doc/source/atoms.rst                       |  27 +++++++++++++++++++--
 doc/source/img/area_of_influence.svg       |   3 +++
 3 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 doc/diagrams/area_of_influence.graffle.tgz
 create mode 100644 doc/source/img/area_of_influence.svg

diff --git a/doc/diagrams/area_of_influence.graffle.tgz b/doc/diagrams/area_of_influence.graffle.tgz
new file mode 100644
index 0000000000000000000000000000000000000000..b5aa4648883326085b631426845123b6ee97e985
GIT binary patch
literal 2710
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
Qx94g915H?M<^WIt0OG(`LjV8(

literal 0
HcmV?d00001

diff --git a/doc/source/atoms.rst b/doc/source/atoms.rst
index 9c2827bc..2b7c9d95 100644
--- a/doc/source/atoms.rst
+++ b/doc/source/atoms.rst
@@ -95,8 +95,31 @@ subclasses are provided:
     which allows for these atoms to influence subsequent execution(s) and the
     inputs any associated atoms require.
 
-Examples
---------
+Area of influence
+-----------------
+
+Each retry atom is associated with a flow and it can *influence* how the
+atoms (or nested flows) contained in that that flow retry or revert (using
+the previously mentioned patterns and decision enumerations):
+
+*For example:*
+
+.. image:: img/area_of_influence.svg
+   :width: 325px
+   :align: left
+   :alt: Retry area of influence
+
+In this diagram retry controller (1) will be consulted if task ``A``, ``B``
+or ``C`` fail and retry controller (2) decides to delegate its retry decision
+to retry controller (1). If retry controller (2) does **not** decide to
+delegate its retry decision to retry controller (1) then retry
+controller (1) will be oblivious of any decisions. If any of
+task ``1``, ``2`` or ``3`` fail then only retry controller (1) will be
+consulted to determine the strategy/pattern to apply to resolve there
+associated failure.
+
+Usage examples
+--------------
 
 .. testsetup::
 
diff --git a/doc/source/img/area_of_influence.svg b/doc/source/img/area_of_influence.svg
new file mode 100644
index 00000000..5e269e45
--- /dev/null
+++ b/doc/source/img/area_of_influence.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="-14 93 492 503" width="41pc" height="503pt"><metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:date>2015-04-22 21:13Z</dc:date><!-- Produced by OmniGraffle Professional 5.4.4 --></metadata><defs><filter id="Shadow" filterUnits="userSpaceOnUse"><feGaussianBlur in="SourceAlpha" result="blur" stdDeviation="3.488"/><feOffset in="blur" result="offset" dx="0" dy="4"/><feFlood flood-color="black" flood-opacity=".75" result="flood"/><feComposite in="flood" in2="offset" operator="in"/></filter><font-face font-family="Helvetica" font-size="12" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="FilledArrow_Marker" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="black"><g><path d="M 8 0 L 0 -3 L 0 3 Z" fill="currentColor" stroke="currentColor" stroke-width="1"/></g></marker></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Area of influence</title><g><title>Layer 1</title><g><use xl:href="#id3_Graphic" filter="url(#Shadow)"/><use xl:href="#id5_Graphic" filter="url(#Shadow)"/><use xl:href="#id6_Graphic" filter="url(#Shadow)"/></g><path d="M 404.53386 168.07705 C 499.8222 265.51279 499.8222 423.4872 404.53386 520.92295 C 309.246 618.3592 154.75399 618.3592 59.466136 520.92295 C -35.822208 423.4872 -35.822208 265.51279 59.466136 168.07705 C 154.75399 70.640816 309.246 70.640816 404.53386 168.07705" fill="white"/><path d="M 404.53386 168.07705 C 499.8222 265.51279 499.8222 423.4872 404.53386 520.92295 C 309.246 618.3592 154.75399 618.3592 59.466136 520.92295 C -35.822208 423.4872 -35.822208 265.51279 59.466136 168.07705 C 154.75399 70.640816 309.246 70.640816 404.53386 168.07705" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(41.8 337.5)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="175.86504" y="11" textLength="28.669922">Retry</tspan></text><ellipse cx="255" cy="393.5" rx="150.00024" ry="140.50023" fill="white"/><ellipse cx="255" cy="393.5" rx="150.00024" ry="140.50023" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(140 379.5)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="100.66504" y="11" textLength="28.669922">Retry</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="79.990234" y="25" textLength="70.01953">Controller (2)</tspan></text><ellipse cx="181.5" cy="340" rx="41.500065" ry="40.000065" fill="white"/><ellipse cx="181.5" cy="340" rx="41.500065" ry="40.000065" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(153.3 333)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="10.5222656" y="11" textLength="7.330078">T</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="16.522266" y="11" textLength="22.007812">ask </tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="37.873828" y="11" textLength="8.0039062">A</tspan></text><ellipse cx="295.5" cy="340" rx="41.500065" ry="40.000065" fill="white"/><ellipse cx="295.5" cy="340" rx="41.500065" ry="40.000065" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(267.3 333)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="10.1941406" y="11" textLength="7.330078">T</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="16.194141" y="11" textLength="30.011719">ask B</tspan></text><ellipse cx="299.5" cy="454" rx="41.500065" ry="40.000065" fill="white"/><ellipse cx="299.5" cy="454" rx="41.500065" ry="40.000065" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(271.3 447)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="9.863086" y="11" textLength="7.330078">T</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="15.863086" y="11" textLength="30.673828">ask C</tspan></text><g id="id3_Graphic"><ellipse cx="95.5" cy="227" rx="41.500065" ry="40.000065" fill="white"/><ellipse cx="95.5" cy="227" rx="41.500065" ry="40.000065" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(67.3 220)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="10.85918" y="11" textLength="7.330078">T</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="16.85918" y="11" textLength="28.68164">ask 1</tspan></text></g><g id="id5_Graphic"><ellipse cx="187.5" cy="179" rx="41.500065" ry="40.000065" fill="white"/><ellipse cx="187.5" cy="179" rx="41.500065" ry="40.000065" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(159.3 172)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="10.85918" y="11" textLength="7.330078">T</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="16.85918" y="11" textLength="28.68164">ask 2</tspan></text></g><g id="id6_Graphic"><ellipse cx="296.5" cy="191" rx="41.500065" ry="40.000065" fill="white"/><ellipse cx="296.5" cy="191" rx="41.500065" ry="40.000065" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(268.3 184)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="10.85918" y="11" textLength="7.330078">T</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="16.85918" y="11" textLength="28.68164">ask 3</tspan></text></g><line x1="223.49993" y1="340.08636" x2="243.60028" y2="340.1277" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(190 551)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="21.165039" y="11" textLength="28.669922">Retry</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x=".49023438" y="25" textLength="70.01953">Controller (1)</tspan></text><line x1="132.44904" y1="207.72231" x2="141.77384" y2="202.85721" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><line x1="229.23052" y1="183.59419" x2="244.92894" y2="185.32246" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><line x1="296.92024" y1="380.477" x2="297.7326" y2="403.6291" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g></g></svg>