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


-- | Cross-platform Socket to Socket Data Splicing
--   
--   A library that implements most efficient socket to socket data
--   transfer loops for proxy servers on all operating systems.
--   
--   On GNU/Linux, it exports the zero-copy system call <tt>c_splice()</tt>
--   (<a>http://en.wikipedia.org/wiki/Splice_(system_call)#Requirements</a>)
--   in <tt>System.IO.Splice.Linux</tt>.
--   
--   On other operating systems, it only exports a portable Haskell
--   implementation.
--   
--   A unified sockets API for all operating systems is available in
--   <tt>Network.Socket.Splice</tt>.
--   
--   <ul>
--   <li><i>Version Scheme</i> Major-<tt><i>R</i></tt>-ewrite .
--   New-<tt><i>F</i></tt>-unctionality .
--   <tt><i>I</i></tt>-mprovementAndBugFixes .
--   <tt><i>P</i></tt>-ackagingOnly</li>
--   </ul>
--   
--   <ul>
--   <li><tt>PackagingOnly</tt> changes are made for quality assurance
--   reasons.</li>
--   </ul>
@package splice
@version 0.6.1.1


-- | This library implements most efficient socket to socket data transfer
--   loops for proxy servers on each operating system.
--   
--   On GNU/Linux, it uses and exposes the zero-copy <tt>splice()</tt>
--   system call: <a>http://kerneltrap.org/node/6505</a>.
--   
--   On all other operating systems, it currently falls back to a portable
--   Haskell implementation – which allocates a single memory buffer in
--   user address space, then enters an inner loop that uses
--   <a>hGetBufSome</a> and <a>hPutBuf</a>. This avoids lots of tiny
--   allocations as would otherwise be caused by <a>recv</a> and
--   <a>sendAll</a> from the <tt>bytestring</tt> package.
module Network.Socket.Splice

-- | Pipes data from one socket to another in an <i>infinite loop</i>.
--   
--   <a>splice</a> currently has two implementations:
--   
--   <ul>
--   <li><i>on GNU/Linux using <tt>fdSplice</tt> ≅</i></li>
--   </ul>
--   
--   <pre>
--   splice len (sIn, _       ) (sOut, _        ) = ... fdSplice ...
--   </pre>
--   
--   <ul>
--   <li><i>on all other operating systems using <a>hSplice</a> ≅</i></li>
--   </ul>
--   
--   <pre>
--   splice len (_  , Just hIn) (_   , Just hOut) = ... hSplice  ...
--   </pre>
--   
--   <ul>
--   <li><i>Notes</i></li>
--   </ul>
--   
--   <ul>
--   <li><tt>fdSplice</tt> and <tt>fdSplice</tt> implementation of
--   <a>splice</a> are only available on GNU/Linux.</li>
--   <li><a>hSplice</a> is always available and the <a>hSplice</a>
--   implementation of <a>splice</a> can be forced on GNU/Linux by defining
--   the <tt>portable</tt> flag at compile time.</li>
--   <li><a>hSplice</a> implementation requires handles in
--   <a>NoBuffering</a> mode.</li>
--   <li><a>splice</a> is a terminal loop on two sockets and once entered
--   its sockets and handles cannot be interleaved by other IO
--   operations.</li>
--   </ul>
splice :: ChunkSize -> (Socket, Maybe Handle) -> (Socket, Maybe Handle) -> IO ()

-- | The numeric type to recommend chunk sizes for moving data between
--   sockets used by both zero-copy and portable implementations of
--   <a>splice</a>.
type ChunkSize = Int

-- | Indicates whether <a>splice</a> uses zero-copy system calls or the
--   portable user space Haskell implementation.
zeroCopy :: Bool

-- | Similar to <a>try</a> but used when an obvious exception is expected
--   and can be handled easily. Unlike <a>finally</a> exceptions are
--   <i>NOT</i> rethrown once handled.
tryWith :: (SomeException -> IO a) -> IO a -> IO a

-- | Similar to <a>try</a> but used when an obvious exception is expected
--   which can be safely ignored.
try_ :: IO () -> IO ()

-- | The portable Haskell loop.
--   
--   <ol>
--   <li>allocates a <i>single</i> memory buffer in user address space</li>
--   <li>uses it until the loop terminates by exception</li>
--   <li>frees the buffer and returns</li>
--   </ol>
--   
--   <ul>
--   <li><i>Notes</i></li>
--   </ul>
--   
--   <ul>
--   <li>the socket handles are required to be in <a>NoBuffering</a>
--   mode.</li>
--   </ul>
hSplice :: Int -> Handle -> Handle -> IO ()
