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

-- | Closable, fair, single-wakeup channel type that avoids 0
--   reader space leaks.
--   
--   WARNING: While the code in this library should be fairly stable
--   and production, the API is something I'm still working on. API changes
--   will follow the PVP, but expect breaking API changes in future
--   versions!
--   
--   A closable, fair, single-wakeup channel that avoids the 0 reader space
--   leak that Control.Concurrent.Chan from base suffers
--   from.
--   
--   The Chan type from Control.Concurrent.Chan
--   consists of both a read and write end combined into a single value.
--   This means there is always at least 1 read end for a Chan,
--   which keeps any values written to it alive. This is a problem for
--   applications/libraries that want to have a channel that can have zero
--   listeners.
--   
--   Suppose we have an library that produces events and we want to let
--   users register to receive events. If we use a channel and write all
--   events to it, we would like to drop and garbage collect any events
--   that take place when there are 0 listeners. The always present read
--   end of Chan from base makes this impossible. We end up with a
--   Chan that forever accumulates more and more events that will
--   never get removed, resulting in a memory leak.
--   
--   BroadcastChan splits channels into separate read and
--   write ends. Any message written to a a channel with no existing read
--   end is immediately dropped so it can be garbage collected. Once a read
--   end is created, all messages written to the channel will be accessible
--   to that read end.
--   
--   Once all read ends for a channel have disappeared and been garbage
--   collected, the channel will return to dropping messages as soon as
--   they are written.
--   
--   Why should I use BroadcastChan over
--   Control.Concurrent.Chan?
--   
--   
--   
- BroadcastChan is closable,
--   
- BroadcastChan has no 0 reader space leak,
--   
- BroadcastChan has comparable or better
--   performance.
--   
--   
--   Why should I use BroadcastChan over various (closable) STM
--   channels?
--   
--   
--   
- BroadcastChan is single-wakeup,
--   
- BroadcastChan is fair,
--   
- BroadcastChan performs better under
--   contention.
--   
@package broadcast-chan
@version 0.2.1.2

-- | Functions in this module are *NOT* intended to be used by regular
--   users of the library. Rather, they are intended for implementing
--   parallel processing libraries on top of broadcast-chan, such
--   as broadcast-chan-conduit.
--   
--   This module, while not for end users, is considered part of the public
--   API, so users can rely on PVP bounds to avoid breakage due to changes
--   to this module.
module BroadcastChan.Extra

-- | Action to take when an exception occurs while processing an element.
data Action

-- | Drop the current element and continue processing.
Drop :: Action

-- | Retry by appending the current element to the queue of remaining
--   elements.
Retry :: Action

-- | Stop all processing and reraise the exception.
Terminate :: Action

-- | Allocation, cleanup, and work actions for parallel processing. These
--   should be passed to an appropriate bracketOnError function.
data BracketOnError (m :: Type -> Type) r
Bracket :: IO [Weak ThreadId] -> ([Weak ThreadId] -> IO ()) -> m r -> BracketOnError (m :: Type -> Type) r

-- | Allocation action that spawn threads and sets up handlers.
[allocate] :: BracketOnError (m :: Type -> Type) r -> IO [Weak ThreadId]

-- | Cleanup action that handles exceptional termination
[cleanup] :: BracketOnError (m :: Type -> Type) r -> [Weak ThreadId] -> IO ()

-- | Action that performs actual processing and waits for processing to
--   finish and threads to terminate.
[action] :: BracketOnError (m :: Type -> Type) r -> m r

-- | Exception handler for parallel processing.
data Handler (m :: Type -> Type) a

-- | Always take the specified Action.
Simple :: Action -> Handler (m :: Type -> Type) a

-- | Allow inspection of the element, exception, and execution of monadic
--   actions before deciding the Action to take.
Handle :: (a -> SomeException -> m Action) -> Handler (m :: Type -> Type) a

-- | Datatype for specifying additional setup/cleanup around forking
--   threads. Used by runParallelWith and runParallelWith_ to
--   fix resource management in broadcast-chan-conduit.
--   
--   If the allocation action can fail/abort with an exception it
--   MUST take care not to leak resources in these cases. In other
--   words, IFF setupFork succeeds then this library will ensure the
--   corresponding cleanup runs.
data ThreadBracket
ThreadBracket :: IO () -> IO () -> IO () -> ThreadBracket

