-- 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 Linux, it uses and exposes the zero-copy <tt>splice()</tt> system
--   call: <a>http://kerneltrap.org/node/6505</a>.
--   
--   On other operating systems, it currently falls back to a portable
--   Haskell implementation.
--   
--   <ul>
--   <li><i>Corsis Research</i> This work is funded by Corsis Research
--   (<a>http://corsis.eu</a>) for the development of</li>
--   <li><i>PortFusion ]-[ayabusa (はやぶさ) (Hayabusa)</i> – German-Japanese
--   joint research project for building the simplest and most concise
--   high-performance distributed reverse / forward proxy possible
--   (<a>https://sourceforge.net/p/portfusion/wiki/RoadMap/</a>).</li>
--   </ul>
@package splice
@version 0.3.1


-- | Exposes the GNU/Linux system call <tt>splice()</tt>.
--   
--   <i>This module is only available (compiled &amp; exposed) on
--   Linux.</i>
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 <tt>len</tt>
--   bytes of data from the file descriptor <tt>fd_in</tt> to the file
--   descriptor <tt>fd_out</tt>, where one of the descriptors must refer to
--   a pipe.
--   
--   <a>c_splice</a> is <i>NOT</i> a loop and needs to be called
--   repeatedly.
--   
--   For an example, see <a>splice</a>.
c_splice :: Fd -> Ptr (Int64) -> Fd -> Ptr (Int64) -> ChunkSize -> Word -> IO (Int32)

-- | The numeric type used by <a>c_splice</a> 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 (<i>in kernel address space</i>) 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


-- | This library implements most efficient socket to socket data transfer
--   loops for proxy servers on each operating system.
--   
--   On Linux, it uses and exposes the zero-copy <tt>splice()</tt> system
--   call: <a>http://kerneltrap.org/node/6505</a>.
--   
--   On other operating systems, it currently falls back to a portable
--   Haskell implementation – which first allocates a constant-sized memory
--   buffer in user address, then enters an inner loop which uses
--   <a>hGetBufSome</a> and <a>hPutBuf</a> on this user-space buffer. This
--   avoids tony of tiny allocations as might 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>.
--   
--   On Linux this uses the <tt>splice()</tt> system call and eliminates
--   copying between kernel and user address spaces.
--   
--   On other operating systems, a portable Haskell implementation utilizes
--   a user space buffer.
splice :: ChunkSize -> Socket -> Socket -> 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 = ChunkSize

-- | 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
--   which can be safely ignored.
try_ :: IO () -> IO ()