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 watchers list.