-- | Setup action to run before spawning a new thread.
[setupFork] :: ThreadBracket -> IO ()

-- | Normal cleanup action upon thread termination.
[cleanupFork] :: ThreadBracket -> IO ()

-- | Exceptional cleanup action in case thread terminates due to an
--   exception.
[cleanupForkError] :: ThreadBracket -> IO ()

-- | Convenience function for changing the monad the exception handler runs
--   in.
mapHandler :: (m Action -> n Action) -> Handler m a -> Handler n a

-- | Sets up parallel processing.
--   
--   The workhorses of this function are the output yielder and "stream"
--   processing functions.
--   
--   The output yielder is responsible for handling the produced b
--   values, which if can either yield downstream (Left) when used
--   with something like conduit or pipes, or fold into a
--   single results (Right) when used to run IO in parallel.
--   
--   The stream processing function gets two arguments:
--   
--   
--   
- a -> m () Should be used to buffer a number of
--   elements equal to the number of threads.
--   
- a -> m b Which should be used to process the
--   remainder of the element stream via, for example, mapM.
--   
--   
--   See BroadcastChan or broadcast-chan-conduit for
--   examples.
--   
--   The returned BracketOnError has a allocate action that
--   takes care of setting up forkIO threads and exception handlers.
--   The cleanup action ensures all threads are terminate in case of
--   an exception. Finally, action performs the actual parallel
--   processing of elements.
runParallel :: forall a b m n r. (MonadIO m, MonadIO n) => Either (b -> n r) (r -> b -> n r) -> Handler IO a -> Int -> (a -> IO b) -> ((a -> m ()) -> (a -> m (Maybe b)) -> n r) -> n (BracketOnError n r)

-- | Like runParallel, but accepts a setup and cleanup action that
--   will be run before spawning a new thread and upon thread exit
--   respectively.
--   
--   The main use case is to properly manage the resource reference counts
--   of ResourceT.
--   
--   If the setup throws an IO exception or otherwise aborts, it
--   MUST ensure any allocated resource are freed. If it completes
--   without an exception, the cleanup is guaranteed to run (assuming
--   proper use of bracketing with the returned BracketOnError).
runParallelWith :: forall a b m n r. (MonadIO m, MonadIO n) => ThreadBracket -> Either (b -> n r) (r -> b -> n r) -> Handler IO a -> Int -> (a -> IO b) -> ((a -> m ()) -> (a -> m (Maybe b)) -> n r) -> n (BracketOnError n r)

-- | Sets up parallel processing for functions where we ignore the result.
--   
--   The stream processing argument is the workhorse of this function. It
--   gets a (rate-limited) function a -> m () that queues
--   a values for processing. This function should be applied to
--   all a elements that should be processed. This would be either
--   a partially applied forM_ for parallel processing, or something
--   like conduit's mapM_ to construct a "sink" for a
--   values. See BroadcastChan or broadcast-chan-conduit
--   for examples.
--   
--   The returned BracketOnError has a allocate action that
--   takes care of setting up forkIO threads and exception handlers.
--   Th cleanup action ensures all threads are terminate in case of
--   an exception. Finally, action performs the actual parallel
--   processing of elements.
runParallel_ :: (MonadIO m, MonadIO n) => Handler IO a -> Int -> (a -> IO ()) -> ((a -> m ()) -> n r) -> n (BracketOnError n r)

-- | Like runParallel_, but accepts a setup and cleanup action that
--   will be run before spawning a new thread and upon thread exit
--   respectively.
--   
--   The main use case is to properly manage the resource reference counts
--   of ResourceT.
--   
--   If the setup throws an IO exception or otherwise aborts, it
--   MUST ensure any allocated resource are freed. If it completes
--   without an exception, the cleanup is guaranteed to run (assuming
--   proper use of bracketing with the returned BracketOnError).
runParallelWith_ :: (MonadIO m, MonadIO n) => ThreadBracket -> Handler IO a -> Int -> (a -> IO ()) -> ((a -> m ()) -> n r) -> n (BracketOnError n r)
instance GHC.Classes.Eq BroadcastChan.Extra.Action
instance GHC.Internal.Exception.Type.Exception BroadcastChan.Extra.Shutdown
instance GHC.Internal.Show.Show BroadcastChan.Extra.Action
instance GHC.Internal.Show.Show BroadcastChan.Extra.Shutdown

