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


-- | Use network sockets together with the pipes library.
--   
--   Use network sockets together with the <tt>pipes</tt> library.
--   
--   This package is organized using the following namespaces:
--   
--   <ul>
--   <li><a>Pipes.Network.TCP</a> exports pipes and utilities for using TCP
--   connections in a streaming fashion.</li>
--   <li><a>Pipes.Network.TCP.Safe</a> subsumes <a>Pipes.Network.TCP</a>,
--   exporting pipes and functions that allow you to safely establish new
--   TCP connections within a pipeline using the <tt>pipes-safe</tt>
--   facilities. You only need to use this module if you want to safely
--   acquire and release operating system resources within a pipeline.</li>
--   </ul>
--   
--   See the <tt>changelog</tt> file in the source distribution to learn
--   about any important changes between version.
@package pipes-network
@version 0.6.4.1


-- | This minimal module exports facilities that ease the usage of TCP
module Pipes.Network.TCP

-- | Receives bytes from the remote end and sends them downstream.
--   
--   The number of bytes received at once is always in the interval <i>[1
--   .. specified maximum]</i>.
--   
--   This <a>Producer'</a> returns if the remote peer closes its side of
--   the connection or EOF is received.
fromSocket :: MonadIO m => Socket -> Int -> Producer' ByteString m ()

-- | Like <a>fromSocket</a>, except with the first <a>Int</a> argument you
--   can specify the maximum time that each interaction with the remote end
--   can take. If such time elapses before the interaction finishes, then
--   an <a>IOError</a> exception is thrown. The time is specified in
--   microseconds (1 second = 1e6 microseconds).
fromSocketTimeout :: MonadIO m => Int -> Socket -> Int -> Producer' ByteString m ()

-- | Like <a>fromSocket</a>, except the downstream pipe can specify the
--   maximum number of bytes to receive at once using <a>request</a>.
fromSocketN :: MonadIO m => Socket -> Int -> Server' Int ByteString m ()

-- | Like <a>fromSocketN</a>, except with the first <a>Int</a> argument you
--   can specify the maximum time that each interaction with the remote end
--   can take. If such time elapses before the interaction finishes, then
--   an <a>IOError</a> exception is thrown. The time is specified in
--   microseconds (1 second = 1e6 microseconds).
fromSocketTimeoutN :: MonadIO m => Int -> Socket -> Int -> Server' Int ByteString m ()

-- | Sends to the remote end each <a>ByteString</a> received from upstream.
toSocket :: MonadIO m => Socket -> Consumer' ByteString m r

-- | Like <a>toSocket</a> but takes a lazy <a>ByteSring</a> and sends it in
--   a more efficient manner (compared to converting it to a strict
--   <a>ByteString</a> and sending it).
toSocketLazy :: MonadIO m => Socket -> Consumer' ByteString m r

-- | Like <a>toSocket</a> but takes a <tt>[<a>ByteSring</a>]</tt> and sends
--   it in a more efficient manner (compared to converting it to a strict
--   <a>ByteString</a> and sending it).
toSocketMany :: MonadIO m => Socket -> Consumer' [ByteString] m r

-- | Like <a>toSocket</a>, except with the first <a>Int</a> argument you
--   can specify the maximum time that each interaction with the remote end
--   can take. If such time elapses before the interaction finishes, then
--   an <a>IOError</a> exception is thrown. The time is specified in
--   microseconds (1 second = 1e6 microseconds).
toSocketTimeout :: MonadIO m => Int -> Socket -> Consumer' ByteString m r

-- | Like <a>toSocketTimeout</a> but takes a lazy <a>ByteSring</a> and
--   sends it in a more efficient manner (compared to converting it to a
--   strict <a>ByteString</a> and sending it).
toSocketTimeoutLazy :: MonadIO m => Int -> Socket -> Consumer' ByteString m r

-- | Like <a>toSocketTimeout</a> but takes a <tt>[<a>ByteSring</a>]</tt>
--   and sends it in a more efficient manner (compared to converting it to
--   a strict <a>ByteString</a> and sending it).
toSocketTimeoutMany :: MonadIO m => Int -> Socket -> Consumer' [ByteString] m r


-- | This module exports facilities allowing you to safely obtain, use and
--   release <a>Socket</a> resources within a <i>Pipes</i> pipeline, by
--   relying on <tt>pipes-safe</tt>.
--   
--   This module is meant to be used as a replacement of
--   <a>Pipes.Network.TCP</a>, and as such it overrides some functions from
--   <a>Network.Simple.TCP</a> so that they use <a>MonadSafe</a> instead of
--   <a>IO</a> as their base monad. Additionally, It also exports pipes
--   that establish a TCP connection and interact with it in a streaming
--   fashion at once.
--   
--   If you just want to use <a>Socket</a> obtained outside the
--   <i>Pipes</i> pipeline, then you can just ignore this module and use
--   the simpler module <a>Pipes.Network.TCP</a> instead.
module Pipes.Network.TCP.Safe

