CODEWITHSUNDEEP
clojure
tangrammer
tangrammer

Reputation: 3061

What's the meaning of :key parameter in add-watch function

My problem is that with the doc and examples providede i can't understand the meaning of :key parameter or its possible values This is the official doc page of the function that I'm referring:
http://clojuredocs.org/clojure_core/clojure.core/add-watch

add-watch clojure.core

(add-watch reference key fn)

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. The watch fn will be called synchronously, on the agent's thread if an agent, before any pending sends if agent or ref. Note that an atom's or ref's state may have changed again prior to the fn call, so use old/new-state rather than derefing the reference. Note also that watch fns may be called from multiple threads simultaneously. Var watchers are triggered only by root binding changes, not thread-local set!s. Keys must be unique per reference, and can be used to remove the watch with remove-watch, but are otherwise considered opaque by the watch mechanism.

Thanks

Upvotes: 5

Views: 1725

Answers (2)

Alex
Alex

Reputation: 13961

It's basically just an identifier that you can use in calling code to identify the watch, in case you have more than one watches per reference. It's something that should have significance to your application code, but will be passed through by Clojure.

For instance:

user> (def a (atom 0))
#'user/a
user> (add-watch a
                 :count-to-3
                 (fn [k r old-state new-state]
                     (println "changed from" old-state "to" new-state)
                     (when (>= new-state 3)
                       (remove-watch a :count-to-3))))
#<Atom@3287a10: 0>
user> (dotimes [_ 5] (swap! a inc))
changed from 0 to 1
changed from 1 to 2
changed from 2 to 3
nil
user> @a
5

Upvotes: 9

jgriego
jgriego

Reputation: 1266

The answer's right there:

Keys must be unique per reference, and can be used to remove the watch with remove-watch, but are otherwise considered opaque by the watch mechanism.

In other words, the actual watch mechanism doesn't care what you set the key to (as long as it's unique among the handlers set on the given ref), but you'll need to hang on to it if you ever want to call remove-watch to get rid of your handler

Upvotes: 8

Related Questions