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


-- | Introduces conduits to channels, and promotes using conduits concurrently.
--   
--   Provides two simple conduit wrappers around STM channels - a source
--   and a sink.
@package stm-conduit
@version 4.0.0


-- | <ul>
--   <li>Introduction</li>
--   </ul>
--   
--   Contain combinators for concurrently joining conduits, such that the
--   producing side may continue to produce (up to the queue size) as the
--   consumer is concurrently consuming.
module Data.Conduit.Async

-- | A "concurrent conduit", in which the stages run in parallel with a
--   buffering queue between them.
data CConduit i o m r

-- | A "concurrent conduit", in which the stages run in parallel with a
--   buffering queue and possibly a disk file between them.
data CFConduit i o m r

-- | An alias for <a>=$=&amp;</a> by analogy with <a>=$=</a> and <a>$=</a>.
($=&) :: (CCatable c1 c2 c3) => c1 i x m () -> c2 x o m r -> c3 i o m r
infixl 1 $=&

-- | An alias for <a>=$=&amp;</a> by analogy with <a>=$=</a> and <a>=$</a>.
(=$&) :: (CCatable c1 c2 c3) => c1 i x m () -> c2 x o m r -> c3 i o m r
infixr 2 =$&

-- | An operator form of <a>buffer'</a>. In general you should be able to
--   replace any use of <a>=$=</a> with <a>=$=&amp;</a> and <a>$$</a>
--   either with <a>$$&amp;</a> or <a>=$=</a> and <a>runCConduit</a> and
--   suddenly reap the benefit of concurrency, if your conduits were
--   spending time waiting on each other.
--   
--   <pre>
--   &gt;&gt;&gt; runCConduit $ CL.sourceList [1,2,3] =$=&amp; CL.consume
--   [1,2,3]
--   </pre>
(=$=&) :: (CCatable c1 c2 c3) => c1 i x m () -> c2 x o m r -> c3 i o m r
infixr 2 =$=&

-- | An operator form of <a>buffer</a>. In general you should be able to
--   replace any use of <a>$$</a> with <a>$$&amp;</a> and suddenly reap the
--   benefit of concurrency, if your conduits were spending time waiting on
--   each other.
--   
--   The underlying monad must always be an instance of 'MonadBaseControl
--   IO'. If at least one of the two conduits is a <a>CFConduit</a>, it
--   must additionally be a in instance of <a>MonadResource</a>.
--   
--   <pre>
--   &gt;&gt;&gt; CL.sourceList [1,2,3] $$&amp; CL.consume
--   [1,2,3]
--   </pre>
--   
--   It can be combined with <a>$=&amp;</a> and <a>$=</a>. This creates two
--   threads; the first thread produces the list and the second thread does
--   the map and the consume:
--   
--   <pre>
--   &gt;&gt;&gt; CL.sourceList [1,2,3] $$&amp; mapC (*2) $= CL.consume
--   [2,4,6]
--   </pre>
--   
--   This creates three threads. The three conduits all run in their own
--   threads:
--   
--   <pre>
--   &gt;&gt;&gt; CL.sourceList [1,2,3] $$&amp; mapC (*2) $=&amp; CL.consume
--   [2,4,6]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; CL.sourceList [1,2,3] $$&amp; (mapC (*2) $= mapC (+1)) $=&amp; CL.consume
--   [3,5,7]
--   </pre>
($$&) :: (CCatable c1 c2 c3, CRunnable c3, RunConstraints c3 m) => c1 () x m () -> c2 x Void m r -> m r
infixr 0 $$&

-- | Concurrently join the producer and consumer, using a bounded queue of
--   the given size. The producer will block when the queue is full, if it
--   is producing faster than the consumers is taking from it. Likewise, if
--   the consumer races ahead, it will block until more input is available.
--   
--   Exceptions are properly managed and propagated between the two sides,
--   so the net effect should be equivalent to not using buffer at all,
--   save for the concurrent interleaving of effects.
--   
--   The underlying monad must always be an instance of 'MonadBaseControl
--   IO'. If at least one of the two conduits is a <a>CFConduit</a>, it
--   must additionally be a in instance of <a>MonadResource</a>.
--   
--   This function is similar to <a>$$</a>; for one more like <a>=$=</a>,
--   see <a>buffer'</a>.
--   
--   <pre>
--   &gt;&gt;&gt; buffer 1 (CL.sourceList [1,2,3]) CL.consume
--   [1,2,3]
--   </pre>
buffer :: (CCatable c1 c2 c3, CRunnable c3, RunConstraints c3 m) => Int -> c1 () x m () -> c2 x Void m r -> m r

