README

   1 = socket_dontwait - socket methods using MSG_DONTWAIT and more
   2
   3 This library is a drop-in replacement that reimplements several IO
   4 methods with replacements using MSG_DONTWAIT for BasicSocket.  This
   5 allows us to avoid unnecessary system calls and GVL bouncing.
   6
   7 We've reimplemented the +readpartial+, +read_nonblock+,
   8 +write_nonblock+, +read+ and +write+ instance methods normally inherited
   9 from the IO class directly into BasicSocket with socket-specific system
  10 calls and flags.
  11
  12 This library is only intended for Ruby 1.9 and will not build with other
  13 versions of Ruby.  This only supports operating systems with complete
  14 support of the non-POSIX MSG_DONTWAIT flag for send(2) and recv(2)
  15 syscalls on stream sockets.
  16
  17 This library is fully-supported and stable on GNU/Linux 2.6+.  It is
  18 experimental and unsupported on other systems unless someone steps
  19 forward to support them.  Some operating systems have incomplete/broken
  20 support for the MSG_DONTWAIT flag on various types of stream sockets.
  21
  22 == Features
  23
  24 * Avoid use of fcntl(2) to set O_NONBLOCK in favor of MSG_DONTWAIT when
  25   using non-blocking I/O.  We _unset_ O_NONBLOCK if we need to block
  26   and release the GVL instead of relying on select(2).
  27
  28 * Avoids select(2) entirely in favor of blocking I/O when the
  29   GVL is released.  This allows using file descriptor numbers higher
  30   than 1023 without overflowing select(2) buffers or relying on malloc()
  31   to allocate large fdsets.
  32
  33 * BasicSocket#read uses recv(2) with MSG_WAITALL to avoid extra system
  34   calls for larger reads.
  35
  36 * Thread and signal-safe, releases the GVL for all blocking operations
  37   and retries if system calls are interrupted.
  38
  39 * Includes a 1.9.1-specific workaround to preserve errno after reacquiring
  40   the GVL.  This is
  41   {fixed}[http://redmine.ruby-lang.org/repositories/diff/ruby-19?rev=27401]
  42   in newer versions of Ruby.
  43
  44 * Falls back to line-buffered IO if needed (not recommended).
  45
  46 == Bugs/Caveats
  47
  48 * We ignore taint/$SAFE checks, we'll support it if there's demand,
  49   but we doubt there is...
  50
  51 * Does not support 1.9 encoding filters.  1.9 defaults all sockets to
  52   Encoding::BINARY anyways, so this should not be noticeable to code
  53   that leaves socket encodings untouched.
  54
  55 * Does not support write buffering in userspace.  Ruby defaults all
  56   sockets to "IO#sync = true", anyways so this does not affect code
  57   that leaves the default setting untouched.
  58
  59 * Avoid using line-buffered IO on sockets (IO#gets, IO#each_line),
  60   nearly all of the features of this library are cancelled out when
  61   the line-buffering fallback is used.
  62
  63 == Install
  64
  65 If you're using a packaged Ruby distribution, make sure you have a C
  66 compiler and the matching Ruby development libraries and headers.
  67 You need Ruby 1.9 to install socket_dontwait.  Previous versions of
  68 Ruby will NOT be supported.
  69
  70 If you use RubyGems:
  71
  72     gem install socket_dontwait
  73
  74 Otherwise grab the latest tarball from:
  75
  76 http://bogomips.org/socket_dontwait/files/
  77
  78 Unpack it, and run "ruby setup.rb"
  79
  80 == Development
  81
  82 You can get the latest source via git from the following locations:
  83
  84   git://git.bogomips.org/socket_dontwait.git
  85   git://repo.or.cz/socket_dontwait.git (mirror)
  86
  87 You may browse the code from the web and download the latest snapshot
  88 tarballs here:
  89
  90 * http://git.bogomips.org/cgit/socket_dontwait.git (cgit)
  91 * http://repo.or.cz/w/socket_dontwait.git (gitweb)
  92
  93 Inline patches (from "git format-patch") to the mailing list are
  94 preferred because they allow code review and comments in the reply to
  95 the patch.
  96
  97 We will adhere to mostly the same conventions for patch submissions as
  98 git itself.  See the Documentation/SubmittingPatches document
  99 distributed with git on on patch submission guidelines to follow.  Just
 100 don't email the git mailing list or maintainer with socket_dontwait
 101 patches.
 102
 103 == Contact/Bug Reports/Feedback/Patches/Pull-Requests
 104
 105 This was originally created for the Rainbows! project (but may be used by
 106 others), so we'll reuse their mailing list at
 107 {rainbows-talk@rubyforge.org}[mailto:rainbows-talk@rubyforge.org].