-- | A closable, fair, single-wakeup channel that avoids the 0 reader space
--   leak that Control.Concurrent.Chan from base suffers
--   from.
--   
--   The Chan type from Control.Concurrent.Chan
--   consists of both a read and write end combined into a single value.
--   This means there is always at least 1 read end for a Chan,
--   which keeps any values written to it alive. This is a problem for
--   applications/libraries that want to have a channel that can have zero
--   listeners.
--   
--   Suppose we have an library that produces events and we want to let
--   users register to receive events. If we use a channel and write all
--   events to it, we would like to drop and garbage collect any events
--   that take place when there are 0 listeners. The always present read
--   end of Chan from base makes this impossible. We end up with a
--   Chan that forever accumulates more and more events that will
--   never get removed, resulting in a memory leak.
--   
--   BroadcastChan splits channels into separate read and
--   write ends. Any message written to a a channel with no existing read
--   end is immediately dropped so it can be garbage collected. Once a read
--   end is created, all messages written to the channel will be accessible
--   to that read end.
--   
--   Once all read ends for a channel have disappeared and been garbage
--   collected, the channel will return to dropping messages as soon as
--   they are written.
--   
--   Why should I use BroadcastChan over
--   Control.Concurrent.Chan?
--   
--   
--   
- BroadcastChan is closable,
--   
- BroadcastChan has no 0 reader space leak,
--   
- BroadcastChan has comparable or better
--   performance.
--   
--   
--   Why should I use BroadcastChan over various (closable) STM
--   channels?
--   
--   
--   
- BroadcastChan is single-wakeup,
--   
- BroadcastChan is fair,
--   
- BroadcastChan performs better under
--   contention.
--   
module BroadcastChan

-- | The abstract type representing the read or write end of a
--   BroadcastChan.
data BroadcastChan (dir :: Direction) a

-- | Used with DataKinds as phantom type indicating whether a
--   BroadcastChan value is a read or write end.
data Direction

-- | Indicates a write BroadcastChan
In :: Direction

-- | Indicates a read BroadcastChan
Out :: Direction

-- | Alias for the In type from the Direction kind, allows
--   users to write the BroadcastChan In a type
--   without enabling DataKinds.
type In = 'In

-- | Alias for the Out type from the Direction kind, allows
--   users to write the BroadcastChan Out a type
--   without enabling DataKinds.
type Out = 'Out

-- | Creates a new BroadcastChan write end.
newBroadcastChan :: MonadIO m => m (BroadcastChan In a)

-- | Create a new read end for a BroadcastChan.
--   
--   
--   
- BroadcastChan In: Will receive all messages
--   written to the channel after this read end is created.
--   
- BroadcastChan Out: Will receive all currently
--   unread messages and all future messages.
--   
newBChanListener :: forall m (dir :: Direction) a. MonadIO m => BroadcastChan dir a -> m (BroadcastChan Out a)

-- | Read the next value from the read end of a BroadcastChan.
--   Returns Nothing if the BroadcastChan is closed and
--   empty. See BroadcastChan.Throw.readBChan for an
--   exception throwing variant.
readBChan :: MonadIO m => BroadcastChan Out a -> m (Maybe a)

-- | Write a value to write end of a BroadcastChan. Any messages
--   written while there are no live read ends are dropped on the floor and
--   can be immediately garbage collected, thus avoiding space leaks.
--   
--   The return value indicates whether the write succeeded, i.e.,
--   True if the message was written, False is the channel is
--   closed. See BroadcastChan.Throw.writeBChan for an
--   exception throwing variant.
writeBChan :: MonadIO m => BroadcastChan In a -> a -> m Bool

-- | Close a BroadcastChan, disallowing further writes. Returns
--   True if the BroadcastChan was closed. Returns
--   False if the BroadcastChan was already closed.
closeBChan :: MonadIO m => BroadcastChan In a -> m Bool