-- | Concurrently join the producer and consumer, using a bounded queue of
--   the given size. The producer will block when the queue is full, if it
--   is producing faster than the consumers is taking from it. Likewise, if
--   the consumer races ahead, it will block until more input is available.
--   
--   Exceptions are properly managed and propagated between the two sides,
--   so the net effect should be equivalent to not using buffer at all,
--   save for the concurrent interleaving of effects.
--   
--   This function is similar to <a>=$=</a>; for one more like <a>$$</a>,
--   see <a>buffer</a>.
--   
--   <pre>
--   &gt;&gt;&gt; runCConduit $ buffer' 1 (CL.sourceList [1,2,3]) CL.consume
--   [1,2,3]
--   </pre>
buffer' :: CCatable c1 c2 c3 => Int -> c1 i x m () -> c2 x o m r -> c3 i o m r

-- | Like <a>buffer</a>, except that when the bounded queue is overflowed,
--   the excess is cached in a local file so that consumption from upstream
--   may continue. When the queue becomes exhausted by yielding, it is
--   filled from the cache until all elements have been yielded.
--   
--   Note that the maximum amount of memory consumed is equal to (2 *
--   memorySize + 1), so take this into account when picking a chunking
--   size.
--   
--   This function is similar to <a>$$</a>; for one more like <a>=$=</a>,
--   see <a>bufferToFile'</a>.
--   
--   <pre>
--   &gt;&gt;&gt; runResourceT $ bufferToFile 1 Nothing "/tmp" (CL.sourceList [1,2,3]) CL.consume
--   [1,2,3]
--   </pre>
bufferToFile :: (CFConduitLike c1, CFConduitLike c2, Serialize x, MonadUnliftIO m, MonadResource m, MonadThrow m) => Int -> Maybe Int -> FilePath -> c1 () x m () -> c2 x Void m r -> m r

-- | Like <a>buffer'</a>, except that when the bounded queue is overflowed,
--   the excess is cached in a local file so that consumption from upstream
--   may continue. When the queue becomes exhausted by yielding, it is
--   filled from the cache until all elements have been yielded.
--   
--   Note that the maximum amount of memory consumed is equal to (2 *
--   memorySize + 1), so take this into account when picking a chunking
--   size.
--   
--   This function is similar to <a>=$=</a>; for one more like <a>$$</a>,
--   see <a>bufferToFile</a>.
--   
--   <pre>
--   &gt;&gt;&gt; runResourceT $ runCConduit $ bufferToFile' 1 Nothing "/tmp" (CL.sourceList [1,2,3]) CL.consume
--   [1,2,3]
--   </pre>
--   
--   It is frequently convenient to define local function to use this in
--   operator form:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   runResourceT $ do
--     let buf c = bufferToFile' 10 Nothing "/tmp" c -- eta-conversion to avoid monomorphism restriction
--     runCConduit $ CL.sourceList [0x30, 0x31, 0x32] `buf` mapC (toEnum :: Int -&gt; Char) `buf` CL.consume
--   :}
--   "012"
--   </pre>
bufferToFile' :: (CFConduitLike c1, CFConduitLike c2, Serialize x) => Int -> Maybe Int -> FilePath -> c1 i x m () -> c2 x o m r -> CFConduit i o m r

-- | Execute a conduit concurrently. This is the concurrent equivalent of
--   <a>runConduit</a>.
--   
--   The underlying monad must always be an instance of
--   <a>MonadUnliftIO</a>. If the conduits is a <a>CFConduit</a>, it must
--   additionally be a in instance of <a>MonadResource</a>.
runCConduit :: (CRunnable c, (RunConstraints c m)) => c () Void m r -> m r

