add image

Author: puredanger

doc/flow.md

@@ -12,12 +12,14 @@ The fundamental objective of __core.async.flow__ is to enable a strict separatio
 
 __core.async.flow__ provides *concrete* implementations of two more abstractions - the '__process__' - a thread of activity, and the '__flow__' - a directed graph of processes communicating via channels. A single data structure describes your flow topology, and has all of the settings for threads, channels etc. A process accepts data from and provides data to channels. The process implementation in c.a.flow handles all channel I/O, thread lifecycle and coordination with the flow graph.
 
-All you need to do in you application is:
+All you need to do in your application is:
 
 1. Define ordinary, often pure, data->data functions that the processes will run in their inner loop to do the *computational* part of processing messages. These functions do not handle channels or threads or lifecycle, and do not even know they are running in a flow. They can be tested in isolation, and hot-reloaded. If they encounter a problem they can, and should, just throw an exception. The process will take care of it from there.
 
 2. Define a flow by creating a data structure that enumerates the processes and the connections between their inputs and outputs, as well as various configuration settings for both.
 
+![core.async.flow concerns](https://github.com/clojure/core.async/blob/master/doc/img/flow-concerns.png?raw=true)
+
 With these application inputs, c.a.flow does the rest. It inquires of the processes what channels they require, creates those channels, then instantiates the processes making all of the channel connections between them. The processes in turn start threads (in fully user-configurable thread pools), await inputs, monitor the admin control channel, and when inputs arrive make data->data calls to your application logic, taking the return from that and sending it to the designated output channels. The processes follow a protocol used by the flow to do lifecycle management and error handling.
 
 Once you've created a flow, the API provides functions to start/stop(shutdown) the flow, and to pause/resume both the flow and individual processes, to ping processes to get their state and that of their connected channels, to inject data into any point in the graph etc. The flow provides channels containing the ordinary monitoring/reporting stream and, separately, the error stream. 

doc/img/flow-concerns.png

@@ -7,7 +7,7 @@ <h2><a href="#rationale" id="rationale"></a>Rationale</h2>
 <p>The fundamental objective of <strong>core.async.flow</strong> is to enable a strict separation of your application logic from its topology, execution, communication, lifecycle, monitoring and error handling, all of which are provided by and centralized in, c.a.flow, yielding more consistent, robust, testable, observable and operable systems.</p>
 <h2><a href="#overview" id="overview"></a>Overview</h2>
 <p><strong>core.async.flow</strong> provides <em>concrete</em> implementations of two more abstractions - the ‘<strong>process</strong>’ - a thread of activity, and the ‘<strong>flow</strong>’ - a directed graph of processes communicating via channels. A single data structure describes your flow topology, and has all of the settings for threads, channels etc. A process accepts data from and provides data to channels. The process implementation in c.a.flow handles all channel I/O, thread lifecycle and coordination with the flow graph.</p>
-<p>All you need to do in you application is:</p>
+<p>All you need to do in your application is:</p>
 <ol>
 <li>
 <p>Define ordinary, often pure, data-&gt;data functions that the processes will run in their inner loop to do the <em>computational</em> part of processing messages. These functions do not handle channels or threads or lifecycle, and do not even know they are running in a flow. They can be tested in isolation, and hot-reloaded. If they encounter a problem they can, and should, just throw an exception. The process will take care of it from there.</p>
@@ -16,6 +16,7 @@ <h2><a href="#overview" id="overview"></a>Overview</h2>
 <p>Define a flow by creating a data structure that enumerates the processes and the connections between their inputs and outputs, as well as various configuration settings for both.</p>
 </li>
 </ol>
+<p><img src="https://github.com/clojure/core.async/blob/master/doc/img/flow-concerns.png?raw=true" alt="core.async.flow concerns" /></p>
 <p>With these application inputs, c.a.flow does the rest. It inquires of the processes what channels they require, creates those channels, then instantiates the processes making all of the channel connections between them. The processes in turn start threads (in fully user-configurable thread pools), await inputs, monitor the admin control channel, and when inputs arrive make data-&gt;data calls to your application logic, taking the return from that and sending it to the designated output channels. The processes follow a protocol used by the flow to do lifecycle management and error handling.</p>
 <p>Once you’ve created a flow, the API provides functions to start/stop(shutdown) the flow, and to pause/resume both the flow and individual processes, to ping processes to get their state and that of their connected channels, to inject data into any point in the graph etc. The flow provides channels containing the ordinary monitoring/reporting stream and, separately, the error stream.</p>
 <p>The library provides many more details and features, including the ability to create, via ordinary functions, processes that act as <strong>sources</strong> (of data from outside the flow) or <strong>sinks</strong> (to recipients outside the flow) so you can situate your flow in a broader context while still coordinating resource management with the flow lifecycle.</p>