The[flow](https://clojure.github.io/core.async/flow.html) library enables a strict separation application logic from the deployment concerns of topology, execution, communication, lifecycle, monitoring and error handling.

You provide logic to flow in the form of_step-fns_, which are wrapped into running processes, executing in a loop. Flow manages the life cycle of the process and handles incoming and outgoing messages by putting or taking them on channels. Step-fns do not access channels directly or hold state, making them easy to test in isolation and reuse.

Step functions have four arities:

<ahref="https://github.com/clojure/core.async/blob/master/doc/img/step-fn-arities.png?raw=true"><imgsrc="https://github.com/clojure/core.async/blob/master/doc/img/step-fn-arities.png?raw=true"alt="step-fn arities"width="700"/></a>

The describe arity must return a static description of the step-fn's:params,:ins, and:outs. Each of these is a map of name (a keyword) to docstring.

The names used for input and output channels should be distinct (no overlap).

The init arity is called once by the process to takes a set of args from the flow def (corresponding to the params returned from the describe arity) and returns the init state of the process.

Theprocess state isa map. It can contain any keys needed bythestep-fn transition andtransform arities. In addition, there are some flow-specific keys, described here.

Thetransition arity iscalled any time the flow or process undergoes a lifecycle transition (::flow/start, ::flow/stop, ::flow/pause, ::flow/resume). The description arity takesthecurrent state andreturns an updated state to be used for subsequent calls.

`::flow/pid` is added to thestate bytheprocess based on the name suppliedinthe flow def.

The step-fn should use thetransition arity to coordinatethecreation, pausing, and shutdown of external resourcesina process.

`::flow/in-ports` and`::flow/out-ports` are maps of cid to external channel, optionally returned in the initialstatefrom the init arity. The in-ports andout-ports are used to connect source and sink processes to external channels. These channels must be provided by the step-fn and returned in the init arity map, either by creating the channel or using a channel passed in via the flow def init args for the process. The flow does not manage the lifecycle of these channels.

`::flow/input-filter`, a predicateofcid, can be returned inthestate from any aritytoindicate a filter ontheprocessinputchannel read set. For example, a step-fn that is waiting for a response from multiple inputs might remove the channels that have already responded from the read-set until responses have been received from all.

The transform arity is called in a loop by the process for every message received on aninput channel and returns a new state and a mapofoutput cids to messages to return. The process will take care of sending these messages totheoutput channels. Output can be senttonone, any or all ofthe:outsenumerated, and/or aninputnamed by a[pid inid] tuple (e.g. for reply-to), and/or to the ::flow/report output. A step need not output at all (output or msgs can be empyt/nil), however an output_message_ may never be nil (per core.async channels).

The step-fn may throw excepitons from anyarity and they will be handled by flow. Exceptions thrown from the transition or transform arities, the exception will be logged on the flow's:error-chan.

The transition arity is called any time the flow or process undergoes a lifecycle transition (::flow/start, ::flow/stop, ::flow/pause, ::flow/resume). The description arity takes the currentstate and returns an updated state to be used for subsequent calls.

Thestep-fn should use the transition arity to coordinatethecreation, pausing, andshutdown of external resources in a process.

Theprocess state is a map. It can contain any keys needed bythestep-fn transition andtransform arities. In addition, there are some flow-specific keys, described here.

The transform arity is called in a loop by the process for every message received on an input channel and returns a new stateanda map of output cidstomessages to return. The process will take care of sending these messages totheoutput channels. Output can be sent to none, any or all ofthe:outsenumerated, and/oran input named by a[pid inid] tuple (e.g. for reply-to), and/or tothe::flow/report output. A step need notoutput at all (output or msgs can be empyt/nil), however an output_message_ may never be nil (per core.asyncchannels).

`::flow/in-ports` and`::flow/out-ports` are maps of cid to external channel, optionally returned in the initial state from the init arity. The in-portsandout-ports are usedtoconnect source and sink processes to external channels. These channels must be provided bythestep-fn and returned in the init arity map, either by creatingthechannelorusing a channel passed in via the flow def init args fortheprocess. The flow does notmanage the lifecycle of thesechannels.

The step-fn may throw excepitonsfrom any arityand they will be handled by flow. Exceptions thrownfrom thetransition or transform arities,theexception will be logged on the flow's:error-chan.

`::flow/input-filter`, a predicate of cid, can be returned in the statefrom any arityto indicate a filter on the process input channel read set. For example, a step-fn that is waiting for a responsefrommultiple inputs might removethechannels that have already responded fromtheread-set until responses have been received from all.

Some additional helpers exist to create step-fns from other forms:

*`lift*->step` - given a fn f taking one arg and returning a collection of non-nil values, creates a step-fn as needed by a process, with one input and one output (named:in and:out), and no state

*`lift*->step` - given a fn f taking one arg and returning a collection of non-nil values, creates a step-fn as needed by a process launcher, with one input and one output (named:in and:out), and no state

*`lift1->step` - like`lift*->step` but for functions that return a single value (when`nil`, yield no output)

*`map->step` - given a map with keys`:describe`,`:init`,`:transition`,`:transform` corresponding to the arities above, create a step-fn.

Processes can be created using the[process](https://clojure.github.io/core.async/clojure.core.async.flow.html#var-process) function, which takes a step-fn, and an option map with keys:

Process launchers can be created using the[process](https://clojure.github.io/core.async/clojure.core.async.flow.html#var-process) function, which takes a step-fn, and an option map with keys:

*`::workload` - one of`:mixed`,`:io` or`:compute`

*`:compute-timeout-ms` - if:workload is:compute, this timeout (default 5000 msec) will be used when getting the return from the future - see below

A:workload supplied as an option to process will override any:workload returned by the:describe fn of the process. If neither are provded the default is:mixed.

A:workload supplied as an option to`process` will override any:workload returned by the:describe fn of the process launcher. If neither are provded the default is:mixed.

In the:workload context of:mixed or:io, this dictates the type of thread in which the process loop will run,_including its calls to transform_.

When:compute is specified transform must not block!

Note that process launchers are defined by the[ProcLauncher](https://clojure.github.io/core.async/clojure.core.async.flow.spi.html#var-ProcLauncher) protocol. While you will typically use`process` to create a process launcher, advanced uses may also implement the protocol directly.

Because the step-fn is called in a loop, it is a good practice to define the step-fn in a var and use the var (`#'the-fn`) instead of the function value itself (`the-fn`). This practice supports interactive development by allowing the var to be rebound from the repl while the flow is running.

The step-fns are how you supply code for each process in the flow. The other thing you must supply is the flow configuration that ties together theprocs and the connections between them.

The step-fns are how you supply code for each process in the flow. The other thing you must supply is the flow configuration that ties together theproc launchers and the connections between them.

This flow definition is supplied to the[create-flow](https://clojure.github.io/core.async/clojure.core.async.flow.html#var-create-flow) function and consists of a map with`:procs`,`:conns`, and optionally some workflow executors.

The`:procs` is a map of pid -> proc-def. The proc-def is a map with`:proc` (the processfunction), the`:args` (passed to the init arity of the step-fn), and the`:chan-opts` which can be used to specify channel properties.

The`:procs` is a map of pid -> proc-def. The proc-def is a map with`:proc` (the processlauncher), the`:args` (passed to the init arity of the step-fn), and the`:chan-opts` which can be used to specify channel properties.

The`:conns` is a collection of`[[from-pid outid] [to-pid inid]]` tuples. Inputs and outputs support multiple connections. When an output is connected multiple times, every connection will get every message, per`core.async/mult`.

* [pause-proc](https://clojure.github.io/core.async/clojure.core.async.flow.html#var-pause-proc) - Pauses a single proc

* [resume-proc](https://clojure.github.io/core.async/clojure.core.async.flow.html#var-resume-proc) - Resumes a single proc

You can alsouse these functions to ping the running processesare return their current state and status:

You can alsouse these functions to ping the running processesand return their current state and status:

* [ping](https://clojure.github.io/core.async/clojure.core.async.flow.html#var-ping) - Pings all procs and returns a map of their status

* [ping-proc](https://clojure.github.io/core.async/clojure.core.async.flow.html#var-ping-proc) - Pings a single proce by pid and returns a map of status