-- | Gather output values asynchronously from an action in the base monad
--   and then yield them downstream. This provides a means of working
--   around the restriction that <a>ConduitM</a> cannot be an instance of
--   <tt>MonadBaseControl</tt> in order to, for example, yield values from
--   within a Haskell callback function called from a C library.
gatherFrom :: (MonadIO m, MonadUnliftIO m) => Int -> (TBQueue o -> m ()) -> ConduitT () o m ()

-- | Drain input values into an asynchronous action in the base monad via a
--   bounded <a>TBQueue</a>. This is effectively the dual of
--   <a>gatherFrom</a>.
drainTo :: (MonadIO m, MonadUnliftIO m) => Int -> (TBQueue (Maybe i) -> m r) -> ConduitT i Void m r


-- | <ul>
--   <li>Introduction</li>
--   </ul>
--   
--   Contains a simple source and sink for linking together conduits in in
--   different threads. Usage is so easy, it's best explained with an
--   example:
--   
--   We first create a channel for communication...
--   
--   <pre>
--   do chan &lt;- atomically $ newTBMChan 16
--   </pre>
--   
--   Then we fork a new thread loading a wackton of pictures into memory.
--   The data (pictures, in this case) will be streamed down the channel to
--   whatever is on the other side.
--   
--   <pre>
--   _ &lt;- forkIO . runResourceT $ do
--         _ &lt;- register $ atomically $ closeTBMChan chan
--         loadTextures lotsOfPictures $$ sinkTBMChan chan
--   </pre>
--   
--   We register closing function explicitly, because starting with version
--   <tt>1.3.0</tt> <tt>conduits</tt> library no longer maintain resources,
--   so this is the only way to safely close channel in case of exceptions.
--   
--   Finally, we connect something to the other end of the channel. In this
--   case, we connect a sink which uploads the textures one by one to the
--   graphics card.
--   
--   <pre>
--   runResourceT $ sourceTBMChan chan $$ Conduit.mapM_ (liftIO . uploadToGraphicsCard)
--   </pre>
--   
--   By running the two tasks in parallel, we no longer have to wait for
--   one texture to upload to the graphics card before reading the next one
--   from disk. This avoids the common switching of bottlenecks (such as
--   between the disk and graphics memory) that most loading processes seem
--   to love.
--   
--   Control.Concurrent.STM.TMChan and Control.Concurrent.STM.TBMChan are
--   re-exported for convenience.
--   
--   <ul>
--   <li>Caveats</li>
--   </ul>
--   
--   It is recommended to use TBMChan as much as possible, and generally
--   avoid TMChan usage. TMChans are unbounded, and if used, the conduit
--   pipeline will no longer use a bounded amount of space. They will
--   essentially leak memory if the writer is faster than the reader.
--   
--   Therefore, use bounded channels as much as possible, preferably with a
--   high bound so it will be hit infrequently.
module Data.Conduit.TMChan

-- | A simple wrapper around a TBMChan. As data is pushed into the channel,
--   the source will read it and pass it down the conduit pipeline. When
--   the channel is closed, the source will close also.
--   
--   If the channel fills up, the pipeline will stall until values are
--   read.
sourceTBMChan :: MonadIO m => TBMChan a -> ConduitT () a m ()

-- | A simple wrapper around a TBMChan. As data is pushed into the sink, it
--   will magically begin to appear in the channel. If the channel is full,
--   the sink will block until space frees up.
sinkTBMChan :: MonadIO m => TBMChan a -> ConduitT a z m ()

-- | A simple wrapper around a TMChan. As data is pushed into the channel,
--   the source will read it and pass it down the conduit pipeline. When
--   the channel is closed, the source will close also.
sourceTMChan :: MonadIO m => TMChan a -> ConduitT () a m ()

-- | A simple wrapper around a TMChan. As data is pushed into this sink, it
--   will magically begin to appear in the channel.
sinkTMChan :: MonadIO m => TMChan a -> ConduitT a z m ()

-- | Combines two sources with an unbounded channel, creating a new source
--   which pulls data from a mix of the two sources: whichever produces
--   first.
--   
--   The order of the new source's data is undefined, but it will be some
--   combination of the two given sources.
(>=<) :: (MonadResource mi, MonadIO mo, MonadUnliftIO mi) => ConduitT () a mi () -> ConduitT () a mi () -> mo (ConduitT () a mi ())
infixl 5 >=<

