store/[org.clojure/clojure "1.8.0"] clj::clojure.core/agent

Official Documentation

Add notes
Arities
==================================================
   [state & options]

Docstring
==================================================
  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.

Source

(defn agent
  "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."
  {:added "1.0"
   :static true
   }
  ([state & options]
     (let [a (new clojure.lang.Agent state)
           opts (apply hash-map options)]
       (setup-reference a options)
       (when (:error-handler opts)
         (.setErrorHandler a (:error-handler opts)))
       (.setErrorMode a (or (:error-mode opts)
                            (if (:error-handler opts) :continue :fail)))
       a)))

Example 1

Edit
;; 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 changes its value:
(send counter inc)
;; => nil

;; @ 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")
;; => nil

@pulp-fiction
;; => {:act-one "PROLOGUE"}

(send pulp-fiction assoc :act-two "VINCENT VEGA & MARSELLUS WALLACE'S WIFE")
;; => nil

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

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

Uses on crossclj