Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Sequences and Laziness

Lazy Sequences

Learn how Clojure lazy sequences compute values only when needed: range, iterate, repeatedly, cycle, lazy-seq, realization, chunking and common laziness traps.

Most Clojure sequence functions are lazy. When you call (map inc (range 1000000)) nothing is computed yet; you receive a recipe that produces values one at a time (in small batches, as you will see) when something asks for them. Laziness lets you describe infinite sequences, avoid wasted work, and process data bigger than memory with the same code you use for tiny inputs.

It also has sharp edges: side effects that never run, resources that close too early, and memory held longer than expected. This lesson covers both sides. It builds on the sequence abstraction.

Clojure does not run in the site's editors. The Clojure code is read-only; the runnable examples use JavaScript generators, which are lazy in the same spirit.

Infinite sequences

Because values are produced on demand, a sequence can be infinite as long as you only consume a finite part.

CLOJURE
(take 5 (range))               ;=> (0 1 2 3 4)
(take 5 (iterate #(* 2 %) 1))  ;=> (1 2 4 8 16)
(take 7 (cycle [:a :b :c]))    ;=> (:a :b :c :a :b :c :a)
(take 3 (repeat "hi"))         ;=> ("hi" "hi" "hi")

The producers worth knowing:

  • (range) counts up forever; (range 10), (range 2 20 3) are finite.
  • (iterate f x) yields x, (f x), (f (f x)) and so on.
  • (repeat x) repeats one value; (repeatedly f) calls a function again and again (useful with random numbers or ID generators).
  • (cycle coll) loops through a collection forever.

Consumers such as take, take-while, first, nth and some stop early. A consumer that needs everything, such as count, reduce or vec, on an infinite sequence runs until memory is gone, so apply take or take-while first.

CLOJURE
(take-while #(< % 100) (iterate #(* % 3) 1))
;=> (1 3 9 27 81)

Writing your own: lazy-seq

The macro lazy-seq wraps a body that returns a sequence and delays it until someone calls seq on it. The classic pattern is a function that conses one value onto a lazy call to itself:

CLOJURE
(defn naturals [n]
  (lazy-seq (cons n (naturals (inc n)))))

(take 4 (naturals 1))   ;=> (1 2 3 4)

Without lazy-seq this would recurse forever (and overflow the stack). With it, (naturals 1) returns immediately; the call to (naturals 2) happens only when the second element is requested. Here is a Fibonacci sequence in the same style:

CLOJURE
(defn fibs
  ([] (fibs 0N 1N))
  ([a b] (lazy-seq (cons a (fibs b (+ a b))))))

(take 10 (fibs))   ;=> (0 1 1 2 3 5 8 13 21 34)

A good rule: build lazy sequences from existing functions (map, filter, iterate, take-while) and reach for lazy-seq only when you need a custom producer.

Realization and caching

A lazy sequence is realized when its values have actually been computed. Once realized, an element is cached in the sequence, so asking again does not recompute it.

CLOJURE
(def s (map (fn [x] (println "computing" x) (* x x)) [1 2 3]))
; nothing printed yet

(first s)
; prints: computing 1   (and, in practice, possibly more; see chunking)
(realized? s)   ;=> true  once the first cell exists

Caching means a lazy sequence is safe to traverse repeatedly, and (count s) after a full traversal does not rerun the work.

Chunked sequences

Sequences built from vectors and ranges are chunked: they realize elements in blocks of 32 for speed. So (first (map println (range 100))) may print 32 lines, not one. For purely functional code you will never notice; for code with side effects you will, which brings us to the traps.

Laziness traps

  1. Side effects inside map never run. (map println items) just creates a recipe. Use doseq (or run!) when you want the side effect, and map when you want the result.
  2. Forcing a result. dorun realizes a sequence and throws the results away; doall realizes and returns it.
  3. Resource scope. (with-open [r (reader f)] (line-seq r)) returns a lazy sequence of lines, but the reader is closed when with-open exits, so the first read fails. Realize inside the scope: (doall (line-seq r)), or process the lines there.
  4. Dynamic bindings. A lazy sequence evaluated outside a binding form will not see that binding.
  5. Holding the head. If you keep a reference to the first cell of a huge sequence while consuming it, none of the consumed cells can be garbage collected, and memory grows. Do not def a big lazy sequence at the top level if you only need to stream it.
  6. Stack overflow from nested laziness. Wrapping a sequence in thousands of nested concat or lazy-seq layers can overflow the stack when finally realized. Use into, mapcat or reduce for large merges.
CLOJURE
(def result (doall (map expensive-call ids)))   ; run now, keep results
(run! println ["a" "b"])                         ; side effects, no results

Laziness in practice

A common use is a pipeline over a large input where only part is needed:

CLOJURE
(->> (iterate inc 1)
     (filter #(zero? (mod % 7)))
     (map #(* % %))
     (take 3))
;=> (49 196 441)

Only the first 21 numbers are ever inspected; the rest of the infinite stream never exists. For a bounded "first that matches" search, (first (filter pred coll)) stops at the first hit. For counting a very large stream in constant memory, use reduce or a transducer, since they do not need to build intermediate sequences.

Try it: lazy generators

JavaScript generators are lazy: nothing runs until you pull. These helpers imitate iterate, take, filter and map and show that work happens one element at a time.

JS Lazy pipeline with generators

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: lazy-seq and caching

This stand-in builds a lazy-seq as a cell that remembers its value after the first call, so the "computing" message appears once per element.

JS A cached lazy cell

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does (map println [1 2 3]) do when evaluated and its result is thrown away?

    map is lazy. Nothing is realized unless something consumes the result. Use doseq or run! for side effects.
  2. 2. Which function realizes a lazy sequence and returns it?

    doall forces the entire sequence and returns it; dorun forces it but returns nil.
  3. 3. Why is (with-open [r (reader f)] (line-seq r)) a bug?

    The lazy sequence escapes the with-open scope, so the reader is closed when elements are first realized. Realize inside the scope.
  4. 4. What does (take 3 (cycle [:a :b])) return?

    cycle repeats the collection forever, and take stops after three items.

Summary

  • Most sequence functions are lazy: they compute values only when consumed, and cache them afterwards.
  • range, iterate, repeat, repeatedly and cycle produce infinite sequences; pair them with take or take-while.
  • lazy-seq plus cons builds a custom lazy producer.
  • Chunking realizes 32 elements at a time for vectors and ranges.
  • Beware side effects in map, resources closed too early, held heads and deep nesting; use doall, dorun, doseq and run! deliberately.

Next: Transducers