-- | Merges a list of sources, putting them all into a bounded channel, and
--   returns a source which can be pulled from to pull from all the given
--   sources in a first-come-first-serve basis.
--   
--   The order of the new source's data is undefined, but it will be some
--   combination of the given sources. The monad of the resultant source
--   (<tt>mo</tt>) is independent of the monads of the input sources
--   (<tt>mi</tt>).
--   
--   All spawned threads will be removed when source is closed or upon an
--   exit from <a>ResourceT</a> region. This means that result can only be
--   used within a <a>runResourceT</a> scope.
--   
--   @before 3.0 Spawned threads are not guaranteed to be closed. This may
--   happen if Source was closed before all it's input were closed.
mergeSources :: (MonadResource mi, MonadIO mo, MonadUnliftIO mi) => [ConduitT () a mi ()] -> Int -> mo (ConduitT () a mi ())

-- | Combines two conduits with unbounded channels, creating a new conduit
--   which pulls data from a mix of the two: whichever produces first.
--   
--   The order of the new conduit's output is undefined, but it will be
--   some combination of the two given conduits.
(<=>) :: (MonadThrow mi, MonadIO mo, MonadUnliftIO mi) => ConduitT i i (ResourceT mi) () -> ConduitT i i (ResourceT mi) () -> ResourceT mi (ConduitT i i mo ())

-- | Provide an input across several conduits, putting them all into a
--   bounded channel. Returns a conduit which can be pulled from to pull
--   from all the given conduits in a first-come-first-serve basis.
--   
--   The order of the new conduits's outputs is undefined, but it will be
--   some combination of the given conduits. The monad of the resultant
--   conduit (<tt>mo</tt>) is independent of the monads of the input
--   conduits (<tt>mi</tt>).
--   
--   Closes all worker processes when resulting conduit is closed or when
--   execution leaves ResourceT context. This means that conduit is only
--   valid inside <tt>runResouceT</tt> scope.
--   
--   @before 3.0 Spawned threads are not guaranteed to be closed, This may
--   happen if threads Conduit was closed before all threads have finished
--   execution.

-- | <i>Deprecated: This method will dissapear in the next version.</i>
mergeConduits :: (MonadIO mo, MonadUnliftIO mi) => [ConduitT i o (ResourceT mi) ()] -> Int -> ResourceT mi (ConduitT i o mo ())


-- | Contains a simple source and sink linking together conduits in
--   different threads. For extended examples of usage and bottlenecks see
--   <a>TMChan</a>.
--   
--   TQueue is an amoritized FIFO queue behaves like TChan, with two
--   important differences:
--   
--   <ul>
--   <li>it's faster (but amortized thus the cost of individual operations
--   may vary a lot)</li>
--   <li>it doesn't provide equivalent of the dupTChan and cloneTChan
--   operations</li>
--   </ul>
--   
--   Here is short description of data structures:
--   
--   <ul>
--   <li>TQueue - unbounded infinite queue</li>
--   <li>TBQueue - bounded infinite queue</li>
--   <li>TMQueue - unbounded finite (closable) queue</li>
--   <li>TBMQueue - bounded finite (closable) queue</li>
--   </ul>
--   
--   Caveats
--   
--   Infinite operations means that source doesn't know when stream is
--   ended so one need to use other methods of finishing stream like
--   sending an exception or finish conduit in downstream.
module Data.Conduit.TQueue

-- | A simple wrapper around a <a>TQueue</a>. As data is pushed into the
--   queue, the source will read it and pass it down the conduit pipeline.
sourceTQueue :: MonadIO m => TQueue a -> ConduitT z a m ()

-- | A simple wrapper around a <a>TQueue</a>. As data is pushed into this
--   sink, it will magically begin to appear in the queue.
sinkTQueue :: MonadIO m => TQueue a -> ConduitT a z m ()

-- | A simple wrapper around a <a>TBQueue</a>. As data is pushed into the
--   queue, the source will read it and pass it down the conduit pipeline.
sourceTBQueue :: MonadIO m => TBQueue a -> ConduitT z a m ()