-- | Check whether a BroadcastChan is closed. True meaning
--   that future read/write operations on the channel will always fail.
--   
--   
--   
- BroadcastChan In: True indicates the
--   channel is closed and writes will always fail.Beware of TOC-TOU
--   races: It is possible for a BroadcastChan to be closed by
--   another thread. If multiple threads use the same channel a
--   closeBChan from another thread can result in the channel being
--   closed right after isClosedBChan returns.
--   
- BroadcastChan Out: True indicates
--   the channel is both closed and empty, meaning reads will always
--   fail.
--   
isClosedBChan :: forall m (dir :: Direction) a. MonadIO m => BroadcastChan dir a -> m Bool

-- | Return a lazy list representing the messages written to the channel.
--   
--   Uses unsafeInterleaveIO to defer the IO operations.
--   
--   
--   
- BroadcastChan In: The list contains every
--   message written to the channel after this IO action
--   completes.
--   
- BroadcastChan Out: The list contains every
--   currently unread message and all future messages. It's safe to keep
--   using the original channel in any thread.Unlike getChanContents
--   from Control.Concurrent, the list resulting from this function
--   is not affected by reads on the input channel. Every message
--   that is unread or written after the IO action completes
--   will end up in the result list.
--   
getBChanContents :: forall (dir :: Direction) a. BroadcastChan dir a -> IO [a]

-- | Action to take when an exception occurs while processing an element.
data Action

-- | Drop the current element and continue processing.
Drop :: Action

-- | Retry by appending the current element to the queue of remaining
--   elements.
Retry :: Action

-- | Stop all processing and reraise the exception.
Terminate :: Action

-- | Exception handler for parallel processing.
data Handler (m :: Type -> Type) a

-- | Always take the specified Action.
Simple :: Action -> Handler (m :: Type -> Type) a

-- | Allow inspection of the element, exception, and execution of monadic
--   actions before deciding the Action to take.
Handle :: (a -> SomeException -> m Action) -> Handler (m :: Type -> Type) a

-- | Map a monadic function over a Foldable, processing elements in
--   parallel.
--   
--   This function does NOT guarantee that elements are processed in
--   a deterministic order!
parMapM_ :: (Foldable f, MonadUnliftIO m) => Handler m a -> Int -> (a -> m ()) -> f a -> m ()

-- | Like parMapM_, but folds the individual results into single
--   result value.
--   
--   This function does NOT guarantee that elements are processed in
--   a deterministic order!
parFoldMap :: (Foldable f, MonadUnliftIO m) => Handler m a -> Int -> (a -> m b) -> (r -> b -> r) -> r -> f a -> m r

-- | Like parFoldMap, but uses a monadic fold function.
--   
--   This function does NOT guarantee that elements are processed in
--   a deterministic order!
parFoldMapM :: forall a b f m r. (Foldable f, MonadUnliftIO m) => Handler m a -> Int -> (a -> m b) -> (r -> b -> m r) -> r -> f a -> m r

-- | Strict fold of the BroadcastChan​'s messages. Can be used with
--   Control.Foldl from Tekmo's foldl package:
--   
--   
--   Control.Foldl.purely foldBChan :: (MonadIO m, MonadIO n) => Fold a b -> BroadcastChan d a -> n (m b)
--   
--   
--   The result of this function is a nested monadic value to give more
--   fine-grained control/separation between the start of listening for
--   messages and the start of processing. The inner action folds the
--   actual messages and completes when the channel is closed and
--   exhausted. The outer action controls from when on messages are
--   received. Specifically:
--   
--   
--   
- BroadcastChan In: Will process all messages
--   sent after the outer action completes.
--   
- BroadcastChan Out: Will process all messages
--   that are unread when the outer action completes, as well as all future
--   messages.After the outer action completes the fold is unaffected by
--   other (concurrent) reads performed on the original channel. So it's
--   safe to reuse the channel.
--   
foldBChan :: forall m n x a b (d :: Direction). (MonadIO m, MonadIO n) => (x -> a -> x) -> x -> (x -> b) -> BroadcastChan d a -> n (m b)

