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.
   7
   8 == Features
   9
  10 * Efficient zero-copy I/O avoids data copies into userspace,
  11   reducing garbage for the Ruby garbage collector as a side effect.
  12
  13 * More flexible than sendfile, may be used to enable copies between
  14   arbitrary file descriptors (assuming kernel support), not just
  15   file-to-socket (or file-to-anything in newer Linux).
  16
  17 * Thread-safe blocking operations under Ruby 1.9+, releases GVL
  18   if blocking operations are used.
  19
  20 * Safely usable with non-blocking I/O frameworks (unlike IO.copy_stream)
  21   when combined with the IO::Splice::F_NONBLOCK flag.
  22
  23 * Fully-documented library API and
  24   {examples}[http://bogomips.org/ruby_io_splice/examples/]
  25
  26 * Adds helpful IO#pipe_size and IO#pipe_size= accessor methods for
  27   resizing the pipe buffer in Linux 2.6.35 or later.
  28
  29 == Install
  30
  31 Operating system support for the splice(2), tee(2) and vmsplice(2)
  32 system calls is required.  Currently, only Linux 2.6.17 or later with a
  33 modern C library (glibc 2.5 or later) support these system calls.  Using
  34 the latest stable Linux kernel is *HIGHLY* recommended as there have
  35 been numerous bugs in the early releases of these system calls.
  36
  37 If you're using a packaged Ruby distribution, make sure you have a C
  38 compiler and the matching Ruby development libraries and headers.
  39
  40 If you use RubyGems:
  41
  42     gem install io_splice
  43
  44 Otherwise grab the latest tarball from:
  45
  46 http://bogomips.org/ruby_io_splice/files/
  47
  48 Unpack it, and run "ruby setup.rb"
  49
  50 == Usage
  51
  52 Our API matches the C API closely, see the RDoc for full API
  53 documentation and the Linux manpages for more details.
  54
  55 All of these system calls are fairly new have seen limited usage
  56 anywhere, even outside of the Ruby world.
  57
  58 If you encounter problems (privilege escalation, memory leaks (in the
  59 kernel), poor performance, corrupt data, etc..), try upgrading the Linux
  60 kernel to the latest stable version.
  61
  62 These system calls have a lot of potential, and will hopefully be
  63 standardized and available in non-Linux kernels some day.
  64
  65 == Development
  66
  67 You can get the latest source via git from the following locations:
  68
  69   git://bogomips.org/ruby_io_splice.git
  70   git://repo.or.cz/ruby_io_splice.git (mirror)
  71
  72 You may browse the code from the web and download the latest snapshot
  73 tarballs here:
  74
  75 * http://bogomips.org/ruby_io_splice.git (cgit)
  76 * http://repo.or.cz/w/ruby_io_splice.git (gitweb)
  77
  78 Inline patches (from "git format-patch") to the mailing list are
  79 preferred because they allow code review and comments in the reply to
  80 the patch.
  81
  82 We will adhere to mostly the same conventions for patch submissions as
  83 git itself.  See the Documentation/SubmittingPatches document
  84 distributed with git on on patch submission guidelines to follow.  Just
  85 don't email the git mailing list or maintainer with io_splice patches.
  86
  87 == Contact
  88
  89 All feedback (bug reports, user/development discussion, patches, pull
  90 requests) go to the mailing list: mailto:ruby-io-splice@bogomips.org
  91
  92 Send patches (from "git format-patch") with "git send-email" and do not
  93 send HTML email or attachments.  We are very responsive to email and you
  94 will usually get a response within 24-72 hours.
  95
  96 == Mailing List Archives
  97
  98 We operate a {public-inbox}[http://public-inbox.org/] which
  99 feeds the mailing list.  You may subscribe either using
 100 {ssoma}[http://ssoma.public-inbox.org/] or by sending a mail
 101 to mailto:ruby-io-splice+subscribe@bogomips.org
 102
 103 ssoma is a mail archiver/fetcher using git.  It operates in a similar
 104 fashion to tools such as slrnpull, fetchmail, or getmail.  ssoma
 105 subscription instructions:
 106
 107     URL=git://bogomips.org/ruby-io-splice
 108     LISTNAME=ruby-io-splice
 109
 110     # to initialize a maildir (this may be a new or existing maildir,
 111     # ssoma will not touch existing messages)
 112     # If you prefer mbox, use mbox:/path/to/mbox as the last argument
 113     # You may also use imap://$MAILSERVER/INBOX for an IMAP account
 114     # or imaps:// for an IMAPS account, as well.
 115     ssoma add $LISTNAME $URL maildir:/path/to/maildir
 116
 117     # read with your favorite MUA (only using mutt as an example)
 118     mutt -f /path/to/maildir # (or /path/to/mbox)
 119
 120     # to keep your mbox or maildir up-to-date, periodically run:
 121     ssoma sync $LISTNAME
 122
 123     # your MUA may modify and delete messages from the maildir or mbox,
 124     # this does not affect ssoma functionality at all
 125
 126     # to sync all your ssoma subscriptions
 127     ssoma sync
 128
 129     # You may wish to sync in your cronjob
 130     ssoma sync --cron
 131
 132 * http://bogomips.org/ruby-io-splice/