-- | A simple wrapper around a <a>TBQueue</a>. As data is pushed into this
--   sink, it will magically begin to appear in the queue.
sinkTBQueue :: MonadIO m => TBQueue a -> ConduitT a z m ()

-- | A convenience wrapper for creating a source and sink TBQueue of the
--   given size at once, without exposing the underlying queue.
--   
--   Returns release key that can be used for premature close of the
--   communication channel, otherwise channel will be closed when the
--   ResourceT scope will be closed.
entangledPair :: MonadIO m => Int -> m (ConduitT z a m (), ConduitT a l m ())

-- | A simple wrapper around a <a>TMQueue</a>. As data is pushed into the
--   queue, the source will read it and pass it down the conduit pipeline.
--   When the queue is closed, the source will close also.
sourceTMQueue :: MonadIO m => TMQueue a -> ConduitT z a m ()

-- | A simple wrapper around a <a>TMQueue</a>. As data is pushed into this
--   sink, it will magically begin to appear in the queue.
sinkTMQueue :: MonadIO m => TMQueue a -> ConduitT a z m ()

-- | A simple wrapper around a <a>TBMQueue</a>. As data is pushed into the
--   queue, the source will read it and pass it down the conduit pipeline.
--   When the queue is closed, the source will close also.
sourceTBMQueue :: MonadIO m => TBMQueue a -> ConduitT z a m ()

-- | A simple wrapper around a <a>TBMQueue</a>. As data is pushed into this
--   sink, it will magically begin to appear in the queue.
sinkTBMQueue :: MonadIO m => TBMQueue a -> ConduitT a z m ()


-- | This module provide different utility functions that allow to use safe
--   higher level usage.
--   
--   Conduit pairs allow creation of an internal datastructure that acts as
--   a bridge, and provides input and output conduits. The structure itself
--   is hidden internally and can't be used directly, this provide an
--   additional safeness.
--   
--   In order to create a bridge from your own datastructures you need to
--   do the following:
--   
--   <ul>
--   <li>Make it an instance of <a>UnboundedStream</a> or
--   <a>BoundedStream</a> depending on it's properties:</li>
--   </ul>
--   
--   <pre>
--   instance BoundedStream (Proxy2 TBMQueue) TBMQueue where
--    mkBStream _ i = atomically $ newTBMQueue i
--   </pre>
--   
--   <ul>
--   <li>Add <a>IsConduit</a> instance.</li>
--   </ul>
--   
--   <pre>
--   instance MonadIO m =&gt; IsConduit m TBMQueue where
--     mkSource = sourceTBMQueue
--     mkSink   = flip sinkTBMQueue True
--   </pre>
--   
--   <ul>
--   <li>Use "pair" or "pairBounded" to create a bridge. Because bridge
--   data structure is hidden and not seen in parameters, we need proxy
--   type to help compiler to choose type, we use <a>Proxy2</a> for
--   that.</li>
--   </ul>
--   
--   <pre>
--   pairTBMQueue = pairBounded (proxy2 :: Proxy2 TBMQueue a)
--   </pre>
--   
--   <ul>
--   <li>Now we can create a pair of conduits:</li>
--   </ul>
--   
--   <pre>
--   (src, snk) &lt;- pairTBMQueue 32
--   Control.Concurrent.Async.concurrently (sender src) (receviver snk)
--   </pre>
--   
--   As channel is not visible we can close it or send additional messages
--   bypassing conduit code.
--   
--   This package provides predefined pairs for all STM types that are used
--   in the package.
module Data.Conduit.Utils

-- | Create bounded conduit pair, see <a>BoundedStream</a> class
--   description.
pairBounded :: (MonadIO m, IsConduit m o, BoundedStream i o) => i a -> Int -> m (ConduitT () a m (), ConduitT a Void m ())

-- | Create unbounded pair, see <a>UnboundedStream</a> class description.
pair :: (MonadIO m, IsConduit m o, UnboundedStream i o) => i a -> m (ConduitT () a m (), ConduitT a Void m ())

