-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Memoize IO actions
--   
--   Transform an IO action into a similar IO action that performs the
--   original action only once.
--   
--   You can choose to perform the original action in one of two ways:
--   
--   <ol>
--   <li>lazily (might never be performed)</li>
--   <li>eagerly (concurrently performed)</li>
--   </ol>
--   
--   Special thanks to shachaf and headprogrammingczar from #haskell irc
--   for helping me reason about the behavior of this library.
@package io-memoize
@version 1.1.1.0

module Control.Concurrent.Cache

-- | A thread-safe write-once cache. If you need more functionality, (e.g.
--   multiple write, cache clearing) use an <a>MVar</a> instead.
data Cache a

-- | Create an empty cache.
newCache :: IO (Cache a)

-- | Fetch the value stored in the cache, or call the supplied fallback and
--   store the result, if the cache is empty.
fetch :: Cache a -> IO a -> IO a
instance GHC.Classes.Eq (Control.Concurrent.Cache.Cache a)


-- | Memoize IO actions, performing them at most once, but recalling their
--   result for subsequent invocations. This library provides two
--   sequencing strategies: lazy (<a>once</a>), and concurrent
--   (<a>eagerlyOnce</a>).
--   
--   The following property holds: <tt>join . once === id</tt>. The same is
--   true for <tt>eagerlyOnce</tt>.
--   
--   The memory allocated for a memoized result will obviously not be
--   available for garbage collection until the corresponding memoized
--   action is also available for garbage collection.
module System.IO.Memoize

-- | Memoize an IO action. The action will be performed the first time that
--   it its value is demanded; all subsequent invocations will simply
--   recall the value acquired from the first call. If the value is never
--   demanded, then the action will never be performed.
--   
--   This is basically a safe version of <a>unsafeInterleaveIO</a>.
--   Exceptions will be propagated to the caller, and the action will be
--   retried at each invocation, only until it has successfully completed
--   once.
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; getLine' &lt;- once getLine
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; replicateM 3 getLine'
--   Hello
--   ["Hello", "Hello", "Hello"]
--   </pre>
once :: IO a -> IO (IO a)

-- | Memoize an IO action. The action will be started immediately in a new
--   thread. Attempts to access the result will block until the action is
--   finished. If the action produces an error, then attempts to access its
--   value will re-raise the same error each time.
eagerlyOnce :: IO a -> IO (IO a)

-- | <i>Deprecated: Please use <a>once</a>.</i>
ioMemo :: IO a -> IO (IO a)

-- | Memoize an IO action. The action will be performed immediately; all
--   subsequent invocations will recall the value acquired.

-- | <i>Deprecated: Please just call the action directly.</i>
ioMemo' :: IO a -> IO (IO a)

-- | <i>Deprecated: Please use <a>eagerlyOnce</a>.</i>
ioMemoPar :: IO a -> IO (IO a)
