README

   1 = io_splice - zero-copy pipe I/O for Linux and Ruby
   2
   3 The splice family of Linux system calls can transfer data between file
   4 descriptors without the need to copy data into userspace.  Instead of a
   5 userspace buffer, they rely on an ordinary Unix pipe as a kernel-level
   6 buffer.  The `splice' and `tee' syscalls are also provided by the
   7 {sleepy_penguin}[https://yhbt.net/sleepy_penguin/] library.
   8 "io_splice" remains maintained for old applications or users
   9 experimenting with the vmsplice syscalls
  10
  11 == Features
  12
  13 * Efficient zero-copy I/O avoids data copies into userspace,
  14   reducing garbage for the Ruby garbage collector as a side effect.
  15
  16 * More flexible than sendfile, may be used to enable copies between
  17   arbitrary file descriptors (assuming kernel support), not just
  18   file-to-socket (or file-to-anything in newer Linux).
  19
  20 * Thread-safe blocking operations under Ruby 1.9+, releases GVL
  21   if blocking operations are used.
  22
  23 * Safely usable with non-blocking I/O frameworks (unlike IO.copy_stream)
  24   when combined with the IO::Splice::F_NONBLOCK flag.
  25
  26 * Fully-documented library API and
  27   {examples}[https://yhbt.net/ruby_io_splice/examples/]
  28
  29 * Adds helpful IO#pipe_size and IO#pipe_size= accessor methods for
  30   resizing the pipe buffer in Linux 2.6.35 or later.
  31
  32 == Install
  33
  34 Operating system support for the splice(2), tee(2) and vmsplice(2)
  35 system calls is required.  Currently, only Linux 2.6.17 or later with a
  36 modern C library (glibc 2.5 or later) support these system calls.  Using
  37 the latest stable Linux kernel is *HIGHLY* recommended as there have
  38 been numerous bugs in the early releases of these system calls.
  39
  40 If you're using a packaged Ruby distribution, make sure you have a C
  41 compiler and the matching Ruby development libraries and headers.
  42
  43 If you use RubyGems:
  44
  45     gem install io_splice
  46
  47 Otherwise grab the latest tarball from:
  48
  49 https://yhbt.net/ruby_io_splice/files/
  50
  51 Unpack it, and run "ruby setup.rb"
  52
  53 == Usage
  54
  55 Our API matches the C API closely, see the RDoc for full API
  56 documentation and the Linux manpages for more details.
  57
  58 All of these system calls are fairly new have seen limited usage
  59 anywhere, even outside of the Ruby world.
  60
  61 If you encounter problems (privilege escalation, memory leaks (in the
  62 kernel), poor performance, corrupt data, etc..), try upgrading the Linux
  63 kernel to the latest stable version.
  64
  65 These system calls have a lot of potential, and will hopefully be
  66 standardized and available in non-Linux kernels some day.
  67
  68 == Development
  69
  70 You can get the latest source via git from the following locations:
  71
  72   https://yhbt.net/ruby_io_splice.git
  73   https://repo.or.cz/w/ruby_io_splice.git (mirror)
  74
  75 You may browse the code from the web and download the latest snapshot
  76 tarballs here:
  77
  78 * https://yhbt.net/ruby_io_splice.git
  79 * https://repo.or.cz/w/ruby_io_splice.git (gitweb)
  80
  81 Inline patches (from "git format-patch") to the mailing list are
  82 preferred because they allow code review and comments in the reply to
  83 the patch, but attachments are fine, too.
  84
  85 We will adhere to mostly the same conventions for patch submissions as
  86 git itself.  See the Documentation/SubmittingPatches document
  87 distributed with git on on patch submission guidelines to follow.  Just
  88 don't email the git mailing list or maintainer with io_splice patches.
  89
  90 == Contact
  91
  92 All feedback (bug reports, user/development discussion, patches, pull
  93 requests) go to the mailing list: mailto:ruby-io-splice@yhbt.net
  94
  95 Send patches (from "git format-patch") with "git send-email" and do not
  96 send HTML email or attachments.  We are very responsive to email and you
  97 will usually get a response within 24-72 hours.
  98
  99 == Mailing List Archives
 100
 101 * https://yhbt.net/ruby-io-splice/
 102 * nntp://news.public-inbox.org/inbox.comp.lang.ruby.io-splice
 103 * nntp://ou63pmih66umazou.onion/inbox.comp.lang.ruby.io-splice
 104
 105 Anybody may post without a subscription, but HTML mail will
 106 be rejected: mailto:ruby-io-splice@yhbt.net