-- | Class for structures that can handle unbounded stream of values. Such
--   streams break conduit assumptions that constant memory will be used,
--   because if receiver is slower then sender than values will be
--   accumulated.
class UnboundedStream i o | i -> o
mkUStream :: UnboundedStream i o => i a -> IO (o a)

-- | Class for structures that can handle bounded stream of values i.e.
--   there is exists <a>Int</a> value that sets an upper limit on the
--   number of values that can be handled by structure. Exact meaning of
--   this limit may depend on the carrier type.
class BoundedStream i o | i -> o
mkBStream :: BoundedStream i o => i a -> Int -> IO (o a)

-- | Class that describes how we can make conduit out of the carrier value.
class MonadIO m => IsConduit m (x :: * -> *)
mkSink :: IsConduit m x => x a -> ConduitT a Void m ()
mkSource :: IsConduit m x => x a -> ConduitT () a m ()

-- | Proxy type that can be used to create opaque values.
--   
--   This proxy type is required because pair hides internal data structure
--   and proxy is used to help compiler infer internal type.
data Proxy2 (a :: * -> *) b

-- | Construct <a>Proxy2</a> value.
--   
--   <pre>
--   (proxy2 :: Proxy2 TChan a)
--   </pre>
proxy2 :: Proxy2 a b
pairTQueue :: MonadIO m => m (ConduitT () a m (), ConduitT a Void m ())
pairTMQueue :: MonadIO m => m (ConduitT () a m (), ConduitT a Void m ())
pairTMChan :: MonadIO m => m (ConduitT () a m (), ConduitT a Void m ())
pairTBQueue :: MonadIO m => Int -> m (ConduitT () a m (), ConduitT a Void m ())
pairTBMQueue :: MonadIO m => Int -> m (ConduitT () a m (), ConduitT a Void m ())
pairTBMChan :: MonadIO m => Int -> m (ConduitT () a m (), ConduitT a Void m ())
instance Control.Monad.IO.Class.MonadIO m => Data.Conduit.Utils.IsConduit m Control.Concurrent.STM.TBQueue.TBQueue
instance Control.Monad.IO.Class.MonadIO m => Data.Conduit.Utils.IsConduit m Control.Concurrent.STM.TBMQueue.TBMQueue
instance Control.Monad.IO.Class.MonadIO m => Data.Conduit.Utils.IsConduit m Control.Concurrent.STM.TMQueue.TMQueue
instance Control.Monad.IO.Class.MonadIO m => Data.Conduit.Utils.IsConduit m Control.Concurrent.STM.TQueue.TQueue
instance Control.Monad.IO.Class.MonadIO m => Data.Conduit.Utils.IsConduit m Control.Concurrent.STM.TBMChan.TBMChan
instance Control.Monad.IO.Class.MonadIO m => Data.Conduit.Utils.IsConduit m Control.Concurrent.STM.TMChan.TMChan
instance Data.Conduit.Utils.BoundedStream (Data.Conduit.Utils.Proxy2 Control.Concurrent.STM.TBQueue.TBQueue) Control.Concurrent.STM.TBQueue.TBQueue
instance Data.Conduit.Utils.BoundedStream (Data.Conduit.Utils.Proxy2 Control.Concurrent.STM.TBMQueue.TBMQueue) Control.Concurrent.STM.TBMQueue.TBMQueue
instance Data.Conduit.Utils.BoundedStream (Data.Conduit.Utils.Proxy2 Control.Concurrent.STM.TBMChan.TBMChan) Control.Concurrent.STM.TBMChan.TBMChan
instance Data.Conduit.Utils.UnboundedStream (Data.Conduit.Utils.Proxy2 Control.Concurrent.STM.TMQueue.TMQueue) Control.Concurrent.STM.TMQueue.TMQueue
instance Data.Conduit.Utils.UnboundedStream (Data.Conduit.Utils.Proxy2 Control.Concurrent.STM.TQueue.TQueue) Control.Concurrent.STM.TQueue.TQueue
instance Data.Conduit.Utils.UnboundedStream (Data.Conduit.Utils.Proxy2 Control.Concurrent.STM.TMChan.TMChan) Control.Concurrent.STM.TMChan.TMChan
