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


-- | Bundles shared calls to IO functions to perform them only once
--   
--   Bundles shared calls to IO functions to perform them only once
@package sharedio
@version 0.1.0


-- | Allows <a>bundling</a> or <a>throttling</a> of concurrent IO to
--   perform computation only once.
--   
--   Useful in situations where concurrency can be expensive, such as file
--   system scans (where concurrent execution usually returns the same
--   result but introduces much disk seeking overhead).
module Control.Concurrent.SharedIO

-- | A <a>sharing lock</a> on a shared IO computation.
--   
--   When it is <a>free</a>, a computation can be started on it.
--   
--   When it is <a>locked</a>, started computation will not execute, but
--   instead block until the running computation finished, and receive the
--   same result.
data SharedIO a

-- | Creates a new sharing lock.
newSharedIO :: IO (SharedIO a)

-- | Request to start a computation on the given sharing lock.
--   
--   If a computation is already running on that lock, the requested
--   computation will not start, but instead block for the running
--   computation to finish and return the same result for all threads
--   waiting for it.
--   
--   Ensures that (a)synchronous exceptions in the computation will be
--   forwarded to all threads waiting for its result.
--   
--   Example:
--   
--   <ul>
--   <li>- A webserver that lists directory contents, using -- SharedIO to
--   bundle clients fanatically hitting refresh.</li>
--   <li>- Without this, the file seeking would slow the server to a
--   crawl.</li>
--   </ul>
--   
--   main = do fileScanSharedIO &lt;- newSharedIO runWebserver
--   (handleRequest fileScanSharedIO)
--   
--   handleRequest :: SharedIO -&gt; IO [FilePath] handleRequest
--   fileScanSharedIO = do withSharedIO fileScanSharedIO
--   (getDirectoryContents <a>largefolder</a>)
withSharedIO :: SharedIO a -> IO a -> IO a