Clojure - Watchers

Watchers are functions added to variable types such as atoms and reference variables which get invoked when a value of the variable type changes. For example, if the calling program changes the value of an atom variable, and if a watcher function is attached to the atom variable, the function will be invoked as soon as the value of the atom is changed.

The following functions are available in Clojure for Watchers.

add-watch

Adds a watch function to an agent/atom/var/ref reference. The watch ‘fn’ must be a ‘fn’ of 4 args: a key, the reference, its old-state, its new-state. Whenever the reference's state might have been changed, any registered watches will have their functions called.

Syntax

Following is the syntax.

(add-watch variable :watcher
   (fn [key variable-type old-state new-state]))

Parameters − ‘variable’ is the name of the atom or reference variable. ‘variable-type’ is the type of variable, either atom or reference variable. ‘old-state & new-state’ are parameters that will automatically hold the old and new value of the variable. ‘key’ must be unique per reference, and can be used to remove the watch with remove-watch.
Return Value − None.

Example

An example on how this is used is shown in the following program.

(ns clojure.examples.example
   (:gen-class))
(defn Example []
   (def x (atom 0))
   (add-watch x :watcher
      (fn [key atom old-state new-state]
      (println "The value of the atom has been changed")
      (println "old-state" old-state)
      (println "new-state" new-state)))
(reset! x 2))
(Example)

Output

The above program produces the following output.

The value of the atom has been changed
old-state 0
new-state 2

remove-watch

Removes a watch which has been attached to a reference variable.

Syntax

Following is the syntax.

(remove-watch variable watchname)

Parameters − ‘variable’ is the name of the atom or reference variable. ‘watchname’ is the name given to the watch when the watch function is defined.
Return Value − None.

Example

An example on how this is used is shown in the following program.

(ns clojure.examples.example
   (:gen-class))
(defn Example []
   (def x (atom 0))
   (add-watch x :watcher
      (fn [key atom old-state new-state]
         (println "The value of the atom has been changed")
         (println "old-state" old-state)
         (println "new-state" new-state)))
   (reset! x 2)
   (remove-watch x :watcher)
(reset! x 4))
(Example)

Output

The above program produces the following output.

The value of the atom has been changed
old-state 0
new-state 2

You can clearly see from the above program that the second reset command does not trigger the watcher since it was removed from the watcher’s list.