Action doc commit

Author: clojure-build

docs/clojure.core.async.flow.html

@@ -13,6 +13,10 @@
 a set of channels for centralized control, reporting, error-handling,
   and execution of the processes
 
+The flow library itself constructs processes, channels and flows. The
+user provides configuration data and process logic (step-fns) that
+specify how the flow should work.
+
 A flow is constructed from flow configuration data which defines a
 directed graph of processes and the connections between
 them. Processes describe their I/O requirements and the
@@ -22,9 +26,9 @@
 policy decisions regarding process settings, threading, buffering etc.
 
 It is expected that applications will rarely define instances of the
-process protocol but instead use the API functions here, 'process'
-and 'step-process', that implement the process protocol in terms of
-calls to ordinary functions that might include no communication or
+process protocol but instead use the API function 'process' that
+implements the process protocol in terms of calls to ordinary
+functions (step-fns) that might include no communication or
 core.async code. In this way the library helps you achieve a strict
 separation of your application logic from its execution,
 communication, lifecycle, error handling and monitoring.
@@ -36,6 +40,10 @@
 the library itself as ::flow/xyz, where ::flow is an alias for
 clojure.core.async.flow
 
+Flows support the Clojure 'datafy' protocol to support
+observability. See also the 'ping' and 'ping-proc' fns for a live
+view of processes.
+
 A process is represented in the flow definition by an implementation
 of spi/ProcLauncher that starts it. See the spi docs for
 details.</pre></div><div class="public anchor" id="var-command-proc"><h3>command-proc</h3><div class="usage"><code>(command-proc g pid cmd-id more-kvs)</code></div><div class="doc"><pre class="plaintext">synchronously sends a process-specific command with the given id and
@@ -73,25 +81,31 @@
         default :mixed</pre></div></div><div class="public anchor" id="var-inject"><h3>inject</h3><div class="usage"><code>(inject g [pid io-id :as coord] msgs)</code></div><div class="doc"><pre class="plaintext">asynchronously puts the messages on the channel corresponding to the
 input or output of the process, returning a future that will
 complete when done.</pre></div></div><div class="public anchor" id="var-lift*-.3Estep"><h3>lift*-&gt;step</h3><div class="usage"><code>(lift*-&gt;step f)</code></div><div class="doc"><pre class="plaintext">given a fn f taking one arg and returning a collection of non-nil
-values, create a 'step' fn as needed by step-process, with one input
+values, creates a step fn as needed by process, with one input
 and one output (named :in and :out), and no state.</pre></div></div><div class="public anchor" id="var-lift1-.3Estep"><h3>lift1-&gt;step</h3><div class="usage"><code>(lift1-&gt;step f)</code></div><div class="doc"><pre class="plaintext">like lift*-&gt;step except taking a fn returning one value, which when
 nil will yield no output.</pre></div></div><div class="public anchor" id="var-pause"><h3>pause</h3><div class="usage"><code>(pause g)</code></div><div class="doc"><pre class="plaintext">pauses a running flow
 </pre></div></div><div class="public anchor" id="var-pause-proc"><h3>pause-proc</h3><div class="usage"><code>(pause-proc g pid)</code></div><div class="doc"><pre class="plaintext">pauses a process
 </pre></div></div><div class="public anchor" id="var-ping"><h3>ping</h3><div class="usage"><code>(ping g &amp; {:keys [timeout-ms], :or {timeout-ms 1000}})</code></div><div class="doc"><pre class="plaintext">pings all processes, returning a map of pid -&gt; proc status and
 state, for those procs that reply within timeout-ms (default 1000)</pre></div></div><div class="public anchor" id="var-ping-proc"><h3>ping-proc</h3><div class="usage"><code>(ping-proc g pid &amp; {:keys [timeout-ms], :or {timeout-ms 1000}})</code></div><div class="doc"><pre class="plaintext">like ping, but just pings the specified process
-</pre></div></div><div class="public anchor" id="var-process"><h3>process</h3><div class="usage"><code>(process fn-or-map)</code><code>(process fn-or-map {:keys [workload timeout-ms], :or {timeout-ms 5000}, :as opts})</code></div><div class="doc"><pre class="plaintext">Given a function of four arities (0-3), or a map of functions
-corresponding thereto (described below), returns a launcher that
-creates a process compliant with the process protocol (see the
-spi/ProcLauncher doc).
-
-The possible arities/entries for fn/map are 0 - :describe, 1
-- :init, 2 - :transition and 3 - :transform. This is the core
-facility for defining the logic for processes via ordinary
-functions. Using a var holding a fn as the 'fn' is the preferred
-method for defining a proc, as it enables hot-code-reloading of the
-proc logic in a flow, and better names in datafy. You can use the
-map form to compose the proc logic from disparate functions or to
-leverage the optionality of some of the entry points.
+</pre></div></div><div class="public anchor" id="var-process"><h3>process</h3><div class="usage"><code>(process fn-or-map)</code><code>(process fn-or-map {:keys [workload timeout-ms], :or {timeout-ms 5000}, :as opts})</code></div><div class="doc"><pre class="plaintext">Given a function of four arities (0-3), aka the 'step-fn', or a map
+of functions corresponding thereto (described below), returns a
+launcher that creates a process compliant with the process
+protocol (see the spi/ProcLauncher doc).
+
+The possible arities/entries for the step-fn/map are
+
+0 - :describe,
+1 - :init,
+2 - :transition
+3 - :transform.
+
+This is the core facility for defining the logic for processes via
+ordinary functions. Using a var holding a fn as the 'step-fn' is the
+preferred method for defining a proc, as it enables
+hot-code-reloading of the proc logic in a flow, and better names in
+datafy. You can use the map form to compose the proc logic from
+disparate functions or to leverage the optionality of some of the
+entry points.
 
 arity 0, or :describe - required, () -&gt; description
 where description is a map with keys :params :ins and :outs, each of which
@@ -117,7 +131,10 @@
 
 init will be called once by the process to establish any initial
 state. The arg-map will be a map of param-&gt;val, as supplied in the
-flow def. init must be provided if 'describe' returns :params.
+flow def. The key ::flow/pid will be added, mapped to the pid
+associated with the process (useful e.g. if the process wants to
+refer to itself in reply-to coordinates). init must be provided if
+'describe' returns :params.
 
 Optionally, a returned init state may contain the
 keys ::flow/in-ports and/or ::flow/out-ports. These should be maps
@@ -181,7 +198,7 @@
 When :compute is specified transform must not block!</pre></div></div><div class="public anchor" id="var-resume"><h3>resume</h3><div class="usage"><code>(resume g)</code></div><div class="doc"><pre class="plaintext">resumes a paused flow
 </pre></div></div><div class="public anchor" id="var-resume-proc"><h3>resume-proc</h3><div class="usage"><code>(resume-proc g pid)</code></div><div class="doc"><pre class="plaintext">resumes a process
 </pre></div></div><div class="public anchor" id="var-start"><h3>start</h3><div class="usage"><code>(start g)</code></div><div class="doc"><pre class="plaintext">starts the entire flow from init values. The processes start paused.
-Call 'resume' or 'resume-proc' to start flow.  returns a map with keys:
+Call 'resume' or 'resume-proc' to start flow.  Returns a map with keys:
 
 :report-chan - a core.async chan for reading.'ping' reponses
 will show up here, as will any explicit ::flow/report outputs