This guide covers:

  • What are lazy sequences
  • Pitfalls with lazy sequences
  • How to create functions that produce lazy sequences
  • How to force evaluation

This work is licensed under a Creative Commons Attribution 3.0 Unported License (including images & stylesheets). The source is available on Github.

What Version of Clojure Does This Guide Cover?

This guide covers Clojure 1.5.


Clojure is not a lazy language.

However, Clojure supports lazily evaluated sequences. This means that sequence elements are not available ahead of time and produced as the result of a computation. The computation is performed as needed. Evaluation of lazy sequences is known as realization.

Lazy sequences can be infinite (e.g. the sequence of Fibonacci numbers, a sequence of dates with a particular interval between them, and so on). If a lazy sequence is finite, when its computation is completed, it becomes fully realized.

When it is necessary to fully realize a lazy sequence, Clojure provides a way to force evaluation (force realization).

Benefits of Lazy Sequences

Lazy sequences have two main benefits:

  • They can be infinite
  • Full realization of interim results can be avoided

Producing Lazy Sequences

Lazy sequences are produced by functions. Such functions either use the clojure.core/lazy-seq macro or other functions that produce lazy sequences.

clojure.core/lazy-seq accepts one or more forms that produce a sequence of nil (when the sequence is fully realized) and returns a seqable data structure that invokes the body the first time the value is needed and then caches the result.

For example, the following function produces a lazy sequence of random UUIDs strings:

(defn uuid-seq
   (cons (str (random-uuid))

Note: the random-uuid function is available in ClojureScript and was introduced into Clojure in version 1.11 Alpha 3. Prior to that, you needed to use Java interop:

(defn uuid-seq
   (cons (str (java.util.UUID/randomUUID))

Another example:

(defn fib-seq
  "Returns a lazy sequence of Fibonacci numbers"
     (fib-seq 0 1))
  ([a b]
      (cons b (fib-seq b (+ a b))))))

Both examples use clojure.core/cons which prepends an element to a sequence. The sequence can in turn be lazy, which both of the examples rely on.

Even though both of these sequences are infinite, taking first N elements from each does return successfully:

(take 3 (uuid-seq))
(take 10 (fib-seq))
(take 20 (fib-seq))

Realizing Lazy Sequences (Forcing Evaluation)

Lazy sequences can be forcefully realized with clojure.core/dorun and clojure.core/doall. The difference between the two is that dorun throws away all results and is supposed to be used for side effects, while doall returns computed values:

(dorun (map inc [1 2 3 4]))
(doall (map inc [1 2 3 4]))

Commonly Used Functions That Produce Lazy Sequences

Multiple frequently used clojure.core functions return lazy sequences, most notably:

  • map
  • filter
  • remove
  • range
  • take
  • take-while
  • drop
  • drop-while

The following example uses several of these functions to return 10 first even numbers in the range of [0, n):

(take 10 (filter even? (range 0 100)))

Several functions in clojure.core are designed to produce lazy sequences:

  • repeat
  • iterate
  • cycle

For example:

(take 3 (repeat "ha"))
(take 5 (repeat "ha"))
(take 3 (cycle [1 2 3 4 5]))
(take 10 (cycle [1 2 3 4 5]))
(take 3 (iterate (partial + 1) 1))
(take 5 (iterate (partial + 1) 1))

Lazy Sequences Chunking

There are two fundamental strategies for implementing lazy sequences:

  • Realize elements one-by-one
  • Realize elements in groups (chunks, batches)

In Clojure 1.1+, lazy sequences are chunked (realized in chunks).

For example, in the following code

(take 10 (range 1 1000000000000))

one-by-one realization would realize one element 10 times. With chunked sequences, elements are realized ahead of time in chunks (32 elements at a time).

This reduces the number of realizations and, for many common workloads, improves efficiency of lazy sequences.


Michael Klishin, 2013 (original author)