agent

added
1.0

ns
clojure.core

type
function

(agent state & options)

Creates and returns an agent with an initial value of state and
zero or more options (in any order):

:meta metadata-map

:validator validate-fn

:error-handler handler-fn

:error-mode mode-keyword

If metadata-map is supplied, it will become the metadata on the
agent. validate-fn must be nil or a side-effect-free fn of one
argument, which will be passed the intended new state on any state
change. If the new state is unacceptable, the validate-fn should
return false or throw an exception.  handler-fn is called if an
action throws an exception or if validate-fn rejects a new state --
see set-error-handler! for details.  The mode-keyword may be either
:continue (the default if an error-handler is given) or :fail (the
default if no error-handler is given) -- see set-error-mode! for
details.

                ;; Agents provide shared access to mutable state. 
;; They allow non-blocking (asynchronous as opposed 
;; to synchronous atoms) and independent change of 
;; individual locations (unlike coordinated change 
;; of multiple locations through refs).

;; agent creates one:
(def counter (agent 0))
;; #'user/counter

;; send requests a change to its value:
(send counter inc)

; @ or deref provides a snapshot of the current state:
@counter
;;=> 1

;; agents can reference any data structure:

(def pulp-fiction (agent {}))
;; #'user/pulp-fiction

(send pulp-fiction assoc :act-one "PROLOGUE")
@pulp-fiction
;;=> {:act-one "PROLOGUE"}

(send pulp-fiction assoc :act-two "VINCENT VEGA & MARSELLUS WALLACE'S WIFE")
@pulp-fiction
;;=> {:act-two "VINCENT VEGA & MARSELLUS WALLACE'S WIFE", :act-one "PROLOGUE"}

; From http://clojure-examples.appspot.com/clojure.core/agent with permission.