README

   1 = kgio - kinder, gentler I/O for Ruby
   2
   3 kgio provides non-blocking I/O methods for Ruby without raising
   4 exceptions on EAGAIN and EINPROGRESS.  It is intended for use with the
   5 Unicorn and Rainbows! Rack servers, but may be used by other
   6 applications.
   7
   8 == Features
   9
  10 * Avoids exceptions on common EAGAIN/EINPROGRESS errors, returning
  11   Kgio::WaitReadable or Kgio::WaitWritable instead.
  12   These exceptions got more expensive to hit under Ruby 1.9.2
  13   (but should be fixed in Ruby 1.9.3 to 1.9.1 performance levels)
  14
  15 * Returns the unwritten portion of the string on partial writes,
  16   making it ideal for buffering unwritten portions.
  17
  18 * May be assigned Kgio.wait_writable= and Kgio.wait_readable=
  19   methods to allow socket/pipe objects to make custom callbacks
  20   (such as adding the file descriptor to a poll set and yielding
  21   the current Fiber).
  22
  23 * Uses
  24   {accept4}[http://kernel.org/doc/man-pages/online/pages/man2/accept4.2.html]
  25   on new GNU/Linux systems to avoid unnecessary fcntl() calls
  26
  27 * uses MSG_DONTWAIT where available to further avoid unnecessary fcntl() calls
  28
  29 == Install
  30
  31 The library consists of a C extension so you'll need a C compiler
  32 and Ruby development libraries/headers.
  33
  34 You may download the tarball from the Mongrel project page on Rubyforge
  35 and run setup.rb after unpacking it:
  36
  37 http://rubyforge.org/frs/?group_id=8977
  38
  39 You may also install it via RubyGems on Gemcutter:
  40
  41   gem install kgio
  42
  43 You can get the latest source via git from the following locations
  44 (these versions may not be stable):
  45
  46   git://git.bogomips.org/kgio.git
  47   git://repo.or.cz/kgio.git (mirror)
  48
  49 You may browse the code from the web and download the latest snapshot
  50 tarballs here:
  51
  52 * http://git.bogomips.org/cgit/kgio.git (cgit)
  53 * http://repo.or.cz/w/kgio.git (gitweb)
  54
  55 See the HACKING guide on how to contribute and build prerelease gems
  56 from git.
  57
  58 == Contact
  59
  60 All feedback (bug reports, user/development dicussion, patches, pull
  61 requests) go to the mailing list/newsgroup.  See the ISSUES document for
  62 information on the
  63 {Unicorn mailing list}[mailto:mongrel-unicorn@rubyforge.org].
  64
  65 For the latest on kgio releases, you may check our NEWS page (and
  66 subscribe to our Atom feed).