-- | Strict, monadic fold of the BroadcastChan​'s messages. Can be
--   used with Control.Foldl from Tekmo's foldl package:
--   
--   
--   Control.Foldl.impurely foldBChanM :: (MonadIO m, MonadIO n) => FoldM m a b -> BroadcastChan d a -> n (m b)
--   
--   
--   Has the same behaviour and guarantees as foldBChan.
foldBChanM :: forall m n x a b (d :: Direction). (MonadIO m, MonadIO n) => (x -> a -> m x) -> m x -> (x -> m b) -> BroadcastChan d a -> n (m b)

-- | This module contains convenience functions that clash with names in
--   Prelude and is intended to be imported qualified.
module BroadcastChan.Prelude

-- | mapM_ with it's arguments flipped.
forM_ :: MonadIO m => BroadcastChan Out a -> (a -> m b) -> m ()

-- | Map a monadic function over the elements of a BroadcastChan,
--   ignoring the results.
mapM_ :: MonadIO m => (a -> m b) -> BroadcastChan Out a -> m ()

-- | This module is identical to BroadcastChan, but with
--   BroadcastChan.writeBChan and
--   BroadcastChan.readBChan replaced with versions that
--   throw an exception, rather than returning results that the user has to
--   inspect to check for success.
module BroadcastChan.Throw

-- | Exception type for BroadcastChan operations.
data BChanError

-- | Attempted to write to closed BroadcastChan
WriteFailed :: BChanError

-- | Attempted to read from an empty closed BroadcastChan
ReadFailed :: BChanError

-- | Like readBChan, but throws a ReadFailed exception when
--   reading from a closed and empty BroadcastChan.
readBChan :: BroadcastChan Out a -> IO a

-- | Like writeBChan, but throws a WriteFailed exception when
--   writing to closed BroadcastChan.
writeBChan :: BroadcastChan In a -> a -> IO ()

-- | The abstract type representing the read or write end of a
--   BroadcastChan.
data BroadcastChan (dir :: Direction) a

-- | Used with DataKinds as phantom type indicating whether a
--   BroadcastChan value is a read or write end.
data Direction

-- | Indicates a write BroadcastChan
In :: Direction

-- | Indicates a read BroadcastChan
Out :: Direction

-- | Alias for the In type from the Direction kind, allows
--   users to write the BroadcastChan In a type
--   without enabling DataKinds.
type In = 'In

-- | Alias for the Out type from the Direction kind, allows
--   users to write the BroadcastChan Out a type
--   without enabling DataKinds.
type Out = 'Out

-- | Creates a new BroadcastChan write end.
newBroadcastChan :: MonadIO m => m (BroadcastChan In a)

-- | Create a new read end for a BroadcastChan.
--   
--   
--   
- BroadcastChan In: Will receive all messages
--   written to the channel after this read end is created.
--   
- BroadcastChan Out: Will receive all currently
--   unread messages and all future messages.
--   
newBChanListener :: forall m (dir :: Direction) a. MonadIO m => BroadcastChan dir a -> m (BroadcastChan Out a)

-- | Close a BroadcastChan, disallowing further writes. Returns
--   True if the BroadcastChan was closed. Returns
--   False if the BroadcastChan was already closed.
closeBChan :: MonadIO m => BroadcastChan In a -> m Bool

-- | Check whether a BroadcastChan is closed. True meaning
--   that future read/write operations on the channel will always fail.
--   
--   
--   
- BroadcastChan In: True indicates the
--   channel is closed and writes will always fail.Beware of TOC-TOU
--   races: It is possible for a BroadcastChan to be closed by
--   another thread. If multiple threads use the same channel a
--   closeBChan from another thread can result in the channel being
--   closed right after isClosedBChan returns.
--   
- BroadcastChan Out: True indicates
--   the channel is both closed and empty, meaning reads will always
--   fail.
--   
isClosedBChan :: forall m (dir :: Direction) a. MonadIO m => BroadcastChan dir a -> m Bool

