README

   1 = kgio - kinder, gentler I/O for Ruby
   2
   3 This is a legacy project, do not use it for new projects.  Ruby
   4 2.3 and later should make this obsolete.  kgio provides
   5 non-blocking I/O methods for Ruby without raising exceptions on
   6 EAGAIN and EINPROGRESS.
   7
   8 == Features
   9
  10 * Can avoid expensive exceptions on common EAGAIN/EINPROGRESS errors,
  11   returning :wait_readable or :wait_writable instead.
  12   These exceptions got more expensive to hit under Ruby 1.9.2
  13   (but were fixed in Ruby 1.9.3 and later to 1.9.1 performance levels,
  14   which were still bad)
  15
  16 * Returns the unwritten portion of the string on partial writes,
  17   making it ideal for buffering unwritten data.
  18
  19 * May call any method defined to be "kgio_wait_writable" or
  20   "kgio_wait_readable" methods to allow socket/pipe objects to make custom
  21   callbacks (such as adding the file descriptor to a poll set and yielding
  22   the current Fiber).
  23
  24 * Uses {accept4}[http://man7.org/linux/man-pages/man2/accept4.2.html]
  25   on newer GNU/Linux systems to avoid unnecessary fcntl() calls
  26
  27 * Uses MSG_DONTWAIT on GNU/Linux to further avoid unnecessary fcntl() calls
  28
  29 * Compatible with existing Ruby IO objects and Ruby threading.
  30
  31 == Install
  32
  33 The library consists of a C extension so you'll need a Unix-like system
  34 with a C compiler and Ruby development libraries/headers.
  35 You may install it via RubyGems.org:
  36
  37   gem install kgio
  38
  39 You can get the latest source via git from the following locations
  40 (these versions may not be stable):
  41
  42   git://bogomips.org/kgio.git
  43   git://repo.or.cz/kgio.git (mirror)
  44
  45 You may browse the code from the web and download the latest snapshot
  46 tarballs here:
  47
  48 * https://bogomips.org/kgio.git
  49 * http://repo.or.cz/w/kgio.git (gitweb)
  50
  51 See the HACKING guide on how to contribute and build prerelease gems
  52 from git.
  53
  54 == Contact
  55
  56 All feedback (bug reports, user/development dicussion, patches, pull
  57 requests) go to the mailing list/newsgroup.  See the ISSUES document for
  58 information on the {kgio mailing list}[mailto:kgio-public@bogomips.org]
  59
  60 For the latest on kgio releases, you may check our NEWS page (and
  61 subscribe to our Atom feed).