Vars and the Global Environment

Clojure is a practical language that recognizes the occasional need to maintain a persistent reference to a changing value and provides 4 distinct mechanisms for doing so in a controlled manner - Vars, Refs, Agents and Atoms. Vars provide a mechanism to refer to a mutable storage location that can be dynamically rebound (to a new storage location) on a per-thread basis. Every Var can (but needn't) have a root binding, which is a binding that is shared by all threads that do not have a per-thread binding. Thus, the value of a Var is the value of its per-thread binding, or, if it is not bound in the thread requesting the value, the value of the root binding, if any.

The special form def creates (and interns) a Var. If the Var did not already exist and no initial value is supplied, the var is unbound:
user=> (def x)
user=> x
java.lang.IllegalStateException: Var user/x is unbound.
Supplying an initial value binds the root (even if it was already bound).
user=> (def x 1)
user=> x
By default Vars are static, but per-thread bindings for Vars defined with metadata mark them as dynamic can be established via the macro binding and within-thread they obey a stack discipline:
user=> (def ^:dynamic x 1)
user=> (def ^:dynamic y 1)
user=> (+ x y)
user=> (binding [x 2 y 3]
         (+ x y))
user=> (+ x y)
Bindings created with binding cannot be seen by any other thread. Likewise, bindings created with binding can be assigned to, which provides a means for a nested context to communicate with code before it on the call stack. This capability is opt-in only by setting a metadata tag :dynamic to true as in the code block above. There are scenarios that one might wish to redefine static Vars within a context and Clojure (since version 1.3) provides the functions with-redefs and with-redefs-fn for such purposes.

Functions defined with defn are stored in Vars, allowing for the re-definition of functions in a running program. This also enables many of the possibilities of aspect- or context-oriented programming. For instance, you could wrap a function with logging behavior only in certain call contexts or threads.

(set! var-symbol expr)

Assignment special form.

When the first operand is a symbol, it must resolve to a global var. The value of the var's current thread binding is set to the value of expr. Currently, it is an error to attempt to set the root binding of a var using set!, i.e. var assignments are thread-local.
In all cases the value of expr is returned.

Note - you cannot assign to function params or local bindings. Only Java fields, Vars, Refs and Agents are mutable in Clojure.

Using set for Java fields is documented in Java Interop.


The Namespace system maintains global maps of symbols to Var objects (see Namespaces). If a def expression does not find an interned entry in the current namespace for the symbol being def-ed, it creates one, otherwise it uses the existing Var. This find-or-create process is called interning. This means that, unless they have been unmap-ed, Var objects are stable references and need not be looked up every time. It also means that namespaces constitute a global environment in which, as described in Evaluation, the compiler attempts to resolve all free symbols as Vars.

The var special form or the #' reader macro (see Reader) can be used to get an interned Var object instead of its current value.

Non-interned Vars

It is possible to create vars that are not interned by using with-local-vars. These vars will not be found during free symbol resolution, and their values have to be accessed manually. But they can serve as useful thread-local mutable cells.

Related functions

Variants of def: defn defn- definline defmacro defmethod defmulti defonce defstruct

Working with interned Vars: declare intern binding find-var var

Working with Var objects: with-local-vars var-get var-set alter-var-root var? with-redefs with-redefs-fn

Var validators: set-validator get-validator

Common Var metadata: doc find-doc test
Logo & site design by Tom Hickey.