socket: Socket#connect_nonblock avoids arg parsing with C API

* ext/socket/socket.c (sock_connect_nonblock):
  avoid argument parsing in C.
  [ruby-core:71439] [Feature #11339]
* ext/socket/lib/socket.rb (Socket#connect_nonblock):
  new wrapper for private method, move RDoc

target 0: a (ruby 2.3.0dev (2015-11-12 trunk 52540) [x86_64-linux])
target 1: b (ruby 2.3.0dev (2015-11-12 avoid-kwarg-capi 52540) [x86_64-linux]

-----------------------------------------------------------
connect_nonblock

require 'tempfile'
require 'socket'
require 'io/wait'
nr = 500000
Tempfile.create(%w(connect_nonblock .sock)) do |tmp|
  path = tmp.path
  File.unlink(path)
  s = UNIXServer.new(path)
  addr = Socket.sockaddr_un(path).freeze
  nr.times do
    c = Socket.new(Socket::AF_UNIX, Socket::SOCK_STREAM)
    while c.connect_nonblock(addr, exception: false) == :wait_writable
      c.wait_writable
    end
    s.accept.close
    c.close
  end
end

-----------------------------------------------------------
raw data:

[["connect_nonblock",
  [[4.014209181070328,
    3.8479955345392227,
    3.981342639774084,
    4.471840236335993,
    3.7867715656757355],
   [3.639054525643587,
    3.58337214961648,
    3.525284394621849,
    3.52646067738533,
    3.511393066495657]]]]

Elapsed time: 37.889623996 (sec)
-----------------------------------------------------------
benchmark results:
minimum results in each 5 measurements.
Execution time (sec)
name             a       b
connect_nonblock   3.787   3.511

Speedup ratio: compare with the result of `a' (greater is better)
name             b
connect_nonblock   1.078

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@52600 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 47 insertions, 0 deletions

diff --git a/ext/socket/lib/socket.rb b/ext/socket/lib/socket.rb
index 6ee89e90d0..86da09e997 100644
--- a/ext/socket/lib/socket.rb
+++ b/ext/socket/lib/socket.rb
@@ -980,6 +980,53 @@ class Socket < BasicSocket
     }
   end
 
+  # call-seq:
+  #   socket.connect_nonblock(remote_sockaddr, [options]) => 0
+  #
+  # Requests a connection to be made on the given +remote_sockaddr+ after
+  # O_NONBLOCK is set for the underlying file descriptor.
+  # Returns 0 if successful, otherwise an exception is raised.
+  #
+  # === Parameter
+  #  # +remote_sockaddr+ - the +struct+ sockaddr contained in a string or Addrinfo object
+  #
+  # === Example:
+  #   # Pull down Google's web page
+  #   require 'socket'
+  #   include Socket::Constants
+  #   socket = Socket.new(AF_INET, SOCK_STREAM, 0)
+  #   sockaddr = Socket.sockaddr_in(80, 'www.google.com')
+  #   begin # emulate blocking connect
+  #     socket.connect_nonblock(sockaddr)
+  #   rescue IO::WaitWritable
+  #     IO.select(nil, [socket]) # wait 3-way handshake completion
+  #     begin
+  #       socket.connect_nonblock(sockaddr) # check connection failure
+  #     rescue Errno::EISCONN
+  #     end
+  #   end
+  #   socket.write("GET / HTTP/1.0\r\n\r\n")
+  #   results = socket.read
+  #
+  # Refer to Socket#connect for the exceptions that may be thrown if the call
+  # to _connect_nonblock_ fails.
+  #
+  # Socket#connect_nonblock may raise any error corresponding to connect(2) failure,
+  # including Errno::EINPROGRESS.
+  #
+  # If the exception is Errno::EINPROGRESS,
+  # it is extended by IO::WaitWritable.
+  # So IO::WaitWritable can be used to rescue the exceptions for retrying connect_nonblock.
+  #
+  # By specifying `exception: false`, the options hash allows you to indicate
+  # that connect_nonblock should not raise an IO::WaitWritable exception, but
+  # return the symbol :wait_writable instead.
+  #
+  # === See
+  #  # Socket#connect
+  def connect_nonblock(addr, exception: true)
+    __connect_nonblock(addr, exception)
+  end
 end
 
 class UDPSocket < IPSocket