This library is a drop-in replacement that reimplements several IO methods with replacements using MSG_DONTWAIT for BasicSocket. This allows us to avoid unnecessary system calls and GVL bouncing.
We’ve reimplemented the readpartial, read_nonblock, write_nonblock, read and write instance methods normally inherited from the IO class directly into BasicSocket with socket-specific system calls and flags.
This library is only intended for Ruby 1.9.2+ and will not build with other versions of Ruby. This only supports operating systems with complete support of the non-POSIX MSG_DONTWAIT flag for send(2) and recv(2) syscalls on stream sockets.
This library is fully-supported and stable on GNU/Linux 2.6+. It is experimental and unsupported on other systems unless someone steps forward to support them. Some operating systems have incomplete/broken support for the MSG_DONTWAIT flag on various types of stream sockets.
If you’re open to using a non-standard API which isn’t a drop-in replacement, kgio is recommended. It is more portable and faster because it avoids expensive exception generation.
Avoid use of fcntl(2) to set O_NONBLOCK in favor of MSG_DONTWAIT when using non-blocking I/O. We unset O_NONBLOCK if we need to block and release the GVL instead of relying on select(2).
Avoids select(2) entirely in favor of blocking I/O when the GVL is released. This allows using file descriptor numbers higher than 1023 without overflowing select(2) buffers or relying on malloc() to allocate large fdsets.
BasicSocket#read uses recv(2) with MSG_WAITALL to avoid extra system calls for larger reads.
Thread and signal-safe, releases the GVL for all blocking operations and retries if system calls are interrupted.
We ignore taint/$SAFE checks, we’ll support it if there’s demand, but we doubt there is…
Ignores userspace read buffering in Ruby 1.9, relying on line-oriented socket I/O is a good way to get DoS-ed.
Does not support 1.9 encoding filters. 1.9 defaults all sockets to Encoding::BINARY anyways, so this should not be noticeable to code that leaves socket encodings untouched.
Does not support write buffering in userspace. Ruby defaults all sockets to “IO#sync = true”, anyways so this does not affect code that leaves the default setting untouched.
If you’re using a packaged Ruby distribution, make sure you have a C compiler and the matching Ruby development libraries and headers. You need Ruby 1.9.2+ to install socket_dontwait. Previous versions of Ruby will NOT be supported.
If you use RubyGems:
gem install socket_dontwait
Otherwise grab the latest tarball from:
bogomips.org/socket_dontwait/files/
Unpack it, and run “ruby setup.rb”
You can get the latest source via git from the following locations:
git://bogomips.org/socket_dontwait.git git://repo.or.cz/socket_dontwait.git (mirror)
You may browse the code from the web and download the latest snapshot tarballs here:
repo.or.cz/w/socket_dontwait.git (gitweb)
Inline patches (from “git format-patch”) to the mailing list are preferred because they allow code review and comments in the reply to the patch.
We will adhere to mostly the same conventions for patch submissions as git itself. See the Documentation/SubmittingPatches document distributed with git on on patch submission guidelines to follow. Just don’t email the git mailing list or maintainer with socket_dontwait patches.
This was originally created for the Rainbows! project (but may be used by others), so we’ll reuse their mailing list at rainbows-talk@rubyforge.org.
Originally generated with the Darkfish Rdoc Generator 2, modified by wrongdoc.