-- 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 c_splice()
-- (http://kerneltrap.org/node/6505) in
-- System.IO.Splice.Linux.
--
-- On other operating systems, it only exports a portable Haskell
-- implementation.
--
-- A unified sockets API for all operating systems is available in
-- Network.Socket.Splice.
--
--
-- - Version Scheme Major-R-ewrite .
-- New-F-unctionality .
-- I-mprovementAndBugFixes .
-- P-ackagingOnly
--
--
--
-- - PackagingOnly changes are made for quality assurance
-- reasons.
--
@package splice
@version 0.6.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 splice()
-- system call: http://kerneltrap.org/node/6505.
--
-- 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
-- hGetBufSome and hPutBuf. This avoids lots of tiny
-- allocations as would otherwise be caused by recv and
-- sendAll from the bytestring package.
module Network.Socket.Splice
-- | Pipes data from one socket to another in an infinite loop.
--
-- splice currently has two implementations:
--
--
-- - on GNU/Linux using fdSplice ≅
--
--
--
-- splice len (sIn, _ ) (sOut, _ ) = ... fdSplice ...
--
--
--
-- - on all other operating systems using hSplice ≅
--
--
--
-- splice len (_ , Just hIn) (_ , Just hOut) = ... hSplice ...
--
--
--
--
--
-- - fdSplice and fdSplice implementation of
-- splice are only available on GNU/Linux.
-- - hSplice is always available and the hSplice
-- implementation of splice can be forced on GNU/Linux by defining
-- the portable flag at compile time.
-- - hSplice implementation requires handles in
-- NoBuffering mode.
-- - splice is a terminal loop on two sockets and once entered
-- its sockets and handles cannot be interleaved by other IO
-- operations.
--
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
-- splice.
type ChunkSize = Int
-- | Indicates whether splice uses zero-copy system calls or the
-- portable user space Haskell implementation.
zeroCopy :: Bool
-- | Similar to try but used when an obvious exception is expected
-- and can be handled easily. Unlike finally exceptions are
-- NOT rethrown once handled.
tryWith :: (SomeException -> IO a) -> IO a -> IO a
-- | Similar to try but used when an obvious exception is expected
-- which can be safely ignored.
try_ :: IO () -> IO ()
-- | The portable Haskell loop.
--
--
-- - allocates a single memory buffer in user address space
-- - uses it until the loop terminates by exception
-- - frees the buffer and returns
--
--
--
--
--
-- - the socket handles are required to be in NoBuffering
-- mode.
--
hSplice :: Int -> Handle -> Handle -> IO ()