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


-- | handling concurrent output
--   
--   Provides a simple interface for writing concurrent programs that need
--   to output a lot of status messages to the console, and/or run
--   concurrent external commands that output to the console.
@package concurrent-output
@version 1.0.0


-- | Concurrent output handling.
--   
--   <pre>
--   import Control.Concurrent.Async
--   import Control.Concurrent.Output
--   
--   main = withConcurrentOutput $
--   	outputConcurrent "washed the car\n"
--   		`concurrently`
--   outputConcurrent "walked the dog\n"
--   	`concurrently`
--   	createProcessConcurrent (proc "ls" [])
--   </pre>
module Control.Concurrent.Output

-- | Use this around any IO actions that use <a>outputConcurrent</a> or
--   <a>createProcessConcurrent</a>
--   
--   This is necessary to ensure that buffered concurrent output actually
--   gets displayed before the program exits.
withConcurrentOutput :: IO a -> IO a

-- | Blocks until any processes started by <a>createProcessConcurrent</a>
--   have finished, and any buffered output is displayed.
flushConcurrentOutput :: IO ()

-- | Displays a string to stdout, and flush output so it's displayed.
--   
--   Uses locking to ensure that the whole string is output atomically even
--   when other threads are concurrently generating output.
--   
--   When something else is writing to the console at the same time, this
--   does not block. It buffers the string, so it will be displayed once
--   the other writer is done.
outputConcurrent :: String -> IO ()

-- | Wrapper around <a>createProcess</a> that prevents multiple processes
--   that are running concurrently from writing to stdout/stderr at the
--   same time.
--   
--   If the process does not output to stdout or stderr, it's run by
--   createProcess entirely as usual. Only processes that can generate
--   output are handled specially:
--   
--   A process is allowed to write to stdout and stderr in the usual way,
--   assuming it can successfully take the output lock.
--   
--   When the output lock is held (by another concurrent process, or
--   because <a>outputConcurrent</a> is being called at the same time), the
--   process is instead run with its stdout and stderr redirected to a
--   buffer. The buffered output will be displayed as soon as the output
--   lock becomes free.
createProcessConcurrent :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)

-- | This must be used to wait for processes started with
--   <a>createProcessConcurrent</a>.
--   
--   This is necessary because <a>waitForProcess</a> has a race condition
--   when two threads check the same process. If the race is triggered, one
--   thread will successfully wait, but the other throws a DoesNotExist
--   exception.
waitForProcessConcurrent :: ProcessHandle -> IO ExitCode

-- | Holds a lock while performing an action that will display output.
--   While this is running, other threads that try to lockOutput will
--   block, and calls to <a>outputConcurrent</a> and
--   <a>createProcessConcurrent</a> will result in that concurrent output
--   being buffered and not displayed until the action is done.
lockOutput :: (MonadIO m, MonadMask m) => m a -> m a
instance GHC.Classes.Eq Control.Concurrent.Output.BufferedActivity