-- | Like <a>connect</a> from <a>Network.Simple.TCP</a>, but compatible
--   with <a>MonadSafe</a>.
connect :: MonadSafe m => HostName -> ServiceName -> ((Socket, SockAddr) -> m r) -> m r

-- | Like <a>serve</a> from <a>Network.Simple.TCP</a>, but compatible with
--   <a>MonadSafe</a>.
serve :: MonadSafe m => HostPreference -> ServiceName -> ((Socket, SockAddr) -> IO ()) -> m r

-- | Like <a>listen</a> from <a>Network.Simple.TCP</a>, but compatible with
--   <a>MonadSafe</a>.
listen :: MonadSafe m => HostPreference -> ServiceName -> ((Socket, SockAddr) -> m r) -> m r

-- | Like <a>accept</a> from <a>Network.Simple.TCP</a>, but compatible with
--   <a>MonadSafe</a>.
accept :: MonadSafe m => Socket -> ((Socket, SockAddr) -> m r) -> m r

-- | Connect to a TCP server and send downstream the bytes received from
--   the remote end.
--   
--   The connection socket is closed when done or in case of exceptions.
--   
--   Using this <a>Producer'</a> you can write straightforward code like
--   the following, which prints whatever is received from a single TCP
--   connection to a given server listening locally on port 9000, in chunks
--   of up to 4096 bytes:
--   
--   <pre>
--   &gt;&gt;&gt; runSafeT . runEffect $ fromConnect 4096 "127.0.0.1" "9000" &gt;-&gt; P.print
--   </pre>
fromConnect :: MonadSafe m => Int -> HostName -> ServiceName -> Producer' ByteString m ()

-- | Connects to a TCP server, sends to the remote end the bytes received
--   from upstream.
--   
--   The connection socket is closed in case of exceptions.
--   
--   Using this <a>Consumer'</a> you can write straightforward code like
--   the following, which greets a TCP client listening locally at port
--   9000:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; runSafeT . runEffect $ each ["He","llo\r\n"] &gt;-&gt; toConnect "127.0.0.1" "9000"
--   </pre>
toConnect :: MonadSafe m => HostName -> ServiceName -> Consumer' ByteString m r

-- | Like <a>toConnect</a>, but works more efficiently on lazy
--   <a>ByteString</a>s (compared to converting them to a strict
--   <a>ByteString</a> and sending it)
toConnectLazy :: MonadSafe m => HostName -> ServiceName -> Consumer' ByteString m r

-- | Like <a>toConnect</a>, but works more efficiently on
--   <tt>[<a>ByteString</a>]</tt> (compared to converting them to a strict
--   <a>ByteString</a> and sending it)
toConnectMany :: MonadSafe m => HostName -> ServiceName -> Consumer' [ByteString] m r

-- | Binds a listening socket, accepts a single connection and sends
--   downstream any bytes received from the remote end.
--   
--   Less than the specified maximum number of bytes might be received at
--   once.
--   
--   This <a>Producer'</a> returns if the remote peer closes its side of
--   the connection or EOF is received.
--   
--   Both the listening and connection sockets are closed when done or in
--   case of exceptions.
--   
--   Using this <a>Producer'</a> you can write straightforward code like
--   the following, which prints whatever is received from a single TCP
--   connection to port 9000, in chunks of up to 4096 bytes.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; runSafeT . runEffect $ fromServe 4096 "127.0.0.1" "9000" &gt;-&gt; P.print
--   </pre>
fromServe :: MonadSafe m => Int -> HostPreference -> ServiceName -> Producer' ByteString m ()

-- | Binds a listening socket, accepts a single connection, sends to the
--   remote end the bytes received from upstream.
--   
--   Both the listening and connection sockets are closed when done or in
--   case of exceptions.
--   
--   Using this <a>Consumer'</a> you can write straightforward code like
--   the following, which greets a TCP client connecting to port 9000:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; runSafeT . runEffect $ each ["He","llo\r\n"] &gt;-&gt; toServe "127.0.0.1" "9000"
--   </pre>
toServe :: MonadSafe m => HostPreference -> ServiceName -> Consumer' ByteString m r

-- | Like <a>toServe</a>, but works more efficiently on lazy
--   <a>ByteString</a>s (compared to converting them to a strict
--   <a>ByteString</a> and sending it)
toServeLazy :: MonadSafe m => HostPreference -> ServiceName -> Consumer' ByteString m r

-- | Like <a>toServe</a>, but works more efficiently on
--   <tt>[<a>ByteString</a>]</tt> (compared to converting them to a strict
--   <a>ByteString</a> and sending it)
toServeMany :: MonadSafe m => HostPreference -> ServiceName -> Consumer' [ByteString] m r
