1 = socket_dontwait - socket methods using MSG_DONTWAIT and more
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.
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
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 the
14 non-POSIX MSG_DONTWAIT flag for send(2) and recv(2) syscalls.
16 This library is considered EXPERIMENTAL. If successful, we'll see about
17 getting them integrated into the standard Ruby socket library.
21 * Avoid use of fcntl(2) to set O_NONBLOCK in favor of MSG_DONTWAIT when
22 using non-blocking I/O. We _unset_ O_NONBLOCK if we need to block
23 and release the GVL instead of relying on select(2).
25 * Avoids select(2) entirely in favor of blocking I/O when the
26 GVL is released. This allows using file descriptor numbers higher
27 than 1023 without overflowing select(2) buffers.
29 * BasicSocket#read uses recv(2) with MSG_WAITALL to avoid extra system
30 calls for larger reads.
32 * Thread and signal-safe, releases the GVL for all blocking operations
33 and retries if system calls are interrupted.
35 * Includes a 1.9.1-specific workaround to preserve errno after reacquiring
37 {fixed}[http://redmine.ruby-lang.org/repositories/diff/ruby-19?rev=27401]
38 in newer versions of Ruby.
40 * Falls back to line-buffered IO if needed (not recommended).
44 * We ignore taint/$SAFE checks, we'll support it if there's demand,
45 but we doubt there is...
47 * Does not support 1.9 encoding filters. 1.9 defaults all sockets to
48 Encoding::BINARY anyways, so this should not be noticeable to code
49 that leaves socket encodings untouched.
51 * Does not support write buffering in userspace. Ruby defaults all
52 sockets to "IO#sync = true", anyways so this does not affect code
53 that leaves the default setting untouched.
55 * Avoid using line-buffered IO on sockets (IO#gets, IO#each_line),
56 nearly all of the features of this library are cancelled out when
57 the line-buffering fallback is used.
61 If you're using a packaged Ruby distribution, make sure you have a C
62 compiler and the matching Ruby development libraries and headers.
63 You need Ruby 1.9 to install socket_dontwait. Previous versions of
64 Ruby will NOT be supported.
68 gem install socket_dontwait
70 Otherwise grab the latest tarball from:
72 http://bogomips.org/socket_dontwait/files/
74 Unpack it, and run "ruby setup.rb"
78 You can get the latest source via git from the following locations:
80 git://git.bogomips.org/socket_dontwait.git
81 git://repo.or.cz/socket_dontwait.git (mirror)
83 You may browse the code from the web and download the latest snapshot
86 * http://git.bogomips.org/cgit/socket_dontwait.git (cgit)
87 * http://repo.or.cz/w/socket_dontwait.git (gitweb)
89 Inline patches (from "git format-patch") to the mailing list are
90 preferred because they allow code review and comments in the reply to
93 We will adhere to mostly the same conventions for patch submissions as
94 git itself. See the Documentation/SubmittingPatches document
95 distributed with git on on patch submission guidelines to follow. Just
96 don't email the git mailing list or maintainer with socket_dontwait
99 == Contact/Bug Reports/Feedback/Patches/Pull-Requests
101 This was originally created for the Rainbows! project (but may be used by
102 others), so we'll reuse their mailing list at
103 {rainbows-talk@rubyforge.org}[mailto:rainbows-talk@rubyforge.org].