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


-- | Socket to Socket Data Splicing
--   
--   A library that implements efficient socket to socket data transfer
--   loops for proxy servers.
--   
--   On Linux, it uses the zero-copy splice() system call:
--   <a>http://kerneltrap.org/node/6505</a>.
--   
--   On all other operating systems, it currently falls back to a portable
--   Haskell implementation that allocates a constant-sized memory buffer
--   before it enters an inner loop which then uses hGetBufSome and
--   hPutBuf; this avoids lots of tiny allocations as would otherwise be
--   caused by recv and sendAll functions from Network.Socket.ByteString.
--   
--   This work is funded by Corsis Research and used in:
--   
--   PortFusion ]-[ayabusa – German research project for building the
--   simplest high-performance distributed reverse / forward proxy.
--   
--   <a>https://sourceforge.net/p/portfusion/wiki/RoadMap/</a>
@package splice
@version 0.2


-- | This library implements efficient socket to socket data transfer loops
--   for proxy servers.
--   
--   On Linux, it uses the zero-copy splice() system call:
--   <a>http://kerneltrap.org/node/6505</a>.
--   
--   On all other operating systems, it currently falls back to a portable
--   Haskell implementation that allocates a constant-sized memory buffer
--   before it enters an inner loop which then uses hGetBufSome and
--   hPutBuf; this avoids lots of tiny allocations as would otherwise be
--   caused by recv and sendAll functions from Network.Socket.ByteString.
module Network.Socket.Splice

-- | Pipes data from one socket to another in an **infinite loop**.
--   
--   On Linux this happens in kernel space with zero copying between kernel
--   and user spaces.
--   
--   On other operating systems, a portable implementation utilizes a user
--   space buffer and works on handles instead of file descriptors.
splice :: ChunkSize -> Socket -> Socket -> IO ()

-- | The numeric type used to recommend chunk sizes for moving data between
--   sockets used by both the Linux <a>splice</a> and the portable
--   implementation of <a>splice</a>.
type ChunkSize = Word32

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

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

-- | Moves data between two file descriptors without copying between kernel
--   address space and user address space. It transfers up to <tt>len</tt>
--   bytes of data from the file descriptor <tt>fd_in</tt> to the file file
--   descriptor <tt>fd_out</tt>, where one of the descriptors must refer to
--   a pipe.
--   
--   <a>c_splice</a> is NOT a loop and needs to called repeatedly. For an
--   example, see the source code of <a>splice</a>.
c_splice :: Fd -> Ptr (Int64) -> Fd -> Ptr (Int64) -> (Word32) -> Word -> IO (Int32)

-- | Attempt to move pages instead of copying. This is only a hint to the
--   kernel: pages may stil be copied if the kernel cannot move the pages
--   from the pipe, or if the pipe buffers don't refer to full pages.
sPLICE_F_MOVE :: Word

-- | More data will be coming in a subsequent splice. This is a helpful
--   hint when <tt>fd_out</tt> refers to a socket.
sPLICE_F_MORE :: Word

-- | Do not block on I/O. This makes the splice pipe operations
--   nonblocking, but splice() may nevertheless block because the file
--   descriptors that are spliced to/from may block (unless they have the
--   O_NONBLOCK flag set).
sPLICE_F_NONBLOCK :: Word