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


-- | Run IO actions lazily while respecting their order
--   
--   Run IO actions lazily while respecting their order. Running a value of
--   the LazyIO monad in the IO monad is like starting a thread which is
--   however driven by its output. That is, the LazyIO action is only
--   executed as far as necessary in order to provide the required data.
--   
--   The package may help you to avoid stack overflows in <tt>mapM</tt>.
--   Say you have
--   
--   <pre>
--   mapM f xs
--   </pre>
--   
--   where <tt>xs</tt> is a long list. When run, you may encounter a stack
--   overflow. To prevent it, write instead:
--   
--   <pre>
--   import qualified System.IO.Lazy as LazyIO
--   
--   LazyIO.run $ mapM (LazyIO.interleave . f) xs
--   </pre>
--   
--   The stack overflow is gone.
@package lazyio
@version 0.1.0.4


-- | Caution:
--   
--   <ul>
--   <li>Although this module calls <tt>unsafeInterleaveIO</tt> for you, it
--   cannot take the responsibility from you. Using this module is still as
--   unsafe as calling <tt>unsafeInterleaveIO</tt> manually. Thus we
--   recommend to wrap the lazy I/O monad into a custom <tt>newtype</tt>
--   with a restricted set of operations which is considered safe for
--   interleaving I/O actions.</li>
--   <li>Operations like <a>hClose</a> are usually not safe within this
--   monad, since they will only get executed, if their result is consumed.
--   Since this result is often <tt>()</tt> this is quite unusual. It will
--   also often be the case, that not the complete output is read, and thus
--   the closing action is never reached. It is certainly best to call a
--   closing action after you wrote the complete result of the lazy I/O
--   monad somewhere.</li>
--   <li><tt>return a :: LazyIO a</tt> is very different from
--   <tt>interleave (return a) :: LazyIO a</tt>. The first one does not
--   trigger previous IO actions, whereas the second one does. This is the
--   reason why we do not instantiate <tt>MonadIO</tt> with <tt>liftIO =
--   LazyIO.interleave</tt>, despite the matching type signatures. One of
--   the <tt>MonadIO</tt> laws explicitly requires <tt>return a = liftIO
--   (return a)</tt>.</li>
--   <li>We advise to lift strict IO functions into the lazy IO monad.
--   Lifting a function like <tt>readFile</tt> may lead to unintended
--   interleaving. In the future we may enforce that using the
--   <tt>deepseq</tt> package.</li>
--   </ul>
--   
--   Use it like
--   
--   <pre>
--   import qualified System.IO.Lazy as LazyIO
--   
--   LazyIO.run $ do
--      LazyIO.interleave $ putStr "enter first line:"
--      x &lt;- LazyIO.interleave getLine
--      LazyIO.interleave $ putStr "enter second line:"
--      y &lt;- LazyIO.interleave getLine
--      return x
--   </pre>
--   
--   Because only the first entered line is needed, only the first prompt
--   and the first <a>getLine</a> is executed.
module System.IO.Lazy
data T a
run :: T a -> IO a
interleave :: IO a -> T a
instance GHC.Show.Show System.IO.Lazy.RunAll
instance GHC.Base.Monad System.IO.Lazy.T
instance GHC.Base.Functor System.IO.Lazy.T
instance GHC.Base.Applicative System.IO.Lazy.T
