README

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