<!DOCTYPE html PUBLIC ""

"">

<html><head><meta charset="UTF-8" /><title>Walkthrough</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 current"><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 "><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="document" id="content"><div class="doc"><div class="markdown"><h1><a href="#walkthrough" id="walkthrough"></a>Walkthrough</h1>

<h2><a href="#getting-started" id="getting-started"></a>Getting started</h2>

<p>The core.async library supports asynchronous programming through the use of channels.</p>

<p>To use core.async, declare a dependency on Clojure 1.10.0 or higher and the latest core.async library:</p>

<pre><code class="language-clojure">{:deps

{org.clojure/clojure {:mvn/version "1.12.0"}

org.clojure/core.async {:mvn/version "1.8.741"}}}

</code></pre>

<p>To start working with core.async, require the <code>clojure.core.async</code> namespace at the REPL:</p>

<pre><code class="language-clojure">(require '[clojure.core.async :as a :refer [&lt;!! &gt;!! &lt;! &gt;!]])

</code></pre>

<p>Or include it in your namespace:</p>

<pre><code class="language-clojure">(ns my.ns

(:require [clojure.core.async :as a :refer [&lt;!! &gt;!! &lt;! &gt;!]]))

</code></pre>

<h2><a href="#channels" id="channels"></a>Channels</h2>

<p>Values are conveyed on queue-like channels. By default channels are unbuffered (0-length) - they require producer and consumer to rendezvous for the transfer of a value through the channel.</p>

<p>Use <code>chan</code> to make an unbuffered channel:</p>

<pre><code class="language-clojure">(a/chan)

</code></pre>

<p>Pass a number to create a channel with a fixed buffer size:</p>

<pre><code class="language-clojure">(a/chan 10)

</code></pre>

<p><code>close!</code> a channel to stop accepting puts. Remaining values are still available to take. Drained channels return nil on take. Nils may not be sent over a channel explicitly!</p>

<pre><code class="language-clojure">(let [c (a/chan)]

(a/close! c))

</code></pre>

<p>Channels can also use custom buffers that have different policies for the “full” case. Two useful examples are provided in the API.</p>

<pre><code class="language-clojure">;; Use `dropping-buffer` to drop newest values when the buffer is full:

(a/chan (a/dropping-buffer 10))

;; Use `sliding-buffer` to drop oldest values when the buffer is full:

(a/chan (a/sliding-buffer 10))

</code></pre>

<h2><a href="#threads" id="threads"></a>Threads</h2>

<p>In ordinary threads, we use <code>&gt;!!</code> (blocking put) and <code>&lt;!!</code> (blocking take) to communicate via channels.</p>

<pre><code class="language-clojure">(let [c (a/chan 10)]

(&gt;!! c "hello")

(assert (= "hello" (&lt;!! c)))

(a/close! c))

</code></pre>

<p>Because these are blocking calls, if we try to put on an unbuffered channel, we will block the main thread. We can use <code>thread</code> (like <code>future</code>) to execute a body in a pool thread and return a channel with the result. Here we launch a background task to put “hello” on a channel, then read that value in the current thread.</p>

<pre><code class="language-clojure">(let [c (a/chan)]

(a/thread (&gt;!! c "hello"))

(assert (= "hello" (&lt;!! c)))

(a/close! c))

</code></pre>

<h2><a href="#go-blocks-and-ioc-threads" id="go-blocks-and-ioc-threads"></a>Go Blocks and IOC Threads</h2>

<p>The <code>go</code> macro asynchronously executes its body in a special pool of threads. Channel operations that would block will pause execution instead, blocking no threads. This mechanism encapsulates the inversion of control that is external in event/callback systems. Inside <code>go</code> blocks, we use <code>&gt;!</code> (put) and <code>&lt;!</code> (take).</p>

<p>Here we convert our prior channel example to use go blocks:</p>

<pre><code class="language-clojure">(let [c (a/chan)]

(a/go (&gt;! c "hello"))

(assert (= "hello" (&lt;!! (a/go (&lt;! c)))))

(a/close! c))

</code></pre>

<p>Instead of the explicit thread and blocking call, we use a go block for the producer. The consumer uses a go block to take, then returns a result channel, from which we do a blocking take.</p>

<p>== Alts</p>

<p>One killer feature for channels over queues is the ability to wait on many channels at the same time (like a socket select). This is done with <code>alts!!</code> (ordinary threads) or <code>alts!</code> in go blocks.</p>

<p>We can create a background thread with alts that combines inputs on either of two channels. <code>alts!!</code> takes a set of operations to perform - either a channel to take from or a channel value to put and returns the value (nil for put) and channel that succeeded:</p>

<pre><code class="language-clojure">(let [c1 (a/chan)

c2 (a/chan)]

(a/thread (while true

(let [[v ch] (a/alts!! [c1 c2])]

(println "Read" v "from" ch))))

(&gt;!! c1 "hi")

(&gt;!! c2 "there"))

</code></pre>

<p>Prints (on stdout, possibly not visible at your repl):</p>

<pre><code>Read hi from #object[clojure.core.async.impl.channels.ManyToManyChannel ...]

Read there from #object[clojure.core.async.impl.channels.ManyToManyChannel ...]

</code></pre>

<p>We can use alts! to do the same thing with go blocks:</p>

<pre><code class="language-clojure">(let [c1 (a/chan)

c2 (a/chan)]

(a/go (while true

(let [[v ch] (a/alts! [c1 c2])]

(println "Read" v "from" ch))))

(a/go (&gt;! c1 "hi"))

(a/go (&gt;! c2 "there")))

</code></pre>

<p>Since go blocks are lightweight processes not bound to threads, we can have LOTS of them! Here we create 1000 go blocks that say hi on 1000 channels. We use alts!! to read them as they’re ready.</p>

<pre><code class="language-clojure">(let [n 1000

cs (repeatedly n a/chan)

begin (System/currentTimeMillis)]

(doseq [c cs] (a/go (&gt;! c "hi")))

(dotimes [i n]

(let [[v c] (a/alts!! cs)]

(assert (= "hi" v))))

(println "Read" n "msgs in" (- (System/currentTimeMillis) begin) "ms"))

</code></pre>

<p><code>timeout</code> creates a channel that waits for a specified ms, then closes:</p>

<pre><code class="language-clojure">(let [t (a/timeout 100)

begin (System/currentTimeMillis)]

(&lt;!! t)

(println "Waited" (- (System/currentTimeMillis) begin)))

</code></pre>

<p>We can combine timeout with <code>alts!</code> to do timed channel waits. Here we wait for 100 ms for a value to arrive on the channel, then give up:</p>

<pre><code class="language-clojure">(let [c (a/chan)

begin (System/currentTimeMillis)]

(a/alts!! [c (a/timeout 100)])

(println "Gave up after" (- (System/currentTimeMillis) begin)))

</code></pre>

</div></div></div></body></html>