 (ns cmr.common.cache.single-thread-lookup-cache
-  "The single thread lookup cache is a cache that will only execute the lookup function passed
-  when retrieving a value on a single thread. It should be used when the lookup function is very
-  expensive and you want to minimize the number of times it's called.
+  "Defines a cache that serializes all calls to execute the lookup function on a single thread. It
+  should be used when the lookup function is very expensive and you want to minimize the number of
+  times it's called.
 
   When the value is already is cached the request for a value is very fast. When the value is not
   cached a request is queued to fetch the value. A separate thread processes these requests off a

   ;; The underlying cache this will delegate to.
   delegate-cache

   ;; A core.async channel. Each message will contain a map with the :lookup-fn, :key, and :response-channel
   lookup-request-channel

   ;; The single thread channel per cache instance that will listen for messages on the
   ;; lookup-request-channel.
   lookup-process-thread-channel
   ]


    ;; Attempt to read messages from the lookup request channel until it's closed.
    (u/while-let
      [{:keys [key lookup-fn response-channel]} (<!! lookup-request-channel)]
      ;; Get the requested value and put it back on the response channel.
      ;; The delegate will determine if calling the lookup function is necessary.
      (>!! response-channel (c/get-value delegate-cache key lookup-fn)))))


