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

Official Documentation

Add notes
Arities
==================================================
   []

Docstring
==================================================
  Returns a promise object that can be read with deref/@, and set,
  once only, with deliver. Calls to deref/@ prior to delivery will
  block, unless the variant of deref with timeout is used. All
  subsequent derefs will return the same delivered value without
  blocking. See also - realized?.

Source

(defn promise
  "Returns a promise object that can be read with deref/@, and set,
  once only, with deliver. Calls to deref/@ prior to delivery will
  block, unless the variant of deref with timeout is used. All
  subsequent derefs will return the same delivered value without
  blocking. See also - realized?."
  {:added "1.1"
   :static true}
  []
  (let [d (java.util.concurrent.CountDownLatch. 1)
        v (atom d)]
    (reify 
     clojure.lang.IDeref
       (deref [_] (.await d) @v)
     clojure.lang.IBlockingDeref
       (deref
        [_ timeout-ms timeout-val]
        (if (.await d timeout-ms java.util.concurrent.TimeUnit/MILLISECONDS)
          @v
          timeout-val))  
     clojure.lang.IPending
      (isRealized [this]
       (zero? (.getCount d)))
     clojure.lang.IFn
     (invoke
      [this x]
      (when (and (pos? (.getCount d))
                 (compare-and-set! v d x))
        (.countDown d)
        this)))))

Example 1

Edit
(def x (promise))
;; => #'user/x

;; Dereferencing a promise blocks on a value being delivered to that promise. So
;; trying to deref x at this point will make your repl wait forever since
;; nothing has been delivered to x yet.

(deliver x 100)
;; => #<core$promise$reify__5534@4369a50b: 100>

;; x has now had a value delivered, so we can dereference it and we expect to
;; get back the 100 we delivered..

@x
;; => 100

Example 2

Edit
;; Create a promise
(def p (promise))
;; => #'user/p
;; p is our promise

;; Check if was delivered/realized
(realized? p)
;; => false
;; No yet

;; Delivering the promise
(deliver p 42)
;; => #<core$promise$reify__5727@47122d: 42>

;; Check again if it was delivered
(realized? p)
;; => true
;; Yes!

;; Deref to see what has been delivered
@p
;; => 42

;; Note that @ is shorthand for deref
(deref p)
;; => 42

Uses on crossclj