LICENSE NEWS README
IO Splice

Methods

::copy_stream ::full ::partial

module IO::Splice

Constants

F_GETPIPE_SZ

fcntl() command constant used to return the size of a pipe. This constant is only defined when running Linux 2.6.35 or later. For convenience, use IO#pipe_size instead.

F_GIFT

Only usable by vmsplice. This flag probably not useful in the context of Ruby applications which cannot control alignment.

F_MORE

Indicate that there may be more data coming into the outbound descriptor. This can allow the kernel to avoid sending partial frames from sockets. Currently only used with splice.

F_MOVE

Attempt to move pages instead of copying. This is only a hint and support for it was removed in Linux 2.6.21. It will be re-added for FUSE filesystems only in Linux 2.6.35.

F_NONBLOCK

Do not block on pipe I/O. This flag only affects the pipe(s) being spliced from/to and has no effect on the non-pipe descriptor (which requires non-blocking operation to be set explicitly).

The non-blocking flag (O_NONBLOCK) on the pipe descriptors themselves are ignored by this family of functions, and using this flag is the only way to get non-blocking operation out of them.

It is highly recommended this flag be set (or IO.trysplice used) whenever splicing from a socket into a pipe unless there is another (native) thread or process doing a blocking read on that pipe. Otherwise it is possible to block a single-threaded process if the socket buffers are larger than the pipe buffers.

F_SETPIPE_SZ

fcntl() command constant used to set the size of a pipe. This constant is only defined when running Linux 2.6.35 or later. For convenience, use IO#pipe_size= instead.

MAX_AT_ONCE

The maximum size we're allowed to splice at once. Larger sizes will be broken up and retried if the WAITALL flag or IO::Splice.copy_stream is used.

PIPE_BUF

The maximum size of an atomic write to a pipe POSIX requires this to be at least 512 bytes. Under Linux, this is 4096 bytes.

PIPE_CAPA

The maximum default capacity of the pipe in bytes. Under stock Linux, this is 65536 bytes as of 2.6.11, and 4096 before We detect this at runtime as it is easy to recompile the kernel and set a new value. Starting with Linux 2.6.35, pipe capacity will be tunable and this will only represent the default capacity of a newly-created pipe.

Public Class Methods

copy_stream (src, dst, len = nil, src_offset = nil) source

copies the contents of the IO object given by src to dst If len is specified, then only len bytes are copied and EOFError is raised if fewer than len bytes could be copied. Otherwise the copy will be until EOF is reached on the src. src and dst must be IO objects or respond to to_io

Unlike IO.copy_stream, this does not take into account userspace I/O buffers nor IO-like objects with no underlying file descriptor (e.g. StringIO).

This is unsafe for socket-to-socket copies unless there is an active (blocking) reader on the other end.

This method is deprecated and will be removed in a future, as it is potentially unsafe for socket-to-socket operations and difficult-to-use. IO.copy_stream on Linux 2.6.33 and later allows using sendfile for file-to-file copies, so this offers no advantage.

full (src, dst, len, src_offset) source

splice the full amount specified from src to dst Either dst or src must be a pipe. dst and src may BOTH be pipes in Linux 2.6.31 or later. This will block and wait for IO completion of len Raises EOFError if end of file is reached. bytes. Returns the number of bytes actually spliced (always len) unless src does not have len bytes to read.

Do not use this method to splice a socket src into a pipe dst unless there is another process or native thread doing a blocking read on the other end of the dst pipe.

This method is safe for splicing a pipe src into any type of dst IO.

partial (src, dst, len, src_offset) source

splice up to len bytes from src to dst. Either dst or src must be a pipe. dst and src may BOTH be pipes in Linux 2.6.31 or later. Returns the number of bytes actually spliced. Like IO#readpartial, this never returns Errno::EAGAIN


Pages Classes Methods
mail archives: https://yhbt.net/ruby-io-splice/
public: ruby-io-splice@yhbt.net
source code: git clone https://yhbt.net/ruby_io_splice.git