docs/clojure.core.async.flow.spi.html

<!DOCTYPE html PUBLIC ""
    "">
<html><head><meta charset="UTF-8" /><title>clojure.core.async.flow.spi documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name"></span> <span class="project-version"></span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Topics</span></h3><ul><li class="depth-1 "><a href="rationale.html"><div class="inner"><span>Rationale</span></div></a></li><li class="depth-1 "><a href="reference.html"><div class="inner"><span>Reference</span></div></a></li><li class="depth-1 "><a href="walkthrough.html"><div class="inner"><span>Walkthrough</span></div></a></li><li class="depth-1 "><a href="flow.html"><div class="inner"><span>Flow</span></div></a></li><li class="depth-1 "><a href="flow-guide.html"><div class="inner"><span>Flow Guide</span></div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1 "><a href="clojure.core.async.html"><div class="inner"><span>clojure.core.async</span></div></a></li><li class="depth-1 "><a href="clojure.core.async.flow.html"><div class="inner"><span>clojure.core.async.flow</span></div></a></li><li class="depth-1 current"><a href="clojure.core.async.flow.spi.html"><div class="inner"><span>clojure.core.async.flow.spi</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="clojure.core.async.flow.spi.html#var-ProcLauncher"><div class="inner"><span>ProcLauncher</span></div></a></li><li class="depth-2 branch"><a href="clojure.core.async.flow.spi.html#var-describe"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>describe</span></div></a></li><li class="depth-2"><a href="clojure.core.async.flow.spi.html#var-start"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>start</span></div></a></li><li class="depth-1"><a href="clojure.core.async.flow.spi.html#var-Resolver"><div class="inner"><span>Resolver</span></div></a></li><li class="depth-2 branch"><a href="clojure.core.async.flow.spi.html#var-get-exec"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>get-exec</span></div></a></li><li class="depth-2"><a href="clojure.core.async.flow.spi.html#var-get-write-chan"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>get-write-chan</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">clojure.core.async.flow.spi</h1><div class="doc"><pre class="plaintext"></pre></div><div class="public anchor" id="var-ProcLauncher"><h3>ProcLauncher</h3><h4 class="type">protocol</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Note - defining a ProcLauncher is an advanced feature and should not
be needed for ordinary use of the library. This protocol is for
creating new types of Processes that are not possible to create
with ::flow/process.

A ProcLauncher is a constructor for a process, a thread of activity.
It has two functions - to describe the parameters and input/output
requirements of the process and to start it. The launcher should
acquire no resources, nor retain any connection to the started
process. A launcher may be called upon to start a process more than
once, and should start a new process each time start is called.

The process launched process must obey the following:

It must have 2 logical statuses, :paused and :running. In
the :paused status operation is suspended and no output is
produced.

When the process starts it must be :paused

Whenever it is reading or writing to any channel a process must use
alts!! and include a read of the ::flow/control channel, giving it
priority.

Command messages sent over the ::flow/control channel have the keys:
::flow/to - either ::flow/all or a process id
::flow/command - ::flow/stop|pause|resume|ping or process-specific

It must act upon any, and only, control messages whose ::flow/to key is its pid or ::flow/all
It must act upon the following values of ::flow/command:

::flow/stop - all resources should be cleaned up and any thread(s)
   should exit ordinarily - there will be no more subsequent use
   of the process.
::flow/pause - enter the :paused status
::flow/resume - enter the :running status and resume processing
::flow/ping - emit a ping message (format TBD) to
   the ::flow/report channel containing at least its pid and status

A process can define and respond to other commands in its own namespace.

A process should not transmit channel objects (use [pid io-id] data
coordinates instead) A process should not close channels

Finally, if a process encounters an error it must report it on the
::flow/error channel (format TBD) and attempt to continue, though it
may subsequently get a ::flow/stop command it must respect</pre></div><div class="members"><h4>members</h4><div class="inner"><div class="public anchor" id="var-describe"><h3>describe</h3><div class="usage"><code>(describe p)</code></div><div class="doc"><pre class="plaintext">returns a map with keys - :params, :ins and :outs,
each of which in turn is a map of keyword to docstring

:params describes the initial arguments to setup the state for the process
:ins enumerates the input[s], for which the graph will create channels
:outs enumerates the output[s], for which the graph may create channels.

describe may be called by users to understand how to use the
proc. It will also be called by the impl in order to discover what
channels are needed.</pre></div></div><div class="public anchor" id="var-start"><h3>start</h3><div class="usage"><code>(start p {:keys [pid args ins outs resolver]})</code></div><div class="doc"><pre class="plaintext">return ignored, called for the
effect of starting the process (typically, starting its thread)

where:

:pid - the id of the process in the graph, so that e.g. it can refer to itself in control, reporting etc
:args - a map of param-&gt;val,  as supplied in the graph def
:ins - a map of in-id-&gt;readable-channel, plus the ::flow/control channel
:outs - a map of out-id-&gt;writeable-channel, plus the ::flow/error and ::flow/report channels
        N.B. outputs may be nil if not connected
:resolver - an impl of spi/Resolver, which can be used to find
            channels given their logical [pid cid] coordinates, as well as to
            obtain ExecutorServices corresponding to the
            logical :mixed/:io/:compute contexts</pre></div></div></div></div></div><div class="public anchor" id="var-Resolver"><h3>Resolver</h3><h4 class="type">protocol</h4><div class="usage"></div><div class="doc"><pre class="plaintext"></pre></div><div class="members"><h4>members</h4><div class="inner"><div class="public anchor" id="var-get-exec"><h3>get-exec</h3><div class="usage"><code>(get-exec _ context)</code></div><div class="doc"><pre class="plaintext">returns the ExecutorService for the given context, one
of :mixed, :io, :compute</pre></div></div><div class="public anchor" id="var-get-write-chan"><h3>get-write-chan</h3><div class="usage"><code>(get-write-chan _ coord)</code></div><div class="doc"><pre class="plaintext">Given a tuple of [pid cid], returns a core.async chan to
write to or nil (in which case the output should be dropped,
e.g. nothing is connected).</pre></div></div></div></div></div></div></body></html>