-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Socket to Socket Data Splicing (supports all operating systems)
--
-- A library that 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.
--
--
-- - Corsis Research This work is funded by Corsis Research
-- (http://corsis.eu) for the development of
-- - PortFusion ]-[ayabusa (はやぶさ) (Hayabusa) – German-Japanese
-- joint research project for building the simplest and most concise
-- high-performance distributed reverse / forward proxy possible
-- (https://sourceforge.net/p/portfusion/wiki/RoadMap/).
--
@package splice
@version 0.4
-- | Exposes the GNU/Linux system call splice().
--
-- This module is only available (compiled & exposed) on
-- Linux.
module System.IO.Splice.Linux
-- | Moves data between two file descriptors without copying between kernel
-- address space and user address space. It transfers up to len
-- bytes of data from the file descriptor fd_in to the file
-- descriptor fd_out, where one of the descriptors must refer to
-- a pipe.
--
-- c_splice is NOT a loop and needs to be called
-- repeatedly.
--
-- For an example, see splice.
c_splice :: Fd -> Ptr (Int64) -> Fd -> Ptr (Int64) -> ChunkSize -> Word -> IO (Int32)
-- | The numeric type used by c_splice for chunk size
-- recommendations when moving data.
type ChunkSize = Word32
-- | Attempt to move pages instead of copying. This is only a hint to the
-- kernel: pages may stil be copied (in kernel address space) 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 c_splice. This is a
-- helpful hint when fd_out refers to a socket.
sPLICE_F_MORE :: Word
-- | Do not block on I/O. This makes the c_splice pipe operations
-- nonblocking, but c_splice may nevertheless block because the
-- file descriptors that are c_spliced to/from may block (unless
-- they have the O_NONBLOCK flag set).
sPLICE_F_NONBLOCK :: Word
-- | 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:
--
--
--
--
-- 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.
--
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 = ChunkSize
-- | 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
-- 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
--
hSplice :: Int -> Handle -> Handle -> IO ()
-- | GNU/Linux splice() system call loop.
--
--
-- - creates a pipe in kernel address space
-- - uses it until the loop terminates by exception
-- - closes the pipe and returns
--
fdSplice :: ChunkSize -> Fd -> Fd -> IO ()