-- | Return a lazy list representing the messages written to the channel.
--   
--   Uses unsafeInterleaveIO to defer the IO operations.
--   
--   
--   
- BroadcastChan In: The list contains every
--   message written to the channel after this IO action
--   completes.
--   
- BroadcastChan Out: The list contains every
--   currently unread message and all future messages. It's safe to keep
--   using the original channel in any thread.Unlike getChanContents
--   from Control.Concurrent, the list resulting from this function
--   is not affected by reads on the input channel. Every message
--   that is unread or written after the IO action completes
--   will end up in the result list.
--   
getBChanContents :: forall (dir :: Direction) a. BroadcastChan dir a -> IO [a]

-- | Action to take when an exception occurs while processing an element.
data Action

-- | Drop the current element and continue processing.
Drop :: Action

-- | Retry by appending the current element to the queue of remaining
--   elements.
Retry :: Action

-- | Stop all processing and reraise the exception.
Terminate :: Action

-- | Exception handler for parallel processing.
data Handler (m :: Type -> Type) a

-- | Always take the specified Action.
Simple :: Action -> Handler (m :: Type -> Type) a

-- | Allow inspection of the element, exception, and execution of monadic
--   actions before deciding the Action to take.
Handle :: (a -> SomeException -> m Action) -> Handler (m :: Type -> Type) a

-- | Map a monadic function over a Foldable, processing elements in
--   parallel.
--   
--   This function does NOT guarantee that elements are processed in
--   a deterministic order!
parMapM_ :: (Foldable f, MonadUnliftIO m) => Handler m a -> Int -> (a -> m ()) -> f a -> m ()

-- | Like parMapM_, but folds the individual results into single
--   result value.
--   
--   This function does NOT guarantee that elements are processed in
--   a deterministic order!
parFoldMap :: (Foldable f, MonadUnliftIO m) => Handler m a -> Int -> (a -> m b) -> (r -> b -> r) -> r -> f a -> m r

-- | Like parFoldMap, but uses a monadic fold function.
--   
--   This function does NOT guarantee that elements are processed in
--   a deterministic order!
parFoldMapM :: forall a b f m r. (Foldable f, MonadUnliftIO m) => Handler m a -> Int -> (a -> m b) -> (r -> b -> m r) -> r -> f a -> m r

-- | Strict fold of the BroadcastChan​'s messages. Can be used with
--   Control.Foldl from Tekmo's foldl package:
--   
--   
--   Control.Foldl.purely foldBChan :: (MonadIO m, MonadIO n) => Fold a b -> BroadcastChan d a -> n (m b)
--   
--   
--   The result of this function is a nested monadic value to give more
--   fine-grained control/separation between the start of listening for
--   messages and the start of processing. The inner action folds the
--   actual messages and completes when the channel is closed and
--   exhausted. The outer action controls from when on messages are
--   received. Specifically:
--   
--   
--   
- BroadcastChan In: Will process all messages
--   sent after the outer action completes.
--   
- BroadcastChan Out: Will process all messages
--   that are unread when the outer action completes, as well as all future
--   messages.After the outer action completes the fold is unaffected by
--   other (concurrent) reads performed on the original channel. So it's
--   safe to reuse the channel.
--   
foldBChan :: forall m n x a b (d :: Direction). (MonadIO m, MonadIO n) => (x -> a -> x) -> x -> (x -> b) -> BroadcastChan d a -> n (m b)

-- | Strict, monadic fold of the BroadcastChan​'s messages. Can be
--   used with Control.Foldl from Tekmo's foldl package:
--   
--   
--   Control.Foldl.impurely foldBChanM :: (MonadIO m, MonadIO n) => FoldM m a b -> BroadcastChan d a -> n (m b)
--   
--   
--   Has the same behaviour and guarantees as foldBChan.
foldBChanM :: forall m n x a b (d :: Direction). (MonadIO m, MonadIO n) => (x -> a -> m x) -> m x -> (x -> m b) -> BroadcastChan d a -> n (m b)
instance GHC.Classes.Eq BroadcastChan.Throw.BChanError
instance GHC.Internal.Exception.Type.Exception BroadcastChan.Throw.BChanError
instance GHC.Internal.Read.Read BroadcastChan.Throw.BChanError
instance GHC.Internal.Show.Show BroadcastChan.